Error Handling

Classes
struct	AdbcError
	A detailed error message for an operation. More...
struct	AdbcErrorDetail
	Extra key-value metadata for an error. More...

Macros
#define	ADBC_STATUS_OK   0
	No error.
#define	ADBC_STATUS_UNKNOWN   1
	An unknown error occurred.
#define	ADBC_STATUS_NOT_IMPLEMENTED   2
	The operation is not implemented or supported.
#define	ADBC_STATUS_NOT_FOUND   3
	A requested resource was not found.
#define	ADBC_STATUS_ALREADY_EXISTS   4
	A requested resource already exists.
#define	ADBC_STATUS_INVALID_ARGUMENT   5
	The arguments are invalid, likely a programming error.
#define	ADBC_STATUS_INVALID_STATE   6
	The preconditions for the operation are not met, likely a programming error.
#define	ADBC_STATUS_INVALID_DATA   7
	Invalid data was processed (not a programming error).
#define	ADBC_STATUS_INTEGRITY   8
	The database's integrity was affected.
#define	ADBC_STATUS_INTERNAL   9
	An error internal to the driver or database occurred.
#define	ADBC_STATUS_IO   10
	An I/O error occurred.
#define	ADBC_STATUS_CANCELLED   11
	The operation was cancelled, not due to a timeout.
#define	ADBC_STATUS_TIMEOUT   12
	The operation was cancelled due to a timeout.
#define	ADBC_STATUS_UNAUTHENTICATED   13
	Authentication failed.
#define	ADBC_STATUS_UNAUTHORIZED   14
	The client is not authorized to perform the given operation.
#define	ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA   INT32_MIN
	Inform the driver/driver manager that we are using the extended AdbcError struct from ADBC 1.1.0.
#define	ADBC_ERROR_INIT
	A helper to initialize the full AdbcError structure.
#define	ADBC_ERROR_1_0_0_SIZE   (offsetof(struct AdbcError, private_data))
	The size of the AdbcError structure in ADBC 1.0.0.
#define	ADBC_ERROR_1_1_0_SIZE   (sizeof(struct AdbcError))
	The size of the AdbcError structure in ADBC 1.1.0.

Typedefs
typedef uint8_t	AdbcStatusCode
	Error codes for operations that may fail.

Functions
int	AdbcErrorGetDetailCount (const struct AdbcError *error)
	Get the number of metadata values available in an error.
struct AdbcErrorDetail	AdbcErrorGetDetail (const struct AdbcError *error, int index)
	Get a metadata value in an error by index.
const struct AdbcError *	AdbcErrorFromArrayStream (struct ArrowArrayStream *stream, AdbcStatusCode *status)
	Get an ADBC error from an ArrowArrayStream created by a driver.

Detailed Description

ADBC uses integer error codes to signal errors. To provide more detail about errors, functions may also return an AdbcError via an optional out parameter, which can be inspected. If provided, it is the responsibility of the caller to zero-initialize the AdbcError value.

---

Class Documentation

AdbcError

struct AdbcError

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 Attributes
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.
void *	private_data
	Opaque implementation-defined state.
struct AdbcDriver *	private_driver
	The associated driver (used by the driver manager to help track state).

Member Data Documentation

message

char* AdbcError::message

The error message.

private_data

void* AdbcError::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

private_driver

struct AdbcDriver* AdbcError::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

release

void(* AdbcError::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.

sqlstate

char AdbcError::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".

vendor_code

int32_t AdbcError::vendor_code

A vendor-specific error code, if applicable.

AdbcErrorDetail

struct AdbcErrorDetail

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 Attributes
const char *	key
	The metadata key.
const uint8_t *	value
	The binary metadata value.
size_t	value_length
	The length of the metadata value.

Member Data Documentation

key

const char* AdbcErrorDetail::key

The metadata key.

value

const uint8_t* AdbcErrorDetail::value

The binary metadata value.

value_length

size_t AdbcErrorDetail::value_length

The length of the metadata value.

Macro Definition Documentation

ADBC_ERROR_1_0_0_SIZE

#define ADBC_ERROR_1_0_0_SIZE   (offsetof(struct AdbcError, private_data))

The size of the AdbcError structure in ADBC 1.0.0.

Drivers written for ADBC 1.1.0 and later should never touch more than this portion of an AdbcDriver struct when vendor_code is not ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA.

Since

ADBC API revision 1.1.0

ADBC_ERROR_1_1_0_SIZE

#define ADBC_ERROR_1_1_0_SIZE   (sizeof(struct AdbcError))

The size of the AdbcError structure in ADBC 1.1.0.

Drivers written for ADBC 1.1.0 and later should never touch more than this portion of an AdbcDriver struct when vendor_code is ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA.

Since

ADBC API revision 1.1.0

ADBC_ERROR_INIT

#define ADBC_ERROR_INIT

Value:

  ((struct AdbcError){  \
      NULL, ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA, {0, 0, 0, 0, 0}, NULL, NULL, NULL})

A helper to initialize the full AdbcError structure.

Since

ADBC API revision 1.1.0

ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA

#define ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA   INT32_MIN

Inform the driver/driver manager that we are using the extended AdbcError struct from ADBC 1.1.0.

See the AdbcError documentation for usage.

Since

ADBC API revision 1.1.0

ADBC_STATUS_ALREADY_EXISTS

#define ADBC_STATUS_ALREADY_EXISTS   4

A requested resource already exists.

May indicate a driver-side or database-side error.

ADBC_STATUS_CANCELLED

#define ADBC_STATUS_CANCELLED   11

The operation was cancelled, not due to a timeout.

May indicate a driver-side or database-side error.

ADBC_STATUS_INTEGRITY

#define ADBC_STATUS_INTEGRITY   8

The database's integrity was affected.

For instance, a foreign key check may have failed, or a uniqueness constraint may have been violated.

May indicate a database-side error only.

ADBC_STATUS_INTERNAL

#define ADBC_STATUS_INTERNAL   9

An error internal to the driver or database occurred.

May indicate a driver-side or database-side error.

ADBC_STATUS_INVALID_ARGUMENT

#define ADBC_STATUS_INVALID_ARGUMENT   5

The arguments are invalid, likely a programming error.

For instance, they may be of the wrong format, or out of range.

May indicate a driver-side or database-side error.

ADBC_STATUS_INVALID_DATA

#define ADBC_STATUS_INVALID_DATA   7

Invalid data was processed (not a programming error).

For instance, a division by zero may have occurred during query execution.

May indicate a database-side error only.

ADBC_STATUS_INVALID_STATE

#define ADBC_STATUS_INVALID_STATE   6

The preconditions for the operation are not met, likely a programming error.

For instance, the object may be uninitialized, or may have not been fully configured.

May indicate a driver-side or database-side error.

ADBC_STATUS_IO

#define ADBC_STATUS_IO   10

An I/O error occurred.

For instance, a remote service may be unavailable.

May indicate a driver-side or database-side error.

ADBC_STATUS_NOT_FOUND

#define ADBC_STATUS_NOT_FOUND   3

A requested resource was not found.

May indicate a driver-side or database-side error.

ADBC_STATUS_NOT_IMPLEMENTED

#define ADBC_STATUS_NOT_IMPLEMENTED   2

The operation is not implemented or supported.

May indicate a driver-side or database-side error.

ADBC_STATUS_OK

#define ADBC_STATUS_OK   0

No error.

ADBC_STATUS_TIMEOUT

#define ADBC_STATUS_TIMEOUT   12

The operation was cancelled due to a timeout.

May indicate a driver-side or database-side error.

ADBC_STATUS_UNAUTHENTICATED

#define ADBC_STATUS_UNAUTHENTICATED   13

Authentication failed.

May indicate a database-side error only.

ADBC_STATUS_UNAUTHORIZED

#define ADBC_STATUS_UNAUTHORIZED   14

The client is not authorized to perform the given operation.

May indicate a database-side error only.

ADBC_STATUS_UNKNOWN

#define ADBC_STATUS_UNKNOWN   1

An unknown error occurred.

May indicate a driver-side or database-side error.

Typedef Documentation

AdbcStatusCode

typedef uint8_t AdbcStatusCode

Error codes for operations that may fail.

Function Documentation

AdbcErrorFromArrayStream()

const struct AdbcError * AdbcErrorFromArrayStream	(	struct ArrowArrayStream *	stream,
		AdbcStatusCode *	status )

Get an ADBC error from an ArrowArrayStream created by a driver.

This allows retrieving error details and other metadata that would normally be suppressed by the Arrow C Stream Interface.

The caller MUST NOT release the error; it is managed by the release callback in the stream itself.

Parameters

[in]	stream	The stream to query.
[out]	status	The ADBC status code, or ADBC_STATUS_OK if there is no error. Not written to if the stream does not contain an ADBC error or if the pointer is NULL.

Returns

NULL if not supported.

Since

ADBC API revision 1.1.0

AdbcErrorGetDetail()

struct AdbcErrorDetail AdbcErrorGetDetail	(	const struct AdbcError *	error,
		int	index )

Get a metadata value in an error by index.

If index is invalid, returns an AdbcErrorDetail initialized with NULL/0 fields.

Since

ADBC API revision 1.1.0

AdbcErrorGetDetailCount()

int AdbcErrorGetDetailCount

(

const struct AdbcError *

error

)

Get the number of metadata values available in an error.

Since

ADBC API revision 1.1.0