Title:	'Arrow' Database Connectivity ('ADBC') Driver Manager
Version:	0.19.0-1
Description:	Provides a developer-facing interface to 'Arrow' Database Connectivity ('ADBC') for the purposes of driver development, driver testing, and building high-level database interfaces for users. 'ADBC' https://arrow.apache.org/adbc/ is an API standard for database access libraries that uses 'Arrow' for result sets and query parameters.
License:	Apache License (≥ 2)
Encoding:	UTF-8
RoxygenNote:	7.3.2
Suggests:	testthat (≥ 3.0.0), withr
Config/testthat/edition:	3
Config/build/bootstrap:	TRUE
URL:	https://arrow.apache.org/adbc/current/r/adbcdrivermanager/, https://github.com/apache/arrow-adbc
BugReports:	https://github.com/apache/arrow-adbc/issues
Imports:	nanoarrow (≥ 0.3.0)
NeedsCompilation:	yes
Packaged:	2025-07-19 19:06:25 UTC; dewey
Author:	Dewey Dunnington [aut, cre], Apache Arrow [aut, cph], Apache Software Foundation [cph]
Maintainer:	Dewey Dunnington <dewey@dunnington.ca>
Repository:	CRAN
Date/Publication:	2025-07-20 19:30:02 UTC

adbcdrivermanager: 'Arrow' Database Connectivity ('ADBC') Driver Manager

Description

Provides a developer-facing interface to 'Arrow' Database Connectivity ('ADBC') for the purposes of driver development, driver testing, and building high-level database interfaces for users. 'ADBC' https://arrow.apache.org/adbc/ is an API standard for database access libraries that uses 'Arrow' for result sets and query parameters.

Author(s)

Maintainer: Dewey Dunnington dewey@dunnington.ca (ORCID)

Authors:

• Apache Arrow dev@arrow.apache.org [copyright holder]

Other contributors:

• Apache Software Foundation dev@arrow.apache.org [copyright holder]

See Also

Useful links:

• https://arrow.apache.org/adbc/current/r/adbcdrivermanager/

• https://github.com/apache/arrow-adbc

• Report bugs at https://github.com/apache/arrow-adbc/issues

Connection methods

Description

Connection methods

Usage

adbc_connection_get_info(connection, info_codes = NULL)

adbc_connection_get_objects(
  connection,
  depth = 0L,
  catalog = NULL,
  db_schema = NULL,
  table_name = NULL,
  table_type = NULL,
  column_name = NULL
)

adbc_connection_get_table_schema(connection, catalog, db_schema, table_name)

adbc_connection_get_table_types(connection)

adbc_connection_read_partition(connection, serialized_partition)

adbc_connection_commit(connection)

adbc_connection_rollback(connection)

adbc_connection_cancel(connection)

adbc_connection_get_statistic_names(connection)

adbc_connection_get_statistics(
  connection,
  catalog,
  db_schema,
  table_name,
  approximate = FALSE
)

adbc_connection_quote_identifier(connection, value, ...)

adbc_connection_quote_string(connection, value, ...)

Arguments

Value

• adbc_connection_get_info(), adbc_connection_get_objects(), adbc_connection_get_table_types(), and adbc_connection_read_partition() return a nanoarrow_array_stream.

• adbc_connection_get_table_schema() returns a nanoarrow_schena

• adbc_connection_commit() and adbc_connection_rollback() return connection, invisibly.

Examples

db <- adbc_database_init(adbc_driver_void())
con <- adbc_connection_init(db)
# (not implemented by the void driver)
try(adbc_connection_get_info(con, 0))

Connections

Description

Connections

Usage

adbc_connection_init(database, ...)

adbc_connection_init_default(database, options = NULL, subclass = character())

adbc_connection_release(connection)

adbc_connection_set_options(connection, options)

adbc_connection_get_option(connection, option)

adbc_connection_get_option_bytes(connection, option)

adbc_connection_get_option_int(connection, option)

adbc_connection_get_option_double(connection, option)

Arguments

Value

An object of class 'adbc_connection'

Examples

db <- adbc_database_init(adbc_driver_void())
adbc_connection_init(db)

Join the lifecycle of a unique parent to its child

Description

It is occasionally useful to return a connection, statement, or stream from a function that was created from a unique parent. These helpers tie the lifecycle of a unique parent object to its child such that the parent object is released predictably and immediately after the child. These functions will invalidate all references to the previous R object.

Usage

adbc_connection_join(connection, database)

adbc_statement_join(statement, connection)

Arguments

Value

The input, invisibly.

Examples

# Use local_adbc to ensure prompt cleanup on error;
# use join functions to return a single object that manages
# the lifecycle of all three.
stmt <- local({
  db <- local_adbc(adbc_database_init(adbc_driver_log()))

  con <- local_adbc(adbc_connection_init(db))
  adbc_connection_join(con, db)

  stmt <- local_adbc(adbc_statement_init(con))
  adbc_statement_join(stmt, con)

  adbc_xptr_move(stmt)
})

# Everything is released immediately when the last object is released
adbc_statement_release(stmt)

Databases

Description

Databases

Usage

adbc_database_init(driver, ...)

adbc_database_init_default(driver, options = NULL, subclass = character())

adbc_database_release(database)

adbc_database_set_options(database, options)

adbc_database_get_option(database, option)

adbc_database_get_option_bytes(database, option)

adbc_database_get_option_int(database, option)

adbc_database_get_option_double(database, option)

Arguments

Value

An object of class adbc_database

Examples

adbc_database_init(adbc_driver_void())

Low-level driver loader

Description

Most users should use adbc_driver(); however, this function may be used to allow other libraries (e.g., GDAL) to access the driver loader.

Usage

adbc_driver_load(
  x,
  entrypoint,
  version,
  driver,
  error,
  load_flags = adbc_load_flags()
)

Arguments

Value

An integer ADBC status code

Log calls to another driver

Description

Useful for debugging or ensuring that certain calls occur during initialization and/or cleanup. The current logging output should not be considered stable and may change in future releases.

Usage

adbc_driver_log()

Value

An object of class 'adbc_driver_log'

Examples

drv <- adbc_driver_log()
db <- adbc_database_init(drv, key = "value")
con <- adbc_connection_init(db, key = "value")
stmt <- adbc_statement_init(con, key = "value")
try(adbc_statement_execute_query(stmt))
adbc_statement_release(stmt)
adbc_connection_release(con)
adbc_database_release(db)

Monkey see, monkey do!

Description

A driver whose query results are set in advance.

Usage

adbc_driver_monkey()

Value

An object of class 'adbc_driver_monkey'

Examples

db <- adbc_database_init(adbc_driver_monkey())
con <- adbc_connection_init(db)
stmt <- adbc_statement_init(con, mtcars)
stream <- nanoarrow::nanoarrow_allocate_array_stream()
adbc_statement_execute_query(stmt, stream)
as.data.frame(stream$get_next())

Create ADBC drivers

Description

Creates the R object representation of an ADBC driver, which consists of a name and an initializer function with an optional subclass to control finer-grained behaviour at the R level.

Usage

adbc_driver_void()

adbc_driver(
  x,
  entrypoint = NULL,
  ...,
  load_flags = adbc_load_flags(),
  subclass = character()
)

Arguments

Value

An object of class 'adbc_driver'

Examples

adbc_driver_void()

Get extended error information from an array stream

Description

Get extended error information from an array stream

Usage

adbc_error_from_array_stream(stream)

Arguments

Value

NULL if stream was not created by a driver that supports extended error information or a list whose first element is the status code and second element is the adbc_error object. The acbc_error must not be accessed if stream is explicitly released.

Examples

db <- adbc_database_init(adbc_driver_monkey())
con <- adbc_connection_init(db)
stmt <- adbc_statement_init(con, mtcars)
stream <- nanoarrow::nanoarrow_allocate_array_stream()
adbc_statement_execute_query(stmt, stream)
adbc_error_from_array_stream(stream)

Driver search/load options

Description

Options that indicate where to look for driver manifests. Manifests (.toml files) can be installed at the system level, the user level, and/or location(s) specified by the ADBC_CONFIG_PATH environment variable. See the ADBC documentation for details regarding the locations of the user and system paths on various platforms.

Usage

adbc_load_flags(
  search_env = TRUE,
  search_user = TRUE,
  search_system = TRUE,
  allow_relative_paths = TRUE
)

Arguments

Value

An integer flag value for use in adbc_driver()

Statements

Description

Statements

Usage

adbc_statement_init(connection, ...)

adbc_statement_init_default(connection, options = NULL, subclass = character())

adbc_statement_release(statement)

adbc_statement_set_options(statement, options)

adbc_statement_get_option(statement, option)

adbc_statement_get_option_bytes(statement, option)

adbc_statement_get_option_int(statement, option)

adbc_statement_get_option_double(statement, option)

Arguments

Value

An object of class 'adbc_statement'

Examples

db <- adbc_database_init(adbc_driver_void())
con <- adbc_connection_init(db)
adbc_statement_init(con)

Statement methods

Description

Statement methods

Usage

adbc_statement_set_sql_query(statement, query)

adbc_statement_set_substrait_plan(statement, plan)

adbc_statement_prepare(statement)

adbc_statement_get_parameter_schema(statement)

adbc_statement_bind(statement, values, schema = NULL)

adbc_statement_bind_stream(statement, stream, schema = NULL)

adbc_statement_execute_query(
  statement,
  stream = NULL,
  stream_join_parent = FALSE
)

adbc_statement_execute_schema(statement)

adbc_statement_cancel(statement)

Arguments

Value

• adbc_statement_set_sql_query(), adbc_statement_set_substrait_plan(), adbc_statement_prepare(), adbc_statement_bind(), adbc_statement_bind_stream(), and adbc_statement_execute_query() return statement, invisibly.

• adbc_statement_get_parameter_schema() returns a nanoarrow_schema.

Examples

db <- adbc_database_init(adbc_driver_void())
con <- adbc_connection_init(db)
stmt <- adbc_statement_init(con)
# (not implemented by the void driver)
try(adbc_statement_set_sql_query(stmt, "some query"))

Low-level pointer details

Description

• adbc_xptr_move() allocates a fresh R object and moves all values pointed to by x into it. The original R object is invalidated by zeroing its content. This is useful when returning from a function where lifecycle helpers were used to manage the original object.

• adbc_xptr_is_valid() provides a means by which to test for an invalidated pointer.

Usage

adbc_xptr_move(x, check_child_count = TRUE)

adbc_xptr_is_valid(x)

Arguments

Value

• adbc_xptr_move(): A freshly-allocated R object identical to x

• adbc_xptr_is_valid(): Returns FALSE if the ADBC object pointed to by x has been invalidated.

Examples

db <- adbc_database_init(adbc_driver_void())
adbc_xptr_is_valid(db)
db_new <- adbc_xptr_move(db)
adbc_xptr_is_valid(db)
adbc_xptr_is_valid(db_new)

Read, write, and execute on ADBC connections

Description

These are convenience methods useful for testing connections. Note that S3 dispatch is always on db_or_con (i.e., drivers may provide their own implementations).

Usage

read_adbc(db_or_con, query, ..., bind = NULL)

execute_adbc(db_or_con, query, ..., bind = NULL)

write_adbc(
  tbl,
  db_or_con,
  target_table,
  ...,
  mode = c("default", "create", "append"),
  temporary = FALSE
)

Arguments

Value

• read_adbc(): A nanoarrow_array_stream

• execute_adbc(): db_or_con, invisibly.

• write_adbc(): tbl, invisibly.

Examples

# On a database, connections are opened and closed
db <- adbc_database_init(adbc_driver_log())
try(read_adbc(db, "some sql"))
try(execute_adbc(db, "some sql"))
try(write_adbc(mtcars, db, "some_table"))

# Also works on a connection
con <- adbc_connection_init(db)
try(read_adbc(con, "some sql"))
try(execute_adbc(con, "some sql"))
try(write_adbc(mtcars, con, "some_table"))

Cleanup helpers

Description

Managing the lifecycle of databases, connections, and statements can be complex and error-prone. The R objects that wrap the underlying ADBC pointers will perform cleanup in the correct order if you rely on garbage collection (i.e., do nothing and let the objects go out of scope); however it is good practice to explicitly clean up these objects. These helpers are designed to make explicit and predictable cleanup easy to accomplish.

Usage

with_adbc(x, code)

local_adbc(x, .local_envir = parent.frame())

Arguments

Details

Note that you can use adbc_connection_join() and adbc_statement_join() to tie the lifecycle of the parent object to that of the child object. These functions mark any previous references to the parent object as released so you can still use local and with helpers to manage the parent object before it is joined. Use stream_join_parent = TRUE in adbc_statement_execute_query() to tie the lifecycle of a statement to the output stream.

Value

• with_adbc() returns the result of code

• local_adbc() returns the input, invisibly.

Examples

# Using with_adbc():
with_adbc(db <- adbc_database_init(adbc_driver_void()), {
  with_adbc(con <- adbc_connection_init(db), {
    with_adbc(stmt <- adbc_statement_init(con), {
      # adbc_statement_set_sql_query(stmt, "SELECT * FROM foofy")
      # adbc_statement_execute_query(stmt)
      "some result"
    })
  })
})

# Using local_adbc_*() (works best within a function, test, or local())
local({
  db <- local_adbc(adbc_database_init(adbc_driver_void()))
  con <- local_adbc(adbc_connection_init(db))
  stmt <- local_adbc(adbc_statement_init(con))
  # adbc_statement_set_sql_query(stmt, "SELECT * FROM foofy")
  # adbc_statement_execute_query(stmt)
  "some result"
})