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

Defines

ADBC

struct AdbcError

#include <adbc.h>

A detailed error message for an operation.

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.

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*, 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*)