Skip to content

Commit

Permalink
format: add additional features to 1.1.0 spec
Browse files Browse the repository at this point in the history 
Intends to tackle #736 and #755.
  • Loading branch information
@lidavidm
lidavidm committed Jun 19, 2023
1 parent f18f1cc commit c0486ed
Show file tree
Hide file tree
Showing 2 changed files with 166 additions and 0 deletions.
144 changes: 144 additions & 0 deletions adbc.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -326,6 +326,33 @@ struct ADBC_EXPORT AdbcError {
/// \since ADBC API revision 1.1.0
/// \addtogroup adbc-1.1.0
#define ADBC_OPTION_PASSWORD "password"
/// \brief Canonical option name for error details.
///
/// Should be used as the expected option name to retrieve error
/// details from the driver. This allows drivers to return custom,
/// structured error information (for example, JSON or Protocol
/// Buffers) that can be optionally parsed by clients, beyond the
/// standard AdbcError fields, without having to encode it in the
/// error message. The encoding of the data is driver-defined.
///
/// This can be called immediately after any API call that returns an
/// error. Additionally, if an ArrowArrayStream returned from an
/// AdbcConnection or an AdbcStatement returns an error, this can be
/// immediately called from the associated AdbcConnection or
/// AdbcStatement to get further error details (if available). Making
/// other API calls with that connection or statement may clear this
/// error value.
///
/// Drivers may provide multiple error details. Each call to
/// GetOptionBinary will return the next error detail. The driver
/// should return ADBC_STATUS_NOT_FOUND if there are no (more) error
/// details.
///
/// The type is uint8_t*.
///
/// \since ADBC API revision 1.1.0
/// \addtogroup adbc-1.1.0
#define ADBC_OPTION_ERROR_DETAILS "error_details"

/// \brief The database vendor/product name (e.g. the server name).
/// (type: utf8).
Expand Down Expand Up @@ -811,6 +838,8 @@ struct ADBC_EXPORT AdbcDriver {

AdbcStatusCode (*DatabaseGetOption)(struct AdbcDatabase*, const char*, const char**,
struct AdbcError*);
AdbcStatusCode (*DatabaseGetOptionBytes)(struct AdbcDatabase*, const char*,
const uint8_t**, size_t*, struct AdbcError*);
AdbcStatusCode (*DatabaseGetOptionInt)(struct AdbcDatabase*, const char*, int64_t*,
struct AdbcError*);
AdbcStatusCode (*DatabaseGetOptionDouble)(struct AdbcDatabase*, const char*, double*,
Expand All @@ -820,8 +849,11 @@ struct ADBC_EXPORT AdbcDriver {
AdbcStatusCode (*DatabaseSetOptionDouble)(struct AdbcDatabase*, const char*, double,
struct AdbcError*);

AdbcStatusCode (*ConnectionCancel)(struct AdbcConnection*, struct AdbcError*);
AdbcStatusCode (*ConnectionGetOption)(struct AdbcConnection*, const char*, const char**,
struct AdbcError*);
AdbcStatusCode (*ConnectionGetOptionBytes)(struct AdbcDatabase*, const char*,
const uint8_t**, size_t*, struct AdbcError*);
AdbcStatusCode (*ConnectionGetOptionInt)(struct AdbcConnection*, const char*, int64_t*,
struct AdbcError*);
AdbcStatusCode (*ConnectionGetOptionDouble)(struct AdbcConnection*, const char*,
Expand All @@ -836,6 +868,8 @@ struct ADBC_EXPORT AdbcDriver {
struct AdbcError*);
AdbcStatusCode (*StatementGetOption)(struct AdbcStatement*, const char*, const char**,
struct AdbcError*);
AdbcStatusCode (*StatementGetOptionBytes)(struct AdbcDatabase*, const char*,
const uint8_t**, size_t*, struct AdbcError*);
AdbcStatusCode (*StatementGetOptionInt)(struct AdbcStatement*, const char*, int64_t*,
struct AdbcError*);
AdbcStatusCode (*StatementGetOptionDouble)(struct AdbcStatement*, const char*, double*,
Expand Down Expand Up @@ -907,6 +941,34 @@ AdbcStatusCode AdbcDatabaseNew(struct AdbcDatabase* database, struct AdbcError*
AdbcStatusCode AdbcDatabaseGetOption(struct AdbcDatabase* database, const char* key,
const char** value, struct AdbcError* error);

/// \brief Get a bytestring option of the database.
///
/// This must always be thread-safe (other operations are not).
///
/// The returned option value is only valid until the next call to
/// GetOption or Release.
///
/// For standard options, drivers must always support getting the
/// option value (if they support getting option values at all) via
/// the type specified in the option. (For example, an option set via
/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers
/// may also support getting a converted option value via other
/// getters if needed. (For example, getting the string
/// representation of a double option.)
///
/// \since ADBC API revision 1.1.0
/// \addtogroup adbc-1.1.0
/// \param[in] database The database.
/// \param[in] key The option to get.
/// \param[out] value The option value.
/// \param[out] length The option value length.
/// \param[out] error An optional location to return an error
/// message if necessary.
/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized.
AdbcStatusCode AdbcDatabaseGetOptionBytes(struct AdbcDatabase* database, const char* key,
const uint8_t** value, size_t* length,
struct AdbcError* error);

/// \brief Get an integer option of the database.
///
/// This must always be thread-safe (other operations are not).
Expand Down Expand Up @@ -1095,6 +1157,29 @@ ADBC_EXPORT
AdbcStatusCode AdbcConnectionRelease(struct AdbcConnection* connection,
struct AdbcError* error);

/// \brief 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).
///
/// This must always be thread-safe (other operations are not).
///
/// \since ADBC API revision 1.1.0
/// \addtogroup adbc-1.1.0
///
/// \param[in] connection The connection to cancel.
/// \param[out] error An optional location to return an error
/// message if necessary.
///
/// \return ADBC_STATUS_INVALID_STATE if there is no operation to cancel.
/// \return ADBC_STATUS_UNKNOWN if the operation could not be cancelled.
ADBC_EXPORT
AdbcStatusCode AdbcConnectionCancel(struct AdbcConnection* connection,
struct AdbcError* error);

/// \defgroup adbc-connection-metadata Metadata
/// Functions for retrieving metadata about the database.
///
Expand Down Expand Up @@ -1299,6 +1384,34 @@ AdbcStatusCode AdbcConnectionGetObjects(struct AdbcConnection* connection, int d
AdbcStatusCode AdbcConnectionGetOption(struct AdbcConnection* connection, const char* key,
const char** value, struct AdbcError* error);

/// \brief Get a bytestring option of the connection.
///
/// This must always be thread-safe (other operations are not).
///
/// The returned option value is only valid until the next call to
/// GetOption or Release.
///
/// For standard options, drivers must always support getting the
/// option value (if they support getting option values at all) via
/// the type specified in the option. (For example, an option set via
/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers
/// may also support getting a converted option value via other
/// getters if needed. (For example, getting the string
/// representation of a double option.)
///
/// \since ADBC API revision 1.1.0
/// \addtogroup adbc-1.1.0
/// \param[in] connection The connection.
/// \param[in] key The option to get.
/// \param[out] value The option value.
/// \param[out] length The option value length.
/// \param[out] error An optional location to return an error
/// message if necessary.
/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized.
AdbcStatusCode AdbcConnectionGetOptionBytes(struct AdbcConnection* connection,
const char* key, const uint8_t** value,
size_t* length, struct AdbcError* error);

/// \brief Get an integer option of the connection.
///
/// This must always be thread-safe (other operations are not).
Expand Down Expand Up @@ -1494,6 +1607,9 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
///
/// This invalidates any prior result sets.
///
/// Depending on the driver, this may require first executing
/// AdbcStatementPrepare.
///
/// \since ADBC API revision 1.1.0
/// \addtogroup adbc-1.1.0
///
Expand Down Expand Up @@ -1639,6 +1755,34 @@ AdbcStatusCode AdbcStatementCancel(struct AdbcStatement* statement,
AdbcStatusCode AdbcStatementGetOption(struct AdbcStatement* statement, const char* key,
const char** value, struct AdbcError* error);

/// \brief Get a bytestring option of the statement.
///
/// This must always be thread-safe (other operations are not).
///
/// The returned option value is only valid until the next call to
/// GetOption or Release.
///
/// For standard options, drivers must always support getting the
/// option value (if they support getting option values at all) via
/// the type specified in the option. (For example, an option set via
/// SetOptionDouble must be retrievable via GetOptionDouble.) Drivers
/// may also support getting a converted option value via other
/// getters if needed. (For example, getting the string
/// representation of a double option.)
///
/// \since ADBC API revision 1.1.0
/// \addtogroup adbc-1.1.0
/// \param[in] statement The statement.
/// \param[in] key The option to get.
/// \param[out] value The option value.
/// \param[out] length The option value length.
/// \param[out] error An optional location to return an error
/// message if necessary.
/// \return ADBC_STATUS_NOT_FOUND if the option is not recognized.
AdbcStatusCode AdbcStatementGetOptionBytes(struct AdbcStatement* statement,
const char* key, const uint8_t** value,
size_t* length, struct AdbcError* error);

/// \brief Get an integer option of the statement.
///
/// This must always be thread-safe (other operations are not).
Expand Down
22 changes: 22 additions & 0 deletions c/driver_manager/adbc_driver_manager.cc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,11 @@ AdbcStatusCode DatabaseSetOptionDouble(struct AdbcDatabase* database, const char
return ADBC_STATUS_NOT_IMPLEMENTED;
}

AdbcStatusCode ConnectionCancel(struct AdbcConnection* connection,
struct AdbcError* error) {
return ADBC_STATUS_NOT_IMPLEMENTED;
}

AdbcStatusCode ConnectionCommit(struct AdbcConnection*, struct AdbcError* error) {
return ADBC_STATUS_NOT_IMPLEMENTED;
}
Expand Down Expand Up @@ -533,6 +538,14 @@ AdbcStatusCode AdbcDatabaseRelease(struct AdbcDatabase* database,
return status;
}

AdbcStatusCode AdbcConnectionCancel(struct AdbcConnection* connection,
struct AdbcError* error) {
if (!connection->private_driver) {
return ADBC_STATUS_INVALID_STATE;
}
return connection->private_driver->ConnectionCancel(connection, error);
}

AdbcStatusCode AdbcConnectionCommit(struct AdbcConnection* connection,
struct AdbcError* error) {
if (!connection->private_driver) {
Expand Down Expand Up @@ -801,6 +814,14 @@ AdbcStatusCode AdbcStatementBindStream(struct AdbcStatement* statement,
return statement->private_driver->StatementBindStream(statement, stream, error);
}

AdbcStatusCode AdbcStatementCancel(struct AdbcStatement* statement,
struct AdbcError* error) {
if (!statement->private_driver) {
return ADBC_STATUS_INVALID_STATE;
}
return statement->private_driver->StatementCancel(statement, error);
}

// XXX: cpplint gets confused here if declared as 'struct ArrowSchema* schema'
AdbcStatusCode AdbcStatementExecutePartitions(struct AdbcStatement* statement,
ArrowSchema* schema,
Expand Down Expand Up @@ -1197,6 +1218,7 @@ AdbcStatusCode AdbcLoadDriverFromInitFunc(AdbcDriverInitFunc init_func, int vers
FILL_DEFAULT(driver, DatabaseSetOptionInt);
FILL_DEFAULT(driver, DatabaseSetOptionDouble);

FILL_DEFAULT(driver, ConnectionCancel);
FILL_DEFAULT(driver, ConnectionGetOption);
FILL_DEFAULT(driver, ConnectionGetOptionInt);
FILL_DEFAULT(driver, ConnectionGetOptionDouble);
Expand Down

0 comments on commit c0486ed

Please sign in to comment.