Connection Establishment

Topics
	Metadata
	Partitioned Results
	Transaction Semantics

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

Functions
AdbcStatusCode	AdbcConnectionNew (struct AdbcConnection *connection, struct AdbcError *error)
	Allocate a new (but uninitialized) connection.
AdbcStatusCode	AdbcConnectionSetOption (struct AdbcConnection *connection, const char *key, const char *value, struct AdbcError *error)
	Set a char* option.
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.
AdbcStatusCode	AdbcConnectionSetOptionInt (struct AdbcConnection *connection, const char *key, int64_t value, struct AdbcError *error)
	Set an integer option.
AdbcStatusCode	AdbcConnectionSetOptionDouble (struct AdbcConnection *connection, const char *key, double value, struct AdbcError *error)
	Set a double option.
AdbcStatusCode	AdbcConnectionInit (struct AdbcConnection *connection, struct AdbcDatabase *database, struct AdbcError *error)
	Finish setting options and initialize the connection.
AdbcStatusCode	AdbcConnectionRelease (struct AdbcConnection *connection, struct AdbcError *error)
	Destroy this connection.
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.

---

Class Documentation

AdbcConnection

struct AdbcConnection

An active database connection.

Provides methods for query execution, managing prepared statements, using transactions, and so on.

Connections are not required to be thread-safe, but they can be used from multiple threads so long as clients take care to serialize accesses to a connection.

Public Attributes
void *	private_data
	Opaque implementation-defined state. This field is NULLPTR iff the connection is unintialized/freed.
struct AdbcDriver *	private_driver
	The associated driver (used by the driver manager to help track state).

Member Data Documentation

private_data

void* AdbcConnection::private_data

Opaque implementation-defined state. This field is NULLPTR iff the connection is unintialized/freed.

private_driver

struct AdbcDriver* AdbcConnection::private_driver

The associated driver (used by the driver manager to help track state).

Function Documentation

AdbcConnectionCancel()

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.

AdbcConnectionInit()

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.

AdbcConnectionNew()

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.

AdbcConnectionRelease()

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.

AdbcConnectionSetOption()

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()

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

AdbcConnectionSetOptionDouble()

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

AdbcConnectionSetOptionInt()

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