% 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(),
  ...,
  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{...}{Reserved for future extensions, must be empty.}

\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 returned to R, defaults to \code{"UTC"}, which
is currently the only timezone supported by duckdb.
If you want to display datetime values in the local timezone,
set to \code{\link[=Sys.timezone]{Sys.timezone()}} or \code{""}.}

\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.
}
\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}
}
