Database Initialization

Classes
struct	AdbcDatabase
	An instance of a database. More...

Functions
ADBC_EXPORT AdbcStatusCode	AdbcDatabaseNew (struct AdbcDatabase *database, struct AdbcError *error)
	Allocate a new (but uninitialized) database.
ADBC_EXPORT AdbcStatusCode	AdbcDatabaseGetOption (struct AdbcDatabase *database, const char *key, char *value, size_t *length, struct AdbcError *error)
	Get a string option of the database.
ADBC_EXPORT AdbcStatusCode	AdbcDatabaseGetOptionBytes (struct AdbcDatabase *database, const char *key, uint8_t *value, size_t *length, struct AdbcError *error)
	Get a bytestring option of the database.
ADBC_EXPORT AdbcStatusCode	AdbcDatabaseGetOptionDouble (struct AdbcDatabase *database, const char *key, double *value, struct AdbcError *error)
	Get a double option of the database.
ADBC_EXPORT AdbcStatusCode	AdbcDatabaseGetOptionInt (struct AdbcDatabase *database, const char *key, int64_t *value, struct AdbcError *error)
	Get an integer option of the database.
ADBC_EXPORT AdbcStatusCode	AdbcDatabaseSetOption (struct AdbcDatabase *database, const char *key, const char *value, struct AdbcError *error)
	Set a char* option.
ADBC_EXPORT AdbcStatusCode	AdbcDatabaseSetOptionBytes (struct AdbcDatabase *database, const char *key, const uint8_t *value, size_t length, struct AdbcError *error)
	Set a bytestring option on a database.
ADBC_EXPORT AdbcStatusCode	AdbcDatabaseSetOptionDouble (struct AdbcDatabase *database, const char *key, double value, struct AdbcError *error)
	Set a double option on a database.
ADBC_EXPORT AdbcStatusCode	AdbcDatabaseSetOptionInt (struct AdbcDatabase *database, const char *key, int64_t value, struct AdbcError *error)
	Set an integer option on a database.
ADBC_EXPORT AdbcStatusCode	AdbcDatabaseInit (struct AdbcDatabase *database, struct AdbcError *error)
	Finish setting options and initialize the database.
ADBC_EXPORT AdbcStatusCode	AdbcDatabaseRelease (struct AdbcDatabase *database, struct AdbcError *error)
	Destroy this database. No connections may exist.

Detailed Description

Clients first initialize a database, then create a connection (below). This gives the implementation a place to initialize and own any common connection state. For example, in-memory databases can place ownership of the actual database in this object.

Function Documentation

AdbcDatabaseNew()

ADBC_EXPORT AdbcStatusCode AdbcDatabaseNew	(	struct AdbcDatabase *	database,
		struct AdbcError *	error
	)

Allocate a new (but uninitialized) database.

Callers pass in a zero-initialized AdbcDatabase.

Drivers should allocate their internal data structure and set the private_data field to point to the newly allocated struct. This struct should be released when AdbcDatabaseRelease is called.

AdbcDatabaseGetOption()

ADBC_EXPORT AdbcStatusCode AdbcDatabaseGetOption	(	struct AdbcDatabase *	database,
		const char *	key,
		char *	value,
		size_t *	length,
		struct AdbcError *	error
	)

Get a string option of the database.

This must always be thread-safe (other operations are not), though given the semantics here, it is not recommended to call GetOption concurrently with itself.

length must be provided and must be the size of the buffer pointed to by value. If there is sufficient space, the driver will copy the option value (including the null terminator) to buffer and set length to the size of the actual value. If the buffer is too small, no data will be written and length will be set to the required length.

In other words:

• If output length <= input length, value will contain a value with length bytes.
• If output length > input length, nothing has been written to value.

For standard options, drivers must always support getting the option value (if they support getting option values at all) via the type specified in the option. (For example, an option set via SetOptionDouble must be retrievable via GetOptionDouble.) Drivers may also support getting a converted option value via other getters if needed. (For example, getting the string representation of a double option.)

Since

ADBC API revision 1.1.0

Parameters

[in]	database	The database.
[in]	key	The option to get.
[out]	value	The option value.
[in,out]	length	The length of value.
[out]	error	An optional location to return an error message if necessary.

Returns

ADBC_STATUS_NOT_FOUND if the option is not recognized.

AdbcDatabaseGetOptionBytes()

ADBC_EXPORT AdbcStatusCode AdbcDatabaseGetOptionBytes	(	struct AdbcDatabase *	database,
		const char *	key,
		uint8_t *	value,
		size_t *	length,
		struct AdbcError *	error
	)

Get a bytestring option of the database.

This must always be thread-safe (other operations are not), though given the semantics here, it is not recommended to call GetOptionBytes concurrently with itself.

length must be provided and must be the size of the buffer pointed to by value. If there is sufficient space, the driver will copy the option value to buffer and set length to the size of the actual value. If the buffer is too small, no data will be written and length will be set to the required length.

In other words:

• If output length <= input length, value will contain a value with length bytes.
• If output length > input length, nothing has been written to value.

For standard options, drivers must always support getting the option value (if they support getting option values at all) via the type specified in the option. (For example, an option set via SetOptionDouble must be retrievable via GetOptionDouble.) Drivers may also support getting a converted option value via other getters if needed. (For example, getting the string representation of a double option.)

Since

ADBC API revision 1.1.0

Parameters

[in]	database	The database.
[in]	key	The option to get.
[out]	value	The option value.
[in,out]	length	The option value length.
[out]	error	An optional location to return an error message if necessary.

Returns

ADBC_STATUS_NOT_FOUND if the option is not recognized.

AdbcDatabaseGetOptionDouble()

ADBC_EXPORT AdbcStatusCode AdbcDatabaseGetOptionDouble	(	struct AdbcDatabase *	database,
		const char *	key,
		double *	value,
		struct AdbcError *	error
	)

Get a double option of the database.

This must always be thread-safe (other operations are not).

For standard options, drivers must always support getting the option value (if they support getting option values at all) via the type specified in the option. (For example, an option set via SetOptionDouble must be retrievable via GetOptionDouble.) Drivers may also support getting a converted option value via other getters if needed. (For example, getting the double representation of an integer option.)

Since

ADBC API revision 1.1.0

Parameters

[in]	database	The database.
[in]	key	The option to get.
[out]	value	The option value.
[out]	error	An optional location to return an error message if necessary.

Returns

ADBC_STATUS_NOT_FOUND if the option is not recognized.

AdbcDatabaseGetOptionInt()

ADBC_EXPORT AdbcStatusCode AdbcDatabaseGetOptionInt	(	struct AdbcDatabase *	database,
		const char *	key,
		int64_t *	value,
		struct AdbcError *	error
	)

Get an integer option of the database.

This must always be thread-safe (other operations are not).

For standard options, drivers must always support getting the option value (if they support getting option values at all) via the type specified in the option. (For example, an option set via SetOptionDouble must be retrievable via GetOptionDouble.) Drivers may also support getting a converted option value via other getters if needed. (For example, getting the integer representation of a double option.)

Since

ADBC API revision 1.1.0

Parameters

[in]	database	The database.
[in]	key	The option to get.
[out]	value	The option value.
[out]	error	An optional location to return an error message if necessary.

Returns

ADBC_STATUS_NOT_FOUND if the option is not recognized.

AdbcDatabaseSetOption()

ADBC_EXPORT AdbcStatusCode AdbcDatabaseSetOption	(	struct AdbcDatabase *	database,
		const char *	key,
		const char *	value,
		struct AdbcError *	error
	)

Set a char* option.

Options may be set before AdbcDatabaseInit. Some drivers may support setting options after initialization as well.

Parameters

[in]	database	The database.
[in]	key	The option to set.
[in]	value	The option value.
[out]	error	An optional location to return an error message if necessary.

Returns

ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized

AdbcDatabaseSetOptionBytes()

ADBC_EXPORT AdbcStatusCode AdbcDatabaseSetOptionBytes	(	struct AdbcDatabase *	database,
		const char *	key,
		const uint8_t *	value,
		size_t	length,
		struct AdbcError *	error
	)

Set a bytestring option on a database.

Since

ADBC API revision 1.1.0

Parameters

[in]	database	The database.
[in]	key	The option to set.
[in]	value	The option value.
[in]	length	The option value length.
[out]	error	An optional location to return an error message if necessary.

Returns

ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized

AdbcDatabaseSetOptionDouble()

ADBC_EXPORT AdbcStatusCode AdbcDatabaseSetOptionDouble	(	struct AdbcDatabase *	database,
		const char *	key,
		double	value,
		struct AdbcError *	error
	)

Set a double option on a database.

Since

ADBC API revision 1.1.0

Parameters

[in]	database	The database.
[in]	key	The option to set.
[in]	value	The option value.
[out]	error	An optional location to return an error message if necessary.

Returns

ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized

AdbcDatabaseSetOptionInt()

ADBC_EXPORT AdbcStatusCode AdbcDatabaseSetOptionInt	(	struct AdbcDatabase *	database,
		const char *	key,
		int64_t	value,
		struct AdbcError *	error
	)

Set an integer option on a database.

Since

ADBC API revision 1.1.0

Parameters

[in]	database	The database.
[in]	key	The option to set.
[in]	value	The option value.
[out]	error	An optional location to return an error message if necessary.

Returns

ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized

AdbcDatabaseInit()

ADBC_EXPORT AdbcStatusCode AdbcDatabaseInit	(	struct AdbcDatabase *	database,
		struct AdbcError *	error
	)

Finish setting options and initialize the database.

Some drivers may support setting options after initialization as well.

AdbcDatabaseRelease()

ADBC_EXPORT AdbcStatusCode AdbcDatabaseRelease	(	struct AdbcDatabase *	database,
		struct AdbcError *	error
	)

Destroy this database. No connections may exist.

Parameters

[in]	database	The database to release.
[out]	error	An optional location to return an error message if necessary.