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    ((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.
#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
ADBC_EXPORT int	AdbcErrorGetDetailCount (const struct AdbcError *error)
	Get the number of metadata values available in an error.
ADBC_EXPORT struct AdbcErrorDetail	AdbcErrorGetDetail (const struct AdbcError *error, int index)
	Get a metadata value in an error by index.
ADBC_EXPORT 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.

Macro Definition Documentation

ADBC_STATUS_UNKNOWN

#define ADBC_STATUS_UNKNOWN   1

An unknown error occurred.

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_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_ALREADY_EXISTS

#define ADBC_STATUS_ALREADY_EXISTS   4

A requested resource already exists.

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_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_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_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_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_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_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_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_ERROR_INIT

#define ADBC_ERROR_INIT    ((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

                        {NULL, ADBC_ERROR_VENDOR_CODE_PRIVATE_DATA, {0, 0, 0, 0, 0}, NULL, NULL, NULL})

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

Function Documentation

AdbcErrorGetDetailCount()

ADBC_EXPORT int AdbcErrorGetDetailCount

(

const struct AdbcError *

error

)

Get the number of metadata values available in an error.

Since

ADBC API revision 1.1.0

AdbcErrorGetDetail()

ADBC_EXPORT 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

Here is the call graph for this function:

AdbcErrorFromArrayStream()

ADBC_EXPORT 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