% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Driver.R, R/dbConnect__duckdb_driver.R,
%   R/dbDisconnect__duckdb_connection.R
\name{duckdb}
\alias{duckdb}
\alias{duckdb_shutdown}
\alias{duckdb_adbc}
\alias{dbConnect__duckdb_driver}
\alias{dbConnect,duckdb_driver-method}
\alias{dbDisconnect__duckdb_connection}
\alias{dbDisconnect,duckdb_connection-method}
\title{Connect to a DuckDB database instance}
\usage{
duckdb(
  dbdir = DBDIR_MEMORY,
  read_only = FALSE,
  bigint = "numeric",
  config = list(),
  ...,
  home = NULL,
  shared_home = NULL,
  allow_extensions = NULL,
  environment_scan = FALSE
)

duckdb_shutdown(drv)

duckdb_adbc()

\S4method{dbConnect}{duckdb_driver}(
  drv,
  dbdir = DBDIR_MEMORY,
  ...,
  debug = getOption("duckdb.debug", FALSE),
  read_only = FALSE,
  timezone_out = "UTC",
  tz_out_convert = c("with", "force"),
  config = list(),
  bigint = "numeric",
  array = "none",
  geometry = "blob",
  map = "data.frame"
)

\S4method{dbDisconnect}{duckdb_connection}(conn, ..., shutdown = TRUE)
}
\arguments{
\item{dbdir}{Location for database files. Should be a path to an existing
directory in the file system. With the default (or \code{""}), all
data is kept in RAM.}

\item{read_only}{Set to \code{TRUE} for read-only operation.
For file-based databases, this is only applied when the database file is opened for the first time.
Subsequent connections (via the same \code{drv} object or a \code{drv} object pointing to the same path)
will silently ignore this flag.}

\item{bigint}{How 64-bit integers should be returned. There are two options: \code{"numeric"} and \code{"integer64"}.
If \code{"numeric"} is selected, bigint integers will be treated as double/numeric.
If \code{"integer64"} is selected, bigint integers will be set to bit64 encoding.}

\item{config}{Named list with DuckDB configuration flags, see
\url{https://duckdb.org/docs/configuration/overview#configuration-reference} for the possible options.
These flags are only applied when the database object is instantiated.
Subsequent connections will silently ignore these flags.}

\item{...}{These dots are for future extensions and must be empty.}

\item{home}{Root directory for DuckDB's downloaded extensions and stored secrets.
\code{NULL} (the default) resolves the location as described in \link{duckdb_storage}:
an existing \verb{~/.duckdb}, else a per-session temporary directory
(with an offer to create \verb{~/.duckdb} in interactive sessions).
Pass a path to use it as the root explicitly, creating it if needed.
Cannot be combined with \code{shared_home}.
Applied only when the database instance is created;
see the \sQuote{Database instances and driver reuse} section.}

\item{shared_home}{Opt in or out of the shared \verb{~/.duckdb} location,
overriding the automatic resolution.
One of:
\itemize{
\item \code{NULL} (the default) -- resolve automatically (see \link{duckdb_storage}).
This is the safe default.
\item \code{TRUE} -- store extensions and secrets under \verb{~/.duckdb}, \strong{creating that
directory if it does not exist}.
This is a good setting for permanent deployments (Posit Connect, Shiny, APIs).
Do not use on CRAN or on other infrastructure where you don't own \verb{~/.duckdb}.

The setting is a durable, machine-level side effect that is \emph{not} scoped to the current session:
the directory persists after R exits, is reused by every future R session
(and by the DuckDB CLI, Python and other clients that share \verb{~/.duckdb}),
and any secrets written there outlive this process.
Applying this setting repeatedly is a fast no-op.
\item \code{FALSE} -- use a per-session temporary directory even if \verb{~/.duckdb}
already exists. Nothing persists beyond the session.
}

Cannot be combined with \code{home}.
Applied only when the database instance is created;
see the \sQuote{Database instances and driver reuse} section.}

\item{allow_extensions}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
Whether this driver may load DuckDB extensions (\code{INSTALL} / \code{LOAD}).
One of:
\itemize{
\item \code{NULL} (the default) -- decide automatically.
Extensions are enabled,
except on an affected Linux build (one not compiled with \verb{libstdc++}),
where they are disabled and a throttled advisory message is shown.
See the \sQuote{DuckDB extensions on Linux} section.
\item \code{TRUE} -- force-enable extensions,
attempting to load them even on an affected build (which may crash R).
No message.
\item \code{FALSE} -- disable extensions and silence the advisory message.
}

The argument takes precedence over the \code{duckdb.allow_extensions} option (a scalar logical)
and the \code{DUCKDB_R_ALLOW_EXTENSIONS} environment variable
(a value R reads as \code{TRUE} enables extensions and \code{FALSE} disables them;
unset, empty, or any other value is undecided).
Applied only when the database instance is created;
see the \sQuote{Database instances and driver reuse} section.}

\item{environment_scan}{Set to \code{TRUE} to treat
data frames from the calling environment as tables.
If a database table with the same name exists, it takes precedence.
The default of this setting may change in a future version.}

\item{drv}{Object returned by \code{duckdb()}}

\item{debug}{Print additional debug information, such as queries.}

\item{timezone_out}{The time zone in which plain \code{TIMESTAMP} columns
(without time zone) are returned to R, defaults to \code{"UTC"}.
If you want to display datetime values in the local timezone,
set to \code{\link[=Sys.timezone]{Sys.timezone()}} or \code{""}.
\code{TIMESTAMPTZ} columns follow the session's \code{TimeZone} setting instead.}

\item{tz_out_convert}{How to convert timestamp columns to the timezone specified
in \code{timezone_out}. There are two options: \code{"with"}, and \code{"force"}. If \code{"with"}
is chosen, the timestamp will be returned as it would appear in the specified time zone.
If \code{"force"} is chosen, the timestamp will have the same clock
time as the timestamp in the database, but with the new time zone.}

\item{array}{How arrays should be returned. There are two options: \code{"none"} and \code{"matrix"}.
If \code{"none"} is selected, arrays are not returned. Instead an error is generated.
If \code{"matrix"} is selected, arrays are returned as a column matrix. Each array is one row in the matrix.}

\item{geometry}{How geometry columns should be returned. There are two options: \code{"blob"} and \code{"wk"}.
If \code{"blob"} is selected, geometry columns are returned as a list of raw vectors containing WKB data.
If \code{"wk"} is selected, geometry columns are returned as \pkg{wk} \code{wk_wkb} vectors.
Use \code{\link[wk:wk_handle]{wk::wk_handle()}} or \code{\link[sf:st_as_sfc]{sf::st_as_sfc()}} to convert to other geometry formats.}

\item{map}{How \code{MAP} columns should be returned. There are two options: \code{"data.frame"} and \code{"list_of"}.
If \code{"data.frame"} is selected (the default), \code{MAP} columns are returned as a list of data frames with
\code{key} and \code{value} columns.
If \code{"list_of"} is selected, \code{MAP} columns are returned as a \code{\link[vctrs:list_of]{vctrs::list_of()}} whose \code{ptype} is a
\verb{data.frame(key = <K>, value = <V>)} that records the SQL key/value types. This enables MAP columns
to round-trip through \code{\link[DBI:dbWriteTable]{dbWriteTable()}} / \code{\link[DBI:dbCreateTable]{dbCreateTable()}} without specifying \code{field.types},
and lets scans accept named-list cells as MAP entries.}

\item{conn}{A \code{duckdb_connection} object}

\item{shutdown}{Unused. The database instance is shut down automatically.}
}
\value{
\code{duckdb()} returns an object of class \link[=duckdb_driver-class]{duckdb_driver}.

\code{dbDisconnect()} and \code{duckdb_shutdown()} are called for their
side effect.

An object of class "adbc_driver"

\code{dbConnect()} returns an object of class \link[=duckdb_connection-class]{duckdb_connection}.
}
\description{
\code{duckdb()} creates or reuses a database instance.

\code{duckdb_shutdown()} shuts down a database instance.

Return an \code{\link[adbcdrivermanager:adbc_driver]{adbcdrivermanager::adbc_driver()}} for use with Arrow Database
Connectivity via the adbcdrivermanager package.

\code{dbConnect()} connects to a database instance.

\code{dbDisconnect()} closes a DuckDB database connection.
The associated DuckDB database instance is shut down automatically,
it is no longer necessary to set \code{shutdown = TRUE} or to call \code{duckdb_shutdown()}.
}
\details{
The behavior of \code{with = "force"} at DST transitions depends on how R handles translation from
the underlying time representation to a human-readable format.
If the timestamp is invalid in the target timezone, the resulting value may be \code{NA}
or an adjusted time.
}
\section{Database instances and driver reuse}{


\code{duckdb()} returns a driver object that owns a DuckDB \emph{database instance}.
\code{dbConnect()} opens connections to that instance,
and many connections can share one instance.

For a file-based \code{dbdir}, the instance is cached, keyed by the (normalized) path:
calling \code{duckdb()} again with the same \code{dbdir} returns the same driver and instance
while it is still alive.
This is deliberate.
DuckDB allows only a single read-write handle to a database file at a time,
so opening a second instance of the same file would fail with a lock error.
Reusing one instance instead lets any number of \code{dbConnect(duckdb(dbdir = "my.db"))} calls share it.
An in-memory database (\verb{:memory:}, the default) has no file to lock and is never cached:
every \code{duckdb()} call creates a fresh, isolated instance.

Because the instance is created once per database file,
\code{config}, \code{read_only}, \code{home}, and \code{shared_home} take effect only at creation.
A call that reuses an existing instance ignores them.
To apply different values to a file-based database --
for example to reopen it read-only, or to send extensions and secrets elsewhere --
first release the instance with \code{\link[=duckdb_shutdown]{duckdb_shutdown()}}, which also drops it from the cache,
then create it again.
\code{\link[DBI:dbDisconnect]{dbDisconnect()}} only closes a connection,
it does not release the instance, and its \code{shutdown} argument is unused.
Instances are shut down automatically when the driver is garbage-collected or the session ends.
}

\section{DuckDB extensions on Linux}{


DuckDB's prebuilt extensions for Linux are compiled with the GNU C++ standard library (\verb{libstdc++}).
Loading one into a \code{duckdb} package that was itself built with a \emph{different} C++ standard library --
most commonly \verb{libc++} (clang's \verb{-stdlib=libc++}) --
is an ABI mismatch that crashes R (\url{https://github.com/duckdb/duckdb-r/issues/1107}).
Almost all Linux builds (CRAN binaries and most source installs) use \verb{libstdc++} and are unaffected;
macOS and Windows are unaffected.

Each \code{duckdb()} call decides whether the driver it returns may load extensions,
via the \code{allow_extensions} argument, the \code{duckdb.allow_extensions} option,
the \code{DUCKDB_R_ALLOW_EXTENSIONS} environment variable, or automatic detection.
On the automatic path a build that was not compiled with \verb{libstdc++} on Linux disables extensions:
\code{INSTALL} / \code{LOAD} raise a clear error instead of crashing,
automatic extension install/load is turned off,
and a throttled advisory message is shown when \code{duckdb()} is called.
Pass \code{allow_extensions = FALSE} to disable extensions and silence that message,
or \code{allow_extensions = TRUE} to attempt loading anyway (which may still crash R).

The decision is carried on the returned driver as the experimental \code{allow_extensions} slot
(see \link[=duckdb_driver-class]{duckdb_driver}).
}

\examples{
\dontshow{if (simulate_duckdb()$env$examples_enabled() && requireNamespace("adbcdrivermanager", quietly = TRUE)) withAutoprint(\{ # examplesIf}
library(adbcdrivermanager)
with_adbc(db <- adbc_database_init(duckdb_adbc()), {
  as.data.frame(read_adbc(db, "SELECT 1 as one;"))
})
\dontshow{\}) # examplesIf}
\dontshow{if (simulate_duckdb()$env$examples_enabled()) withAutoprint(\{ # examplesIf}
drv <- duckdb()
con <- dbConnect(drv)

dbGetQuery(con, "SELECT 'Hello, world!'")

dbDisconnect(con)
duckdb_shutdown(drv)

# Shorter:
con <- dbConnect(duckdb())
dbGetQuery(con, "SELECT 'Hello, world!'")
dbDisconnect(con, shutdown = TRUE)
\dontshow{\}) # examplesIf}
}
