adbc.h

ADBC: Arrow Database connectivity

An Arrow-based interface between applications and database drivers. ADBC aims to provide a vendor-independent API for SQL and Substrait-based database access that is targeted at analytics/OLAP use cases.

This API is intended to be implemented directly by drivers and used directly by client applications. To assist portability between different vendors, a “driver manager” library is also provided, which implements this same API, but dynamically loads drivers internally and forwards calls appropriately.

ADBC uses structs with free functions that operate on those structs to model objects.

In general, objects allow serialized access from multiple threads, but not concurrent access. Specific implementations may permit multiple threads.

Version

1.1.0

Defines

ADBC

struct AdbcError

#include <adbc.h>

A detailed error message for an operation.

The caller must zero-initialize this struct (clarified in ADBC 1.1.0).

The structure was extended in ADBC 1.1.0. Drivers and clients using ADBC 1.0.0 will not have the private_data or private_driver fields. Drivers should read/write these fields if and only if vendor_code is equal to ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA. Clients are required to initialize this struct to avoid the possibility of uninitialized values confusing the driver.

Public Members

char *message

The error message.

int32_t vendor_code

A vendor-specific error code, if applicable.

char sqlstate[5]

A SQLSTATE error code, if provided, as defined by the SQL:2003 standard. If not set, it should be set to “\0\0\0\0\0”.

void (*release)(struct AdbcError *error)

Release the contained error.

Unlike other structures, this is an embedded callback to make it easier for the driver manager and driver to cooperate.

void *private_data

Opaque implementation-defined state.

This field may not be used unless vendor_code is ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA. If present, this field is NULLPTR iff the error is unintialized/freed.

Since

ADBC API revision 1.1.0

struct AdbcDriver *private_driver

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

This field may not be used unless vendor_code is ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA.

Since

ADBC API revision 1.1.0

struct AdbcErrorDetail

#include <adbc.h>

Extra key-value metadata for an error.

The fields here are owned by the driver and should not be freed. The fields here are invalidated when the release callback in AdbcError is called.

Since

ADBC API revision 1.1.0

Public Members

const char *key

The metadata key.

const uint8_t *value

The binary metadata value.

size_t value_length

The length of the metadata value.

struct AdbcDatabase

#include <adbc.h>

An instance of a database.

Must be kept alive as long as any connections exist.

Public Members

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

struct AdbcConnection

#include <adbc.h>

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 Members

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

struct AdbcStatement

#include <adbc.h>

A container for all state needed to execute a database query, such as the query itself, parameters for prepared statements, driver parameters, etc.

Statements may represent queries or prepared statements.

Statements may be used multiple times and can be reconfigured (e.g. they can be reused to execute multiple different queries). However, executing a statement (and changing certain other state) will invalidate result sets obtained prior to that execution.

Multiple statements may be created from a single connection. However, the driver may block or error if they are used concurrently (whether from a single thread or multiple threads).

Statements 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 statement.

Public Members

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

struct AdbcPartitions

#include <adbc.h>

The partitions of a distributed/partitioned result set.

Public Members

size_t num_partitions

The number of partitions.

const uint8_t **partitions

The partitions of the result set, where each entry (up to num_partitions entries) is an opaque identifier that can be passed to AdbcConnectionReadPartition.

const size_t *partition_lengths

The length of each corresponding entry in partitions.

void *private_data

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

void (*release)(struct AdbcPartitions *partitions)

Release the contained partitions.

Unlike other structures, this is an embedded callback to make it easier for the driver manager and driver to cooperate.

struct AdbcDriver

#include <adbc.h>

An instance of an initialized database driver.

This provides a common interface for vendor-specific driver initialization routines. Drivers should populate this struct, and applications can call ADBC functions through this struct, without worrying about multiple definitions of the same symbol.

Public Members

void *private_data

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

void *private_manager

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

AdbcStatusCode (*release)(struct AdbcDriver *driver, struct AdbcError *error)

Release the driver and perform any cleanup.

This is an embedded callback to make it easier for the driver manager and driver to cooperate.

AdbcStatusCode (*DatabaseInit)(struct AdbcDatabase*, struct AdbcError*)

AdbcStatusCode (*DatabaseNew)(struct AdbcDatabase*, struct AdbcError*)

AdbcStatusCode (*DatabaseSetOption)(struct AdbcDatabase*, const char*, const char*, struct AdbcError*)

AdbcStatusCode (*DatabaseRelease)(struct AdbcDatabase*, struct AdbcError*)

AdbcStatusCode (*ConnectionCommit)(struct AdbcConnection*, struct AdbcError*)

AdbcStatusCode (*ConnectionGetInfo)(struct AdbcConnection*, const uint32_t*, size_t, struct ArrowArrayStream*, struct AdbcError*)

AdbcStatusCode (*ConnectionGetObjects)(struct AdbcConnection*, int, const char*, const char*, const char*, const char**, const char*, struct ArrowArrayStream*, struct AdbcError*)

AdbcStatusCode (*ConnectionGetTableSchema)(struct AdbcConnection*, const char*, const char*, const char*, struct ArrowSchema*, struct AdbcError*)

AdbcStatusCode (*ConnectionGetTableTypes)(struct AdbcConnection*, struct ArrowArrayStream*, struct AdbcError*)

AdbcStatusCode (*ConnectionInit)(struct AdbcConnection*, struct AdbcDatabase*, struct AdbcError*)

AdbcStatusCode (*ConnectionNew)(struct AdbcConnection*, struct AdbcError*)

AdbcStatusCode (*ConnectionSetOption)(struct AdbcConnection*, const char*, const char*, struct AdbcError*)

AdbcStatusCode (*ConnectionReadPartition)(struct AdbcConnection*, const uint8_t*, size_t, struct ArrowArrayStream*, struct AdbcError*)

AdbcStatusCode (*ConnectionRelease)(struct AdbcConnection*, struct AdbcError*)

AdbcStatusCode (*ConnectionRollback)(struct AdbcConnection*, struct AdbcError*)

AdbcStatusCode (*StatementBind)(struct AdbcStatement*, struct ArrowArray*, struct ArrowSchema*, struct AdbcError*)

AdbcStatusCode (*StatementBindStream)(struct AdbcStatement*, struct ArrowArrayStream*, struct AdbcError*)

AdbcStatusCode (*StatementExecuteQuery)(struct AdbcStatement*, struct ArrowArrayStream*, int64_t*, struct AdbcError*)

AdbcStatusCode (*StatementExecutePartitions)(struct AdbcStatement*, struct ArrowSchema*, struct AdbcPartitions*, int64_t*, struct AdbcError*)

AdbcStatusCode (*StatementGetParameterSchema)(struct AdbcStatement*, struct ArrowSchema*, struct AdbcError*)

AdbcStatusCode (*StatementNew)(struct AdbcConnection*, struct AdbcStatement*, struct AdbcError*)

AdbcStatusCode (*StatementPrepare)(struct AdbcStatement*, struct AdbcError*)

AdbcStatusCode (*StatementRelease)(struct AdbcStatement*, struct AdbcError*)

AdbcStatusCode (*StatementSetOption)(struct AdbcStatement*, const char*, const char*, struct AdbcError*)

AdbcStatusCode (*StatementSetSqlQuery)(struct AdbcStatement*, const char*, struct AdbcError*)

AdbcStatusCode (*StatementSetSubstraitPlan)(struct AdbcStatement*, const uint8_t*, size_t, struct AdbcError*)