Connection.from_string

Opens a connection given a provider ID and a connection string.

This allows applications to open connections without having to create a data source (DSN) in the configuration. The format of cnc_string is similar to PostgreSQL and MySQL connection strings. It is a semicolumn-separated series of <key>= <value> pairs, where each key and value are encoded as per RFC 1738, see rfc1738_encode for more information.

The possible keys depend on the provider, the "gda-sql-6.0 -L" command can be used to list the actual keys for each installed database provider.

For example the connection string to open an SQLite connection to a database file named "my_data.db" in the current directory would be <constant>"DB_DIR=.;DB_NAME=my_data"</constant>.

The cnc_string string must have the following format: "[&lt;provider&gt;://][&lt;username&gt;[:& lt;password&gt;]@]&lt;connection_params&gt;" (if &lt;username&gt; and/or &lt;password&gt; are provided, and auth_string is null, then these username and passwords will be used, and if & lt;provider&gt; is provided and provider_name is null then this provider will be used). Note that if provided, &lt;username&gt;, &lt;password&gt; and &lt;provider&gt; must be encoded as per RFC 1738, see rfc1738_encode for more information.

The auth_string must contain the authentication information for the server to accept the connection. It is a string containing semi-colon seperated named values, usually like "USERNAME=...;PASSWORD=..." where the ... are replaced by actual values. Note that each name and value must be encoded as per RFC 1738, see rfc1738_encode for more information.

The actual named parameters required depend on the provider being used, and that list is available as the <parameter>auth_params </parameter> member of the ProviderInfo structure for each installed provider (use get_provider_info to get it). Similarly to the format of the connection string, use the "gda-sql-6.0 -L" command to list the possible named parameters.

Additionally, it is possible to have the connection string respect the "&lt;provider_name&gt;://&lt;real cnc string&gt;" format, in which case the provider name and the real connection string will be extracted from that string (note that if provider_name is not null then it will still be used as the provider ID).\

This method may fail with a GDA_CONNECTION_ERROR domain error (see the ConnectionError error codes) or a gda_config_error domain error (see the ConfigError error codes).

The returned connection is not yet opened, you need to call open or open_async.

Parameters:

Returns: