Classes
struct	AdbcConnectionProfile
	Abstract interface for connection profile providers. More...

Typedefs
typedef AdbcStatusCode(*	AdbcConnectionProfileProvider) (const char profile_name, const char additional_search_path_list, struct AdbcConnectionProfile out, struct AdbcError error)
	Common definition for a connection profile provider.

Functions
AdbcStatusCode	AdbcDriverManagerDatabaseSetProfileProvider (struct AdbcDatabase database, AdbcConnectionProfileProvider provider, struct AdbcError error)
	Set a custom connection profile provider for the driver manager.

AdbcStatusCode	AdbcProfileProviderFilesystem (const char profile_name, const char additional_search_path_list, struct AdbcConnectionProfile out, struct AdbcError error)
	Default Filesystem-based profile provider for the driver manager.

Detailed Description

The ADBC driver manager can support "connection profiles" that specify a driver and options to use when connecting. This allows users to specify connection information in a file or environment variable, and have the driver manager load the appropriate driver and set options accordingly.

This allows creating reusable connection configurations for sharing and distribution without needing to hardcode driver names and options in application code. Profiles will be loaded during DatabaseInit before attempting to initialize the driver. Any options specified by the profile will be applied but will not override options that have already been set using DatabaseSetOption.

To facilitate customization, we define an interface for implementing a Connection Profile object along with a provider function definition which can be set into the driver manager to allow for customized profile loading.

A profile can be specified to the Driver Manager in one of two ways, which will invoke the profile provider during the call to DatabaseInit:

The "profile" option can be set using DatabaseSetOption with the name of the profile to load.
The "uri" being used can have the form "profile://<profile>"

Class Documentation

◆ AdbcConnectionProfile

struct AdbcConnectionProfile

Abstract interface for connection profile providers.

Public Attributes
void *	private_data
	Opaque implementation-defined state. This field is NULL if the profile is uninitialized/freed (but it need not have a value even if the profile is initialized).

void(*	release )(struct AdbcConnectionProfile *profile)
	Release the profile and perform any cleanup.

AdbcStatusCode(*	GetDriverName )(struct AdbcConnectionProfile profile, const char driver_name, AdbcDriverInitFunc init_func, struct AdbcError *error)
	Get the driver to use as specified by this profile.

AdbcStatusCode(*	GetOptions )(struct AdbcConnectionProfile profile, const char keys, const char values, size_t num_options, struct AdbcError *error)
	Get the string options specified by the profile.

AdbcStatusCode(*	GetIntOptions )(struct AdbcConnectionProfile profile, const char keys, const int64_t values, size_t num_options, struct AdbcError error)
	Get the integer options specified by the profile.

AdbcStatusCode(*	GetDoubleOptions )(struct AdbcConnectionProfile profile, const char keys, const double values, size_t num_options, struct AdbcError error)
	Get the double options specified by the profile.

Member Data Documentation

◆ GetDoubleOptions

AdbcStatusCode(* AdbcConnectionProfile::GetDoubleOptions) (struct AdbcConnectionProfile *profile, const char ***keys, const double **values, size_t *num_options, struct AdbcError *error)

Get the double options specified by the profile.

The keys and values returned by this function are owned by the profile object itself and do not need to be freed or managed by the caller. They must not be accessed after calling release on the profile.

Values returned by this function will be set using the DatabaseSetOptionDouble function on the database object being initialized. If the driver does not support the DatabaseSetOptionDouble function, then options should only be returned as strings.

Parameters

[in]	profile	The profile to query.
[out]	keys	The keys of the options specified by the profile.
[out]	values	The values of the options specified by the profile.
[out]	num_options	The number of options specified by the profile, consumers must not access keys or values beyond this count.
[out]	error	An optional location to return an error message

◆ GetDriverName

AdbcStatusCode(* AdbcConnectionProfile::GetDriverName) (struct AdbcConnectionProfile *profile, const char **driver_name, AdbcDriverInitFunc *init_func, struct AdbcError *error)

Get the driver to use as specified by this profile.

It is not required that a profile specify a driver. If the options a driver (if this provides an empty string or nullptr then the driver must be defined by other means, e.g. by the driver / uri options).

Parameters

[in]	profile	The profile to query.
[out]	driver_name	The name of the driver to use, or NULL if not specified.
[out]	init_func	The init function to use for the driver, or NULL if not specified.
[out]	error	An optional location to return an error message

◆ GetIntOptions

AdbcStatusCode(* AdbcConnectionProfile::GetIntOptions) (struct AdbcConnectionProfile *profile, const char ***keys, const int64_t **values, size_t *num_options, struct AdbcError *error)

Get the integer options specified by the profile.

The keys and values returned by this function are owned by the profile object itself and do not need to be freed or managed by the caller. They must not be accessed after calling release on the profile.

Values returned by this function will be set using the DatabaseSetOptionInt function on the database object being initialized. If the driver does not support the DatabaseSetOptionInt function, then options should only be returned as strings.

Parameters

[in]	profile	The profile to query.
[out]	keys	The keys of the options specified by the profile.
[out]	values	The values of the options specified by the profile.
[out]	num_options	The number of options specified by the profile, consumers must not access keys or values beyond this count.
[out]	error	An optional location to return an error message

◆ GetOptions

AdbcStatusCode(* AdbcConnectionProfile::GetOptions) (struct AdbcConnectionProfile *profile, const char ***keys, const char ***values, size_t *num_options, struct AdbcError *error)

Get the string options specified by the profile.

The keys and values returned by this function are owned by the profile object itself and do not need to be freed or managed by the caller. They must not be accessed after calling release on the profile.

The profile can also indicate that a value should be pulled from the environment by having a value in the form env_var(ENV_VAR_NAME). If the driver manager encounters a value of this form, it will replace it with the actual value of the environment variable ENV_VAR_NAME before setting the option. This is only valid for option values not keys.

Parameters

[in]	profile	The profile to query.
[out]	keys	The keys of the options specified by the profile.
[out]	values	The values of the options specified by the profile.
[out]	num_options	The number of options specified by the profile, consumers must not access keys or values beyond this count.
[out]	error	An optional location to return an error message

◆ private_data

void* AdbcConnectionProfile::private_data

Opaque implementation-defined state. This field is NULL if the profile is uninitialized/freed (but it need not have a value even if the profile is initialized).

◆ release

void(* AdbcConnectionProfile::release) (struct AdbcConnectionProfile *profile)

Release the profile and perform any cleanup.

Typedef Documentation

◆ AdbcConnectionProfileProvider

typedef AdbcStatusCode(* AdbcConnectionProfileProvider) (const char *profile_name, const char *additional_search_path_list, struct AdbcConnectionProfile *out, struct AdbcError *error)

Common definition for a connection profile provider.

Parameters

[in]	profile_name	The name of the profile to load. This is the value of the "profile" option or the profile specified in the URI.
[in]	additional_search_path_list	A list of additional paths to search for profiles, delimited by the OS specific path list separator.
[out]	out	The profile to return. The caller will take ownership of the profile and is responsible for calling release on it when finished.
[out]	error	An optional location to return an error message if necessary.

Function Documentation

◆ AdbcDriverManagerDatabaseSetProfileProvider()

AdbcStatusCode AdbcDriverManagerDatabaseSetProfileProvider	(	struct AdbcDatabase *	database,
		AdbcConnectionProfileProvider	provider,
		struct AdbcError *	error )

Set a custom connection profile provider for the driver manager.

If no provider is set, the driver manager will use a default, filesystem-based provider which will look for profiles in the following locations if not given an absolute path to a file:

The environment variable ADBC_PROFILE_PATH, which is a list of paths to search for profiles.
The user-level configuration directory (e.g. ~/.config/adbc/profiles on Linux).

The filesystem-based profile looks for a file named <profile_name>.toml if there is no extension provided, attempting to parse the toml file for the profile information. If the file is found and parsed successfully, the options specified in the profile which have not already been set will be set as if by DatabaseSetOption just before initialization as part of DatabaseInit.

For file-based profiles the expected format is as follows:

version = 1
driver = "driver_name"
 
[options]
option1 = "value1"
option2 = 42
option3 = 3.14

Boolean options will be converted to string equivalents of "true" or "false".

Parameters

[in]	database	The database to set the profile provider for.
[in]	provider	The profile provider to use. If NULL, the default filesystem-based provider will be used if a profile is needed.
[out]	error	An optional location to return an error message if necessary

◆ AdbcProfileProviderFilesystem()

AdbcStatusCode AdbcProfileProviderFilesystem	(	const char *	profile_name,
		const char *	additional_search_path_list,
		struct AdbcConnectionProfile *	out,
		struct AdbcError *	error )

Default Filesystem-based profile provider for the driver manager.

We expose this so that consumers would be able to write a provider that falls back on the default filesystem-based provider if their custom provider fails to find a profile. This allows for more flexible provider implementations that can still leverage the default behavior when needed.

Classes

Typedefs

Functions

Detailed Description

Class Documentation

◆ AdbcConnectionProfile

Public Attributes

Member Data Documentation

◆ GetDoubleOptions

◆ GetDriverName

◆ GetIntOptions

◆ GetOptions

◆ private_data

◆ release

Typedef Documentation

◆ AdbcConnectionProfileProvider

Function Documentation

◆ AdbcDriverManagerDatabaseSetProfileProvider()

◆ AdbcProfileProviderFilesystem()