Connection Establishment

Collaboration diagram for Connection Establishment:

Modules
	Metadata
	Partitioned Results
	Transaction Semantics

Classes
struct	AdbcConnection
	An active database connection. More...

Functions
ADBC_EXPORT AdbcStatusCode	AdbcConnectionNew (struct AdbcConnection *connection, struct AdbcError *error)
	Allocate a new (but uninitialized) connection.
ADBC_EXPORT AdbcStatusCode	AdbcConnectionSetOption (struct AdbcConnection *connection, const char *key, const char *value, struct AdbcError *error)
	Set a char* option.
ADBC_EXPORT AdbcStatusCode	AdbcConnectionSetOptionBytes (struct AdbcConnection *connection, const char *key, const uint8_t *value, size_t length, struct AdbcError *error)
	Set a bytestring option on a connection.
ADBC_EXPORT AdbcStatusCode	AdbcConnectionSetOptionInt (struct AdbcConnection *connection, const char *key, int64_t value, struct AdbcError *error)
	Set an integer option.
ADBC_EXPORT AdbcStatusCode	AdbcConnectionSetOptionDouble (struct AdbcConnection *connection, const char *key, double value, struct AdbcError *error)
	Set a double option.
ADBC_EXPORT AdbcStatusCode	AdbcConnectionInit (struct AdbcConnection *connection, struct AdbcDatabase *database, struct AdbcError *error)
	Finish setting options and initialize the connection.
ADBC_EXPORT AdbcStatusCode	AdbcConnectionRelease (struct AdbcConnection *connection, struct AdbcError *error)
	Destroy this connection.
ADBC_EXPORT AdbcStatusCode	AdbcConnectionCancel (struct AdbcConnection *connection, struct AdbcError *error)
	Cancel the in-progress operation on a connection.

Detailed Description

Functions for creating, using, and releasing database connections.

Function Documentation

AdbcConnectionNew()

ADBC_EXPORT AdbcStatusCode AdbcConnectionNew	(	struct AdbcConnection *	connection,
		struct AdbcError *	error
	)

Allocate a new (but uninitialized) connection.

Callers pass in a zero-initialized AdbcConnection.

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 AdbcConnectionRelease is called.

AdbcConnectionSetOption()

ADBC_EXPORT AdbcStatusCode AdbcConnectionSetOption	(	struct AdbcConnection *	connection,
		const char *	key,
		const char *	value,
		struct AdbcError *	error
	)

Set a char* option.

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

Parameters

[in]	connection	The database connection.
[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

AdbcConnectionSetOptionBytes()

ADBC_EXPORT AdbcStatusCode AdbcConnectionSetOptionBytes	(	struct AdbcConnection *	connection,
		const char *	key,
		const uint8_t *	value,
		size_t	length,
		struct AdbcError *	error
	)

Set a bytestring option on a connection.

Since

ADBC API revision 1.1.0

Parameters

[in]	connection	The connection.
[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

AdbcConnectionSetOptionInt()

ADBC_EXPORT AdbcStatusCode AdbcConnectionSetOptionInt	(	struct AdbcConnection *	connection,
		const char *	key,
		int64_t	value,
		struct AdbcError *	error
	)

Set an integer option.

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

Since

ADBC API revision 1.1.0

Parameters

[in]	connection	The database connection.
[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

AdbcConnectionSetOptionDouble()

ADBC_EXPORT AdbcStatusCode AdbcConnectionSetOptionDouble	(	struct AdbcConnection *	connection,
		const char *	key,
		double	value,
		struct AdbcError *	error
	)

Set a double option.

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

Since

ADBC API revision 1.1.0

Parameters

[in]	connection	The database connection.
[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

AdbcConnectionInit()

ADBC_EXPORT AdbcStatusCode AdbcConnectionInit	(	struct AdbcConnection *	connection,
		struct AdbcDatabase *	database,
		struct AdbcError *	error
	)

Finish setting options and initialize the connection.

Some drivers may support setting options after initialization as well.

AdbcConnectionRelease()

ADBC_EXPORT AdbcStatusCode AdbcConnectionRelease	(	struct AdbcConnection *	connection,
		struct AdbcError *	error
	)

Destroy this connection.

Parameters

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

AdbcConnectionCancel()

ADBC_EXPORT AdbcStatusCode AdbcConnectionCancel	(	struct AdbcConnection *	connection,
		struct AdbcError *	error
	)

Cancel the in-progress operation on a connection.

This can be called during AdbcConnectionGetObjects (or similar), or while consuming an ArrowArrayStream returned from such. Calling this function should make the other functions return ADBC_STATUS_CANCELLED (from ADBC functions) or ECANCELED (from methods of ArrowArrayStream). (It is not guaranteed to, for instance, the result set may be buffered in memory already.)

This must always be thread-safe (other operations are not). It is not necessarily signal-safe.

Since

ADBC API revision 1.1.0

Parameters

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

Returns

ADBC_STATUS_INVALID_STATE if there is no operation to cancel.

ADBC_STATUS_UNKNOWN if the operation could not be cancelled.