1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements. See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership. The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License. You may obtain a copy of the License at
8//
9// http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied. See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18/// \file adbc.h ADBC: Arrow Database connectivity
19///
20/// An Arrow-based interface between applications and database
21/// drivers. ADBC aims to provide a vendor-independent API for SQL
22/// and Substrait-based database access that is targeted at
23/// analytics/OLAP use cases.
24///
25/// This API is intended to be implemented directly by drivers and
26/// used directly by client applications. To assist portability
27/// between different vendors, a "driver manager" library is also
28/// provided, which implements this same API, but dynamically loads
29/// drivers internally and forwards calls appropriately.
30///
31/// ADBC uses structs with free functions that operate on those
32/// structs to model objects.
33///
34/// In general, objects allow serialized access from multiple threads,
35/// but not concurrent access. Specific implementations may permit
36/// multiple threads.
37///
38/// \version 1.0.0
39
40#pragma once
41
42#include <stddef.h>
43#include <stdint.h>
44#include "duckdb/common/arrow/arrow.hpp"
45
46/// \defgroup Arrow C Data Interface
47/// Definitions for the C Data Interface/C Stream Interface.
48///
49/// See https://arrow.apache.org/docs/format/CDataInterface.html
50///
51/// @{
52
53//! @cond Doxygen_Suppress
54namespace duckdb_adbc {
55#ifdef __cplusplus
56extern "C" {
57#endif
58
59#ifndef ARROW_ADBC
60#define ARROW_ADBC
61
62#ifndef ADBC_EXPORTING
63#define ADBC_EXPORTING
64#endif
65
66// Storage class macros for Windows
67// Allow overriding/aliasing with application-defined macros
68#if !defined(ADBC_EXPORT)
69#if defined(_WIN32)
70#if defined(ADBC_EXPORTING)
71#define ADBC_EXPORT __declspec(dllexport)
72#else
73#define ADBC_EXPORT __declspec(dllimport)
74#endif // defined(ADBC_EXPORTING)
75#else
76#define ADBC_EXPORT
77#endif // defined(_WIN32)
78#endif // !defined(ADBC_EXPORT)
79
80/// \defgroup adbc-error-handling Error Handling
81/// ADBC uses integer error codes to signal errors. To provide more
82/// detail about errors, functions may also return an AdbcError via an
83/// optional out parameter, which can be inspected. If provided, it is
84/// the responsibility of the caller to zero-initialize the AdbcError
85/// value.
86///
87/// @{
88
89/// \brief Error codes for operations that may fail.
90typedef uint8_t AdbcStatusCode;
91
92/// \brief No error.
93#define ADBC_STATUS_OK 0
94/// \brief An unknown error occurred.
95///
96/// May indicate a driver-side or database-side error.
97#define ADBC_STATUS_UNKNOWN 1
98/// \brief The operation is not implemented or supported.
99///
100/// May indicate a driver-side or database-side error.
101#define ADBC_STATUS_NOT_IMPLEMENTED 2
102/// \brief A requested resource was not found.
103///
104/// May indicate a driver-side or database-side error.
105#define ADBC_STATUS_NOT_FOUND 3
106/// \brief A requested resource already exists.
107///
108/// May indicate a driver-side or database-side error.
109#define ADBC_STATUS_ALREADY_EXISTS 4
110/// \brief The arguments are invalid, likely a programming error.
111///
112/// For instance, they may be of the wrong format, or out of range.
113///
114/// May indicate a driver-side or database-side error.
115#define ADBC_STATUS_INVALID_ARGUMENT 5
116/// \brief The preconditions for the operation are not met, likely a
117/// programming error.
118///
119/// For instance, the object may be uninitialized, or may have not
120/// been fully configured.
121///
122/// May indicate a driver-side or database-side error.
123#define ADBC_STATUS_INVALID_STATE 6
124/// \brief Invalid data was processed (not a programming error).
125///
126/// For instance, a division by zero may have occurred during query
127/// execution.
128///
129/// May indicate a database-side error only.
130#define ADBC_STATUS_INVALID_DATA 7
131/// \brief The database's integrity was affected.
132///
133/// For instance, a foreign key check may have failed, or a uniqueness
134/// constraint may have been violated.
135///
136/// May indicate a database-side error only.
137#define ADBC_STATUS_INTEGRITY 8
138/// \brief An error internal to the driver or database occurred.
139///
140/// May indicate a driver-side or database-side error.
141#define ADBC_STATUS_INTERNAL 9
142/// \brief An I/O error occurred.
143///
144/// For instance, a remote service may be unavailable.
145///
146/// May indicate a driver-side or database-side error.
147#define ADBC_STATUS_IO 10
148/// \brief The operation was cancelled, not due to a timeout.
149///
150/// May indicate a driver-side or database-side error.
151#define ADBC_STATUS_CANCELLED 11
152/// \brief The operation was cancelled due to a timeout.
153///
154/// May indicate a driver-side or database-side error.
155#define ADBC_STATUS_TIMEOUT 12
156/// \brief Authentication failed.
157///
158/// May indicate a database-side error only.
159#define ADBC_STATUS_UNAUTHENTICATED 13
160/// \brief The client is not authorized to perform the given operation.
161///
162/// May indicate a database-side error only.
163#define ADBC_STATUS_UNAUTHORIZED 14
164
165/// \brief A detailed error message for an operation.
166struct ADBC_EXPORT AdbcError {
167 /// \brief The error message.
168 char *message;
169
170 /// \brief A vendor-specific error code, if applicable.
171 int32_t vendor_code;
172
173 /// \brief A SQLSTATE error code, if provided, as defined by the
174 /// SQL:2003 standard. If not set, it should be set to
175 /// "\0\0\0\0\0".
176 char sqlstate[5];
177
178 /// \brief Release the contained error.
179 ///
180 /// Unlike other structures, this is an embedded callback to make it
181 /// easier for the driver manager and driver to cooperate.
182 void (*release)(struct AdbcError *error);
183};
184
185/// @}
186
187/// \defgroup adbc-constants Constants
188/// @{
189
190/// \brief ADBC revision 1.0.0.
191///
192/// When passed to an AdbcDriverInitFunc(), the driver parameter must
193/// point to an AdbcDriver.
194#define ADBC_VERSION_1_0_0 1000000
195
196/// \brief Canonical option value for enabling an option.
197///
198/// For use as the value in SetOption calls.
199#define ADBC_OPTION_VALUE_ENABLED "true"
200/// \brief Canonical option value for disabling an option.
201///
202/// For use as the value in SetOption calls.
203#define ADBC_OPTION_VALUE_DISABLED "false"
204
205/// \brief The database vendor/product name (e.g. the server name).
206/// (type: utf8).
207///
208/// \see AdbcConnectionGetInfo
209#define ADBC_INFO_VENDOR_NAME 0
210/// \brief The database vendor/product version (type: utf8).
211///
212/// \see AdbcConnectionGetInfo
213#define ADBC_INFO_VENDOR_VERSION 1
214/// \brief The database vendor/product Arrow library version (type:
215/// utf8).
216///
217/// \see AdbcConnectionGetInfo
218#define ADBC_INFO_VENDOR_ARROW_VERSION 2
219
220/// \brief The driver name (type: utf8).
221///
222/// \see AdbcConnectionGetInfo
223#define ADBC_INFO_DRIVER_NAME 100
224/// \brief The driver version (type: utf8).
225///
226/// \see AdbcConnectionGetInfo
227#define ADBC_INFO_DRIVER_VERSION 101
228/// \brief The driver Arrow library version (type: utf8).
229///
230/// \see AdbcConnectionGetInfo
231#define ADBC_INFO_DRIVER_ARROW_VERSION 102
232
233/// \brief Return metadata on catalogs, schemas, tables, and columns.
234///
235/// \see AdbcConnectionGetObjects
236#define ADBC_OBJECT_DEPTH_ALL 0
237/// \brief Return metadata on catalogs only.
238///
239/// \see AdbcConnectionGetObjects
240#define ADBC_OBJECT_DEPTH_CATALOGS 1
241/// \brief Return metadata on catalogs and schemas.
242///
243/// \see AdbcConnectionGetObjects
244#define ADBC_OBJECT_DEPTH_DB_SCHEMAS 2
245/// \brief Return metadata on catalogs, schemas, and tables.
246///
247/// \see AdbcConnectionGetObjects
248#define ADBC_OBJECT_DEPTH_TABLES 3
249/// \brief Return metadata on catalogs, schemas, tables, and columns.
250///
251/// \see AdbcConnectionGetObjects
252#define ADBC_OBJECT_DEPTH_COLUMNS ADBC_OBJECT_DEPTH_ALL
253
254/// \brief The name of the canonical option for whether autocommit is
255/// enabled.
256///
257/// \see AdbcConnectionSetOption
258#define ADBC_CONNECTION_OPTION_AUTOCOMMIT "adbc.connection.autocommit"
259
260/// \brief The name of the canonical option for whether the current
261/// connection should be restricted to being read-only.
262///
263/// \see AdbcConnectionSetOption
264#define ADBC_CONNECTION_OPTION_READ_ONLY "adbc.connection.readonly"
265
266/// \brief The name of the canonical option for setting the isolation
267/// level of a transaction.
268///
269/// Should only be used in conjunction with autocommit disabled and
270/// AdbcConnectionCommit / AdbcConnectionRollback. If the desired
271/// isolation level is not supported by a driver, it should return an
272/// appropriate error.
273///
274/// \see AdbcConnectionSetOption
275#define ADBC_CONNECTION_OPTION_ISOLATION_LEVEL "adbc.connection.transaction.isolation_level"
276
277/// \brief Use database or driver default isolation level
278///
279/// \see AdbcConnectionSetOption
280#define ADBC_OPTION_ISOLATION_LEVEL_DEFAULT "adbc.connection.transaction.isolation.default"
281
282/// \brief The lowest isolation level. Dirty reads are allowed, so one
283/// transaction may see not-yet-committed changes made by others.
284///
285/// \see AdbcConnectionSetOption
286#define ADBC_OPTION_ISOLATION_LEVEL_READ_UNCOMMITTED "adbc.connection.transaction.isolation.read_uncommitted"
287
288/// \brief Lock-based concurrency control keeps write locks until the
289/// end of the transaction, but read locks are released as soon as a
290/// SELECT is performed. Non-repeatable reads can occur in this
291/// isolation level.
292///
293/// More simply put, Read Committed is an isolation level that guarantees
294/// that any data read is committed at the moment it is read. It simply
295/// restricts the reader from seeing any intermediate, uncommitted,
296/// 'dirty' reads. It makes no promise whatsoever that if the transaction
297/// re-issues the read, it will find the same data; data is free to change
298/// after it is read.
299///
300/// \see AdbcConnectionSetOption
301#define ADBC_OPTION_ISOLATION_LEVEL_READ_COMMITTED "adbc.connection.transaction.isolation.read_committed"
302
303/// \brief Lock-based concurrency control keeps read AND write locks
304/// (acquired on selection data) until the end of the transaction.
305///
306/// However, range-locks are not managed, so phantom reads can occur.
307/// Write skew is possible at this isolation level in some systems.
308///
309/// \see AdbcConnectionSetOption
310#define ADBC_OPTION_ISOLATION_LEVEL_REPEATABLE_READ "adbc.connection.transaction.isolation.repeatable_read"
311
312/// \brief This isolation guarantees that all reads in the transaction
313/// will see a consistent snapshot of the database and the transaction
314/// should only successfully commit if no updates conflict with any
315/// concurrent updates made since that snapshot.
316///
317/// \see AdbcConnectionSetOption
318#define ADBC_OPTION_ISOLATION_LEVEL_SNAPSHOT "adbc.connection.transaction.isolation.snapshot"
319
320/// \brief Serializability requires read and write locks to be released
321/// only at the end of the transaction. This includes acquiring range-
322/// locks when a select query uses a ranged WHERE clause to avoid
323/// phantom reads.
324///
325/// \see AdbcConnectionSetOption
326#define ADBC_OPTION_ISOLATION_LEVEL_SERIALIZABLE "adbc.connection.transaction.isolation.serializable"
327
328/// \brief The central distinction between serializability and linearizability
329/// is that serializability is a global property; a property of an entire
330/// history of operations and transactions. Linearizability is a local
331/// property; a property of a single operation/transaction.
332///
333/// Linearizability can be viewed as a special case of strict serializability
334/// where transactions are restricted to consist of a single operation applied
335/// to a single object.
336///
337/// \see AdbcConnectionSetOption
338#define ADBC_OPTION_ISOLATION_LEVEL_LINEARIZABLE "adbc.connection.transaction.isolation.linearizable"
339
340/// \defgroup adbc-statement-ingestion Bulk Data Ingestion
341/// While it is possible to insert data via prepared statements, it can
342/// be more efficient to explicitly perform a bulk insert. For
343/// compatible drivers, this can be accomplished by setting up and
344/// executing a statement. Instead of setting a SQL query or Substrait
345/// plan, bind the source data via AdbcStatementBind, and set the name
346/// of the table to be created via AdbcStatementSetOption and the
347/// options below. Then, call AdbcStatementExecute with a NULL for
348/// the out parameter (to indicate you do not expect a result set).
349///
350/// @{
351
352/// \brief The name of the target table for a bulk insert.
353///
354/// The driver should attempt to create the table if it does not
355/// exist. If the table exists but has a different schema,
356/// ADBC_STATUS_ALREADY_EXISTS should be raised. Else, data should be
357/// appended to the target table.
358#define ADBC_INGEST_OPTION_TARGET_TABLE "adbc.ingest.target_table"
359/// \brief Whether to create (the default) or append.
360#define ADBC_INGEST_OPTION_MODE "adbc.ingest.mode"
361/// \brief Create the table and insert data; error if the table exists.
362#define ADBC_INGEST_OPTION_MODE_CREATE "adbc.ingest.mode.create"
363/// \brief Do not create the table, and insert data; error if the
364/// table does not exist (ADBC_STATUS_NOT_FOUND) or does not match
365/// the schema of the data to append (ADBC_STATUS_ALREADY_EXISTS).
366#define ADBC_INGEST_OPTION_MODE_APPEND "adbc.ingest.mode.append"
367
368/// @}
369
370/// @}
371
372/// \defgroup adbc-database Database Initialization
373/// Clients first initialize a database, then create a connection
374/// (below). This gives the implementation a place to initialize and
375/// own any common connection state. For example, in-memory databases
376/// can place ownership of the actual database in this object.
377/// @{
378
379/// \brief An instance of a database.
380///
381/// Must be kept alive as long as any connections exist.
382struct ADBC_EXPORT AdbcDatabase {
383 /// \brief Opaque implementation-defined state.
384 /// This field is NULLPTR iff the connection is unintialized/freed.
385 void *private_data;
386 /// \brief The associated driver (used by the driver manager to help
387 /// track state).
388 struct AdbcDriver *private_driver;
389};
390
391/// @}
392
393/// \defgroup adbc-connection Connection Establishment
394/// Functions for creating, using, and releasing database connections.
395/// @{
396
397/// \brief An active database connection.
398///
399/// Provides methods for query execution, managing prepared
400/// statements, using transactions, and so on.
401///
402/// Connections are not required to be thread-safe, but they can be
403/// used from multiple threads so long as clients take care to
404/// serialize accesses to a connection.
405struct ADBC_EXPORT AdbcConnection {
406 /// \brief Opaque implementation-defined state.
407 /// This field is NULLPTR iff the connection is unintialized/freed.
408 void *private_data;
409 /// \brief The associated driver (used by the driver manager to help
410 /// track state).
411 struct AdbcDriver *private_driver;
412};
413
414/// @}
415
416/// \defgroup adbc-statement Managing Statements
417/// Applications should first initialize a statement with
418/// AdbcStatementNew. Then, the statement should be configured with
419/// functions like AdbcStatementSetSqlQuery and
420/// AdbcStatementSetOption. Finally, the statement can be executed
421/// with AdbcStatementExecuteQuery (or call AdbcStatementPrepare first
422/// to turn it into a prepared statement instead).
423/// @{
424
425/// \brief A container for all state needed to execute a database
426/// query, such as the query itself, parameters for prepared
427/// statements, driver parameters, etc.
428///
429/// Statements may represent queries or prepared statements.
430///
431/// Statements may be used multiple times and can be reconfigured
432/// (e.g. they can be reused to execute multiple different queries).
433/// However, executing a statement (and changing certain other state)
434/// will invalidate result sets obtained prior to that execution.
435///
436/// Multiple statements may be created from a single connection.
437/// However, the driver may block or error if they are used
438/// concurrently (whether from a single thread or multiple threads).
439///
440/// Statements are not required to be thread-safe, but they can be
441/// used from multiple threads so long as clients take care to
442/// serialize accesses to a statement.
443struct ADBC_EXPORT AdbcStatement {
444 /// \brief Opaque implementation-defined state.
445 /// This field is NULLPTR iff the connection is unintialized/freed.
446 void *private_data;
447
448 /// \brief The associated driver (used by the driver manager to help
449 /// track state).
450 struct AdbcDriver *private_driver;
451};
452
453/// \defgroup adbc-statement-partition Partitioned Results
454/// Some backends may internally partition the results. These
455/// partitions are exposed to clients who may wish to integrate them
456/// with a threaded or distributed execution model, where partitions
457/// can be divided among threads or machines and fetched in parallel.
458///
459/// To use partitioning, execute the statement with
460/// AdbcStatementExecutePartitions to get the partition descriptors.
461/// Call AdbcConnectionReadPartition to turn the individual
462/// descriptors into ArrowArrayStream instances. This may be done on
463/// a different connection than the one the partition was created
464/// with, or even in a different process on another machine.
465///
466/// Drivers are not required to support partitioning.
467///
468/// @{
469
470/// \brief The partitions of a distributed/partitioned result set.
471struct AdbcPartitions {
472 /// \brief The number of partitions.
473 size_t num_partitions;
474
475 /// \brief The partitions of the result set, where each entry (up to
476 /// num_partitions entries) is an opaque identifier that can be
477 /// passed to AdbcConnectionReadPartition.
478 const uint8_t **partitions;
479
480 /// \brief The length of each corresponding entry in partitions.
481 const size_t *partition_lengths;
482
483 /// \brief Opaque implementation-defined state.
484 /// This field is NULLPTR iff the connection is unintialized/freed.
485 void *private_data;
486
487 /// \brief Release the contained partitions.
488 ///
489 /// Unlike other structures, this is an embedded callback to make it
490 /// easier for the driver manager and driver to cooperate.
491 void (*release)(struct AdbcPartitions *partitions);
492};
493
494/// @}
495
496/// @}
497
498/// \defgroup adbc-driver Driver Initialization
499///
500/// These functions are intended to help support integration between a
501/// driver and the driver manager.
502/// @{
503
504/// \brief An instance of an initialized database driver.
505///
506/// This provides a common interface for vendor-specific driver
507/// initialization routines. Drivers should populate this struct, and
508/// applications can call ADBC functions through this struct, without
509/// worrying about multiple definitions of the same symbol.
510struct ADBC_EXPORT AdbcDriver {
511 /// \brief Opaque driver-defined state.
512 /// This field is NULL if the driver is unintialized/freed (but
513 /// it need not have a value even if the driver is initialized).
514 void *private_data;
515 /// \brief Opaque driver manager-defined state.
516 /// This field is NULL if the driver is unintialized/freed (but
517 /// it need not have a value even if the driver is initialized).
518 void *private_manager;
519
520 /// \brief Release the driver and perform any cleanup.
521 ///
522 /// This is an embedded callback to make it easier for the driver
523 /// manager and driver to cooperate.
524 AdbcStatusCode (*release)(struct AdbcDriver *driver, struct AdbcError *error);
525
526 AdbcStatusCode (*DatabaseInit)(struct AdbcDatabase *, struct AdbcError *);
527 AdbcStatusCode (*DatabaseNew)(struct AdbcDatabase *, struct AdbcError *);
528 AdbcStatusCode (*DatabaseSetOption)(struct AdbcDatabase *, const char *, const char *, struct AdbcError *);
529 AdbcStatusCode (*DatabaseRelease)(struct AdbcDatabase *, struct AdbcError *);
530
531 AdbcStatusCode (*ConnectionCommit)(struct AdbcConnection *, struct AdbcError *);
532 AdbcStatusCode (*ConnectionGetInfo)(struct AdbcConnection *, uint32_t *, size_t, struct ArrowArrayStream *,
533 struct AdbcError *);
534 AdbcStatusCode (*ConnectionGetObjects)(struct AdbcConnection *, int, const char *, const char *, const char *,
535 const char **, const char *, struct ArrowArrayStream *, struct AdbcError *);
536 AdbcStatusCode (*ConnectionGetTableSchema)(struct AdbcConnection *, const char *, const char *, const char *,
537 struct ArrowSchema *, struct AdbcError *);
538 AdbcStatusCode (*ConnectionGetTableTypes)(struct AdbcConnection *, struct ArrowArrayStream *, struct AdbcError *);
539 AdbcStatusCode (*ConnectionInit)(struct AdbcConnection *, struct AdbcDatabase *, struct AdbcError *);
540 AdbcStatusCode (*ConnectionNew)(struct AdbcConnection *, struct AdbcError *);
541 AdbcStatusCode (*ConnectionSetOption)(struct AdbcConnection *, const char *, const char *, struct AdbcError *);
542 AdbcStatusCode (*ConnectionReadPartition)(struct AdbcConnection *, const uint8_t *, size_t,
543 struct ArrowArrayStream *, struct AdbcError *);
544 AdbcStatusCode (*ConnectionRelease)(struct AdbcConnection *, struct AdbcError *);
545 AdbcStatusCode (*ConnectionRollback)(struct AdbcConnection *, struct AdbcError *);
546
547 AdbcStatusCode (*StatementBind)(struct AdbcStatement *, struct ArrowArray *, struct ArrowSchema *,
548 struct AdbcError *);
549 AdbcStatusCode (*StatementBindStream)(struct AdbcStatement *, struct ArrowArrayStream *, struct AdbcError *);
550 AdbcStatusCode (*StatementExecuteQuery)(struct AdbcStatement *, struct ArrowArrayStream *, int64_t *,
551 struct AdbcError *);
552 AdbcStatusCode (*StatementExecutePartitions)(struct AdbcStatement *, struct ArrowSchema *, struct AdbcPartitions *,
553 int64_t *, struct AdbcError *);
554 AdbcStatusCode (*StatementGetParameterSchema)(struct AdbcStatement *, struct ArrowSchema *, struct AdbcError *);
555 AdbcStatusCode (*StatementNew)(struct AdbcConnection *, struct AdbcStatement *, struct AdbcError *);
556 AdbcStatusCode (*StatementPrepare)(struct AdbcStatement *, struct AdbcError *);
557 AdbcStatusCode (*StatementRelease)(struct AdbcStatement *, struct AdbcError *);
558 AdbcStatusCode (*StatementSetOption)(struct AdbcStatement *, const char *, const char *, struct AdbcError *);
559 AdbcStatusCode (*StatementSetSqlQuery)(struct AdbcStatement *, const char *, struct AdbcError *);
560 AdbcStatusCode (*StatementSetSubstraitPlan)(struct AdbcStatement *, const uint8_t *, size_t, struct AdbcError *);
561};
562
563/// @}
564
565/// \addtogroup adbc-database
566/// @{
567
568/// \brief Allocate a new (but uninitialized) database.
569///
570/// Callers pass in a zero-initialized AdbcDatabase.
571///
572/// Drivers should allocate their internal data structure and set the private_data
573/// field to point to the newly allocated struct. This struct should be released
574/// when AdbcDatabaseRelease is called.
575ADBC_EXPORT
576AdbcStatusCode AdbcDatabaseNew(struct AdbcDatabase *database, struct AdbcError *error);
577
578/// \brief Set a char* option.
579///
580/// Options may be set before AdbcDatabaseInit. Some drivers may
581/// support setting options after initialization as well.
582///
583/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized
584ADBC_EXPORT
585AdbcStatusCode AdbcDatabaseSetOption(struct AdbcDatabase *database, const char *key, const char *value,
586 struct AdbcError *error);
587
588/// \brief Finish setting options and initialize the database.
589///
590/// Some drivers may support setting options after initialization
591/// as well.
592ADBC_EXPORT
593AdbcStatusCode AdbcDatabaseInit(struct AdbcDatabase *database, struct AdbcError *error);
594
595/// \brief Destroy this database. No connections may exist.
596/// \param[in] database The database to release.
597/// \param[out] error An optional location to return an error
598/// message if necessary.
599ADBC_EXPORT
600AdbcStatusCode AdbcDatabaseRelease(struct AdbcDatabase *database, struct AdbcError *error);
601
602/// @}
603
604/// \addtogroup adbc-connection
605/// @{
606
607/// \brief Allocate a new (but uninitialized) connection.
608///
609/// Callers pass in a zero-initialized AdbcConnection.
610///
611/// Drivers should allocate their internal data structure and set the private_data
612/// field to point to the newly allocated struct. This struct should be released
613/// when AdbcConnectionRelease is called.
614ADBC_EXPORT
615AdbcStatusCode AdbcConnectionNew(struct AdbcConnection *connection, struct AdbcError *error);
616
617/// \brief Set a char* option.
618///
619/// Options may be set before AdbcConnectionInit. Some drivers may
620/// support setting options after initialization as well.
621///
622/// \return ADBC_STATUS_NOT_IMPLEMENTED if the option is not recognized
623ADBC_EXPORT
624AdbcStatusCode AdbcConnectionSetOption(struct AdbcConnection *connection, const char *key, const char *value,
625 struct AdbcError *error);
626
627/// \brief Finish setting options and initialize the connection.
628///
629/// Some drivers may support setting options after initialization
630/// as well.
631ADBC_EXPORT
632AdbcStatusCode AdbcConnectionInit(struct AdbcConnection *connection, struct AdbcDatabase *database,
633 struct AdbcError *error);
634
635/// \brief Destroy this connection.
636///
637/// \param[in] connection The connection to release.
638/// \param[out] error An optional location to return an error
639/// message if necessary.
640ADBC_EXPORT
641AdbcStatusCode AdbcConnectionRelease(struct AdbcConnection *connection, struct AdbcError *error);
642
643/// \defgroup adbc-connection-metadata Metadata
644/// Functions for retrieving metadata about the database.
645///
646/// Generally, these functions return an ArrowArrayStream that can be
647/// consumed to get the metadata as Arrow data. The returned metadata
648/// has an expected schema given in the function docstring. Schema
649/// fields are nullable unless otherwise marked. While no
650/// AdbcStatement is used in these functions, the result set may count
651/// as an active statement to the driver for the purposes of
652/// concurrency management (e.g. if the driver has a limit on
653/// concurrent active statements and it must execute a SQL query
654/// internally in order to implement the metadata function).
655///
656/// Some functions accept "search pattern" arguments, which are
657/// strings that can contain the special character "%" to match zero
658/// or more characters, or "_" to match exactly one character. (See
659/// the documentation of DatabaseMetaData in JDBC or "Pattern Value
660/// Arguments" in the ODBC documentation.) Escaping is not currently
661/// supported.
662///
663/// @{
664
665/// \brief Get metadata about the database/driver.
666///
667/// The result is an Arrow dataset with the following schema:
668///
669/// Field Name | Field Type
670/// ----------------------------|------------------------
671/// info_name | uint32 not null
672/// info_value | INFO_SCHEMA
673///
674/// INFO_SCHEMA is a dense union with members:
675///
676/// Field Name (Type Code) | Field Type
677/// ----------------------------|------------------------
678/// string_value (0) | utf8
679/// bool_value (1) | bool
680/// int64_value (2) | int64
681/// int32_bitmask (3) | int32
682/// string_list (4) | list<utf8>
683/// int32_to_int32_list_map (5) | map<int32, list<int32>>
684///
685/// Each metadatum is identified by an integer code. The recognized
686/// codes are defined as constants. Codes [0, 10_000) are reserved
687/// for ADBC usage. Drivers/vendors will ignore requests for
688/// unrecognized codes (the row will be omitted from the result).
689///
690/// \param[in] connection The connection to query.
691/// \param[in] info_codes A list of metadata codes to fetch, or NULL
692/// to fetch all.
693/// \param[in] info_codes_length The length of the info_codes
694/// parameter. Ignored if info_codes is NULL.
695/// \param[out] out The result set.
696/// \param[out] error Error details, if an error occurs.
697ADBC_EXPORT
698AdbcStatusCode AdbcConnectionGetInfo(struct AdbcConnection *connection, uint32_t *info_codes, size_t info_codes_length,
699 struct ArrowArrayStream *out, struct AdbcError *error);
700
701/// \brief Get a hierarchical view of all catalogs, database schemas,
702/// tables, and columns.
703///
704/// The result is an Arrow dataset with the following schema:
705///
706/// | Field Name | Field Type |
707/// |--------------------------|-------------------------|
708/// | catalog_name | utf8 |
709/// | catalog_db_schemas | list<DB_SCHEMA_SCHEMA> |
710///
711/// DB_SCHEMA_SCHEMA is a Struct with fields:
712///
713/// | Field Name | Field Type |
714/// |--------------------------|-------------------------|
715/// | db_schema_name | utf8 |
716/// | db_schema_tables | list<TABLE_SCHEMA> |
717///
718/// TABLE_SCHEMA is a Struct with fields:
719///
720/// | Field Name | Field Type |
721/// |--------------------------|-------------------------|
722/// | table_name | utf8 not null |
723/// | table_type | utf8 not null |
724/// | table_columns | list<COLUMN_SCHEMA> |
725/// | table_constraints | list<CONSTRAINT_SCHEMA> |
726///
727/// COLUMN_SCHEMA is a Struct with fields:
728///
729/// | Field Name | Field Type | Comments |
730/// |--------------------------|-------------------------|----------|
731/// | column_name | utf8 not null | |
732/// | ordinal_position | int32 | (1) |
733/// | remarks | utf8 | (2) |
734/// | xdbc_data_type | int16 | (3) |
735/// | xdbc_type_name | utf8 | (3) |
736/// | xdbc_column_size | int32 | (3) |
737/// | xdbc_decimal_digits | int16 | (3) |
738/// | xdbc_num_prec_radix | int16 | (3) |
739/// | xdbc_nullable | int16 | (3) |
740/// | xdbc_column_def | utf8 | (3) |
741/// | xdbc_sql_data_type | int16 | (3) |
742/// | xdbc_datetime_sub | int16 | (3) |
743/// | xdbc_char_octet_length | int32 | (3) |
744/// | xdbc_is_nullable | utf8 | (3) |
745/// | xdbc_scope_catalog | utf8 | (3) |
746/// | xdbc_scope_schema | utf8 | (3) |
747/// | xdbc_scope_table | utf8 | (3) |
748/// | xdbc_is_autoincrement | bool | (3) |
749/// | xdbc_is_generatedcolumn | bool | (3) |
750///
751/// 1. The column's ordinal position in the table (starting from 1).
752/// 2. Database-specific description of the column.
753/// 3. Optional value. Should be null if not supported by the driver.
754/// xdbc_ values are meant to provide JDBC/ODBC-compatible metadata
755/// in an agnostic manner.
756///
757/// CONSTRAINT_SCHEMA is a Struct with fields:
758///
759/// | Field Name | Field Type | Comments |
760/// |--------------------------|-------------------------|----------|
761/// | constraint_name | utf8 | |
762/// | constraint_type | utf8 not null | (1) |
763/// | constraint_column_names | list<utf8> not null | (2) |
764/// | constraint_column_usage | list<USAGE_SCHEMA> | (3) |
765///
766/// 1. One of 'CHECK', 'FOREIGN KEY', 'PRIMARY KEY', or 'UNIQUE'.
767/// 2. The columns on the current table that are constrained, in
768/// order.
769/// 3. For FOREIGN KEY only, the referenced table and columns.
770///
771/// USAGE_SCHEMA is a Struct with fields:
772///
773/// | Field Name | Field Type |
774/// |--------------------------|-------------------------|
775/// | fk_catalog | utf8 |
776/// | fk_db_schema | utf8 |
777/// | fk_table | utf8 not null |
778/// | fk_column_name | utf8 not null |
779///
780/// \param[in] connection The database connection.
781/// \param[in] depth The level of nesting to display. If 0, display
782/// all levels. If 1, display only catalogs (i.e. catalog_schemas
783/// will be null). If 2, display only catalogs and schemas
784/// (i.e. db_schema_tables will be null), and so on.
785/// \param[in] catalog Only show tables in the given catalog. If NULL,
786/// do not filter by catalog. If an empty string, only show tables
787/// without a catalog. May be a search pattern (see section
788/// documentation).
789/// \param[in] db_schema Only show tables in the given database schema. If
790/// NULL, do not filter by database schema. If an empty string, only show
791/// tables without a database schema. May be a search pattern (see section
792/// documentation).
793/// \param[in] table_name Only show tables with the given name. If NULL, do not
794/// filter by name. May be a search pattern (see section documentation).
795/// \param[in] table_type Only show tables matching one of the given table
796/// types. If NULL, show tables of any type. Valid table types can be fetched
797/// from GetTableTypes. Terminate the list with a NULL entry.
798/// \param[in] column_name Only show columns with the given name. If
799/// NULL, do not filter by name. May be a search pattern (see
800/// section documentation).
801/// \param[out] out The result set.
802/// \param[out] error Error details, if an error occurs.
803ADBC_EXPORT
804AdbcStatusCode AdbcConnectionGetObjects(struct AdbcConnection *connection, int depth, const char *catalog,
805 const char *db_schema, const char *table_name, const char **table_type,
806 const char *column_name, struct ArrowArrayStream *out, struct AdbcError *error);
807
808/// \brief Get the Arrow schema of a table.
809///
810/// \param[in] connection The database connection.
811/// \param[in] catalog The catalog (or nullptr if not applicable).
812/// \param[in] db_schema The database schema (or nullptr if not applicable).
813/// \param[in] table_name The table name.
814/// \param[out] schema The table schema.
815/// \param[out] error Error details, if an error occurs.
816ADBC_EXPORT
817AdbcStatusCode AdbcConnectionGetTableSchema(struct AdbcConnection *connection, const char *catalog,
818 const char *db_schema, const char *table_name, struct ArrowSchema *schema,
819 struct AdbcError *error);
820
821/// \brief Get a list of table types in the database.
822///
823/// The result is an Arrow dataset with the following schema:
824///
825/// Field Name | Field Type
826/// ---------------|--------------
827/// table_type | utf8 not null
828///
829/// \param[in] connection The database connection.
830/// \param[out] out The result set.
831/// \param[out] error Error details, if an error occurs.
832ADBC_EXPORT
833AdbcStatusCode AdbcConnectionGetTableTypes(struct AdbcConnection *connection, struct ArrowArrayStream *out,
834 struct AdbcError *error);
835
836/// @}
837
838/// \defgroup adbc-connection-partition Partitioned Results
839/// Some databases may internally partition the results. These
840/// partitions are exposed to clients who may wish to integrate them
841/// with a threaded or distributed execution model, where partitions
842/// can be divided among threads or machines for processing.
843///
844/// Drivers are not required to support partitioning.
845///
846/// Partitions are not ordered. If the result set is sorted,
847/// implementations should return a single partition.
848///
849/// @{
850
851/// \brief Construct a statement for a partition of a query. The
852/// results can then be read independently.
853///
854/// A partition can be retrieved from AdbcPartitions.
855///
856/// \param[in] connection The connection to use. This does not have
857/// to be the same connection that the partition was created on.
858/// \param[in] serialized_partition The partition descriptor.
859/// \param[in] serialized_length The partition descriptor length.
860/// \param[out] out The result set.
861/// \param[out] error Error details, if an error occurs.
862ADBC_EXPORT
863AdbcStatusCode AdbcConnectionReadPartition(struct AdbcConnection *connection, const uint8_t *serialized_partition,
864 size_t serialized_length, struct ArrowArrayStream *out,
865 struct AdbcError *error);
866
867/// @}
868
869/// \defgroup adbc-connection-transaction Transaction Semantics
870///
871/// Connections start out in auto-commit mode by default (if
872/// applicable for the given vendor). Use AdbcConnectionSetOption and
873/// ADBC_CONNECTION_OPTION_AUTO_COMMIT to change this.
874///
875/// @{
876
877/// \brief Commit any pending transactions. Only used if autocommit is
878/// disabled.
879///
880/// Behavior is undefined if this is mixed with SQL transaction
881/// statements.
882ADBC_EXPORT
883AdbcStatusCode AdbcConnectionCommit(struct AdbcConnection *connection, struct AdbcError *error);
884
885/// \brief Roll back any pending transactions. Only used if autocommit
886/// is disabled.
887///
888/// Behavior is undefined if this is mixed with SQL transaction
889/// statements.
890ADBC_EXPORT
891AdbcStatusCode AdbcConnectionRollback(struct AdbcConnection *connection, struct AdbcError *error);
892
893/// @}
894
895/// @}
896
897/// \addtogroup adbc-statement
898/// @{
899
900/// \brief Create a new statement for a given connection.
901///
902/// Callers pass in a zero-initialized AdbcStatement.
903///
904/// Drivers should allocate their internal data structure and set the private_data
905/// field to point to the newly allocated struct. This struct should be released
906/// when AdbcStatementRelease is called.
907ADBC_EXPORT
908AdbcStatusCode AdbcStatementNew(struct AdbcConnection *connection, struct AdbcStatement *statement,
909 struct AdbcError *error);
910
911/// \brief Destroy a statement.
912/// \param[in] statement The statement to release.
913/// \param[out] error An optional location to return an error
914/// message if necessary.
915ADBC_EXPORT
916AdbcStatusCode AdbcStatementRelease(struct AdbcStatement *statement, struct AdbcError *error);
917
918/// \brief Execute a statement and get the results.
919///
920/// This invalidates any prior result sets.
921///
922/// \param[in] statement The statement to execute.
923/// \param[out] out The results. Pass NULL if the client does not
924/// expect a result set.
925/// \param[out] rows_affected The number of rows affected if known,
926/// else -1. Pass NULL if the client does not want this information.
927/// \param[out] error An optional location to return an error
928/// message if necessary.
929ADBC_EXPORT
930AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement *statement, struct ArrowArrayStream *out,
931 int64_t *rows_affected, struct AdbcError *error);
932
933/// \brief Turn this statement into a prepared statement to be
934/// executed multiple times.
935///
936/// This invalidates any prior result sets.
937ADBC_EXPORT
938AdbcStatusCode AdbcStatementPrepare(struct AdbcStatement *statement, struct AdbcError *error);
939
940/// \defgroup adbc-statement-sql SQL Semantics
941/// Functions for executing SQL queries, or querying SQL-related
942/// metadata. Drivers are not required to support both SQL and
943/// Substrait semantics. If they do, it may be via converting
944/// between representations internally.
945/// @{
946
947/// \brief Set the SQL query to execute.
948///
949/// The query can then be executed with AdbcStatementExecute. For
950/// queries expected to be executed repeatedly, AdbcStatementPrepare
951/// the statement first.
952///
953/// \param[in] statement The statement.
954/// \param[in] query The query to execute.
955/// \param[out] error Error details, if an error occurs.
956ADBC_EXPORT
957AdbcStatusCode AdbcStatementSetSqlQuery(struct AdbcStatement *statement, const char *query, struct AdbcError *error);
958
959/// @}
960
961/// \defgroup adbc-statement-substrait Substrait Semantics
962/// Functions for executing Substrait plans, or querying
963/// Substrait-related metadata. Drivers are not required to support
964/// both SQL and Substrait semantics. If they do, it may be via
965/// converting between representations internally.
966/// @{
967
968/// \brief Set the Substrait plan to execute.
969///
970/// The query can then be executed with AdbcStatementExecute. For
971/// queries expected to be executed repeatedly, AdbcStatementPrepare
972/// the statement first.
973///
974/// \param[in] statement The statement.
975/// \param[in] plan The serialized substrait.Plan to execute.
976/// \param[in] length The length of the serialized plan.
977/// \param[out] error Error details, if an error occurs.
978ADBC_EXPORT
979AdbcStatusCode AdbcStatementSetSubstraitPlan(struct AdbcStatement *statement, const uint8_t *plan, size_t length,
980 struct AdbcError *error);
981
982/// @}
983
984/// \brief Bind Arrow data. This can be used for bulk inserts or
985/// prepared statements.
986///
987/// \param[in] statement The statement to bind to.
988/// \param[in] values The values to bind. The driver will call the
989/// release callback itself, although it may not do this until the
990/// statement is released.
991/// \param[in] schema The schema of the values to bind.
992/// \param[out] error An optional location to return an error message
993/// if necessary.
994ADBC_EXPORT
995AdbcStatusCode AdbcStatementBind(struct AdbcStatement *statement, struct ArrowArray *values, struct ArrowSchema *schema,
996 struct AdbcError *error);
997
998/// \brief Bind Arrow data. This can be used for bulk inserts or
999/// prepared statements.
1000/// \param[in] statement The statement to bind to.
1001/// \param[in] stream The values to bind. The driver will call the
1002/// release callback itself, although it may not do this until the
1003/// statement is released.
1004/// \param[out] error An optional location to return an error message
1005/// if necessary.
1006ADBC_EXPORT
1007AdbcStatusCode AdbcStatementBindStream(struct AdbcStatement *statement, struct ArrowArrayStream *stream,
1008 struct AdbcError *error);
1009
1010/// \brief Get the schema for bound parameters.
1011///
1012/// This retrieves an Arrow schema describing the number, names, and
1013/// types of the parameters in a parameterized statement. The fields
1014/// of the schema should be in order of the ordinal position of the
1015/// parameters; named parameters should appear only once.
1016///
1017/// If the parameter does not have a name, or the name cannot be
1018/// determined, the name of the corresponding field in the schema will
1019/// be an empty string. If the type cannot be determined, the type of
1020/// the corresponding field will be NA (NullType).
1021///
1022/// This should be called after AdbcStatementPrepare.
1023///
1024/// \return ADBC_STATUS_NOT_IMPLEMENTED if the schema cannot be determined.
1025ADBC_EXPORT
1026AdbcStatusCode AdbcStatementGetParameterSchema(struct AdbcStatement *statement, struct ArrowSchema *schema,
1027 struct AdbcError *error);
1028
1029/// \brief Set a string option on a statement.
1030ADBC_EXPORT
1031AdbcStatusCode AdbcStatementSetOption(struct AdbcStatement *statement, const char *key, const char *value,
1032 struct AdbcError *error);
1033
1034/// \addtogroup adbc-statement-partition
1035/// @{
1036
1037/// \brief Execute a statement and get the results as a partitioned
1038/// result set.
1039///
1040/// \param[in] statement The statement to execute.
1041/// \param[out] schema The schema of the result set.
1042/// \param[out] partitions The result partitions.
1043/// \param[out] rows_affected The number of rows affected if known,
1044/// else -1. Pass NULL if the client does not want this information.
1045/// \param[out] error An optional location to return an error
1046/// message if necessary.
1047/// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver does not support
1048/// partitioned results
1049ADBC_EXPORT
1050AdbcStatusCode AdbcStatementExecutePartitions(struct AdbcStatement *statement, struct ArrowSchema *schema,
1051 struct AdbcPartitions *partitions, int64_t *rows_affected,
1052 struct AdbcError *error);
1053
1054/// @}
1055
1056/// @}
1057
1058/// \addtogroup adbc-driver
1059/// @{
1060
1061/// \brief Common entry point for drivers via the driver manager
1062/// (which uses dlopen(3)/LoadLibrary). The driver manager is told
1063/// to load a library and call a function of this type to load the
1064/// driver.
1065///
1066/// Although drivers may choose any name for this function, the
1067/// recommended name is "AdbcDriverInit".
1068///
1069/// \param[in] version The ADBC revision to attempt to initialize (see
1070/// ADBC_VERSION_1_0_0).
1071/// \param[out] driver The table of function pointers to
1072/// initialize. Should be a pointer to the appropriate struct for
1073/// the given version (see the documentation for the version).
1074/// \param[out] error An optional location to return an error message
1075/// if necessary.
1076/// \return ADBC_STATUS_OK if the driver was initialized, or
1077/// ADBC_STATUS_NOT_IMPLEMENTED if the version is not supported. In
1078/// that case, clients may retry with a different version.
1079typedef AdbcStatusCode (*AdbcDriverInitFunc)(int version, void *driver, struct AdbcError *error);
1080
1081/// @}
1082
1083#endif // ADBC
1084
1085#ifdef __cplusplus
1086}
1087#endif
1088} // namespace duckdb_adbc
1089