Connection properties of a provider (reference)

A provider describes the settings of its connection as individual properties. An administration program shows input fields for them instead of a free-text field for the connection string. The provider itself puts the connection string together and checks it.

Read the description:

GET /admin/v1/odata/Providers?$filter=Usable eq true and Latest eq true
GET /admin/v1/odata/ProviderProperties?$filter=Provider eq 'sqlserver' and Language eq 'en'&$orderby=Scope,Position

Create a data source from properties; ConnectionProperties is a JSON object as text:

POST /admin/v1/odata/DataSources
Content-Type: application/json
 
{ "Name": "fachdaten", "Provider": "sqlserver",
  "ConnectionProperties": "{\"Data Source\":\"srv01\",\"Initial Catalog\":\"Fachdaten\",\"Integrated Security\":\"true\"}" }

When read, DataSources returns the same form, without secret values:

{ "Name": "fachdaten", "Provider": "sqlserver", "Connection": null,
  "ConnectionProperties": "{\"Data Source\":\"srv01\",\"Initial Catalog\":\"Fachdaten\",\"Integrated Security\":\"true\"}" }

Read-only. One row per installed provider package, usable or not.

Read-only. For each usable package that describes its connection: one row per property, scope, and language.

Reading ProviderProperties loads every usable package that isn't loaded yet: the description is the provider's code.

Provider, ProviderVersion, and ProviderOptions mean the same as in the file; see configuration.

The shipped SQL Server provider describes these properties; it knows no ProviderOptions. The names are the keywords the SQL Server driver writes into a string. Defaults and allowed values come from the driver itself; ProviderProperties is authoritative.

Not offered are settings the service manages itself (Pooling, pool sizes, MultipleActiveResultSets). A string written by hand may contain them; they then don't appear as properties.

Who builds the string. The data source's provider—Provider, otherwise Dialect—puts the string together from the properties and checks it. The administration program needs no knowledge of a database's keywords. The service seals the string like one sent as text.

Writing. The service rejects Connection and ConnectionProperties together with 400, and so a provider without a description (DescribesConnection = false). Values may be JSON strings, numbers, or true/false; null or an empty string removes the property. An unknown property, a missing required value, or a value of the wrong type returns 400; the message names the property, never its value.

Password on update. If a secret property is missing from ConnectionProperties, the service keeps its stored value: whoever changes only the server doesn't type the password again. An explicitly empty value ("Password": "") removes it. All other properties replace the stored connection as a whole; whatever is missing then applies with its default.

Reading. ConnectionProperties holds the set properties of the stored connection, never a secret one. The field stays empty when the provider has no description or can't take apart a string written by hand; the connection can then be changed through Connection. The field isn't part of the row version; the version follows the sealed string.

Change log. ConnectionProperties appears there only as “neu gesetzt” (newly set), like Connection.

An administration program fills the provider selection and a property grid:

1. Read Providers with Usable eq true and Latest eq true and fill the selection (Name, value Id).
2. For the chosen Id, read ProviderProperties with Scope eq 'Connection' and the program's own language, order by Position, group by Category; Choice as a selection, Boolean as a switch, Secret as a password field.
3. When editing, read the data source's ConnectionProperties and fill the fields; the password field stays empty.
4. Save: send only the filled fields as a JSON object in ConnectionProperties, not the empty password field—the stored password then stays.
5. Check with `test-connection`.

• HTTP: administration (reference)
• Service configuration (reference)