Package 'adbi'

Adbi driver

Description

In order to open a database connection, DBI::dbConnect() dispatches on a driver object, which can be instantiated by calling adbi().

Usage

adbi(driver = NA_character_)

## S4 method for signature 'AdbiDriver'
dbConnect(drv, ..., bigint = NULL)

## S4 method for signature 'AdbiConnection'
dbDisconnect(conn, force = getOption("adbi.force_close_results", FALSE), ...)

Arguments

driver	A driver specification that can be evaluated (with no arguments) to give an adbcdrivermanager::adbc_driver(). See Details for more information.
drv	An object that inherits from DBI::DBIDriver, or an existing DBI::DBIConnection object (in order to clone an existing connection).
...	Extra arguments passed to DBI::dbConnect() are forwarded to adbcdrivermanager::adbc_database_init()
bigint	The R type that 64-bit integer types should be mapped to, default is bit64::integer64, if bit64 is installed and character otherwise
conn	A DBI::DBIConnection object, as returned by DBI::dbConnect().
force	Close open results when disconnecting

Details

To specify the type of adbc driver, adbi accepts as driver argument

• an object inheriting from adbc_driver,

• a function that can be evaluated with no arguments and returns an object inheriting from adbc_driver,

• a string of the form pkg::fun (where ⁠pkg::⁠ is optional and defaults to fun), which can be used to look up such a function.

As default, an adbcdrivermanager::adbc_driver_monkey() object is created.

Value

A connection object (S4 class AdbiCOnnection, inheriting from DBI::DBIConnection) is returned by DBI::dbConnect(), while DBI::dbDisconnect() returns TRUE invisibly.

Examples

adbi()
if (requireNamespace("adbcsqlite")) {
  adbi("adbcsqlite")
}
library(DBI)
con <- dbConnect(adbi())
dbIsValid(con)
dbDisconnect(con)
dbIsValid(con)

---

Fetch result sets

Description

When fetching results using DBI::dbFetch(), the argument n can be specified to control chunk size per fetching operation. The default value of -1 corresponds to retrieving the entire result set at once, while a positive integer will try returning as many rows (as long as n does not exceed the available number of rows), in line with standard DBI expectations. As data transfer is mediated by Arrow data structures, which are retrieved as array chunks, the underlying chunk size can be used by passing an n value NA.

Usage

## S4 method for signature 'AdbiResult'
dbFetch(res, n = -1, ...)

Arguments

res	An object inheriting from DBI::DBIResult, created by DBI::dbSendQuery().
n	maximum number of records to retrieve per fetch. Use n = -1 or n = Inf to retrieve all pending records. Some implementations may recognize other special values.
...	Other arguments passed on to methods.

Value

A data.frame with the requested number of rows (or zero rows if DBI::dbFetch() is called on a result set with no more remaining rows).

Examples

if (requireNamespace("adbcsqlite")) {
  library(DBI)
  con <- dbConnect(adbi::adbi("adbcsqlite"), uri = ":memory:")
  dbWriteTable(con, "swiss", swiss)
  res <- dbSendQuery(con, "SELECT * from swiss WHERE Agriculture < 30")
  dbFetch(res)
  dbClearResult(res)
  dbDisconnect(con)
}

---

Create result sets

Description

Creating result sets using DBI::dbSendQuery() (and by extension using DBI::dbGetQuery()) mostly follows DBI specification. One way where adbi deviates from DBI mechanisms is how the bigint setting is not only per connection, but the per-connection setting can be overridden on a result set basis. As default, the connection setting is applied, but passing one of the accepted values as bigint when creating a result set will subsequently use that setting for all fetches using this result set.

Usage

## S4 method for signature 'AdbiConnection'
dbSendQueryArrow(
  conn,
  statement,
  ...,
  params = NULL,
  immediate = NULL,
  bigint = NULL
)

## S4 method for signature 'AdbiConnection,character'
dbSendQuery(
  conn,
  statement,
  ...,
  params = NULL,
  immediate = NULL,
  bigint = NULL
)

## S4 method for signature 'AdbiConnection,character'
dbSendStatement(
  conn,
  statement,
  ...,
  params = NULL,
  immediate = NULL,
  bigint = NULL
)

Arguments

conn	A DBI::DBIConnection object, as returned by DBI::dbConnect().
statement	a character string containing SQL.
...	Other parameters passed on to methods.
params	Optional query parameters (forwarded to DBI::dbBind())
immediate	Passing a value TRUE is intended for statements containing no placeholders and FALSE otherwise. The default value NULL will inspect the statement for presence of placeholders (will PREPARE the statement)
bigint	The R type that 64-bit integer types should be mapped to, default is chosen according to the connection setting

Details

Multiple open result sets per connection are supported and support can be disabled by setting options(adbi.allow_multiple_results = FALSE). If not enabled, creating a new result will finalize potential other results and throw a warning.

Value

An S4 class AdbiResult (inheriting from DBI::DBIResult).

See Also

adbi-driver

Examples

if (requireNamespace("adbcsqlite")) {
  library(DBI)
  con <- dbConnect(adbi::adbi("adbcsqlite"), uri = ":memory:")
  dbWriteTable(con, "swiss", swiss)
  str(
    dbGetQuery(con, "SELECT Examination from swiss WHERE Agriculture < 30")
  )
  str(
    dbGetQuery(con, "SELECT Examination from swiss WHERE Agriculture < 30",
      bigint = "integer")
  )
  dbDisconnect(con)
}

---