duckdb
DuckDB is an in-process SQL OLAP database management system.
It is designed to support analytical query workloads and is optimized for fast query execution.
This repository contains the R bindings for DuckDB.
Goals and non-goals
duckdb aims to:
- Implement the DBI interface for DuckDB,
from the driver and connections through prepared statements, transactions, and result fetching.
- Install the database along with the package:
the DuckDB C++ sources are vendored into
src/duckdb/ and built here, so nothing has to be installed separately.
- Follow upstream DuckDB closely, with an automated vendoring routine advancing each release series commit by commit,
and publish the same source tree under the flavor names listed below.
- Meet the rest of the R ecosystem where it already is:
a dbplyr backend, data frames and Arrow objects registered as tables, and CSV files read by the engine directly.
- Leave the file system alone unless asked:
downloaded extensions and stored secrets go under the session's temporary directory unless
~/.duckdb already exists,
and that directory is never created without consent.
It is explicitly not trying to:
- Bundle every DuckDB extension.
Only
parquet and core_functions are linked in;
everything else is downloaded by INSTALL, and no companion R package carries extensions.
- Fetch anything on its own.
An installed extension autoloads on first use, but autoinstall stays off, so nothing is downloaded without being asked for.
- Expose the relational API as a public interface.
Every function there is internal, and duckplyr is the one supported consumer.
- Install the
duckdb CLI or library that the user can use outside of R.
- Exercise the bundled C++ engine on CRAN.
The test suite and the runnable examples are too heavy for the check farm,
so they run on GitHub Actions and r-universe, and elsewhere only when
DUCKDB_R_RUN_TESTS asks for them.
Installation from CRAN
This is the recommended method for recent R versions on Windows or macOS which have binaries available on CRAN.
install.packages("duckdb")
For Linux or older R versions, installing the package from source may take up to an hour.
Consider the Posit Public Package Manager or r-universe for binary installs (see the next sections).
Installation from the Posit Public Package Manager
This repository serves binary builds of CRAN packages for a wide variety of platforms.
Follow setup instructions from https://p3m.dev/client/#/repos/cran/setup.
For example, to install the ManyLinux version of duckdb that is likely to work on your Linux, use:
install.packages("duckdb", repos = sprintf(
"https://p3m.dev/cran/latest/bin/linux/manylinux_2_28-%s/%s", R.version["arch"], substr(getRversion(), 1, 3)
))
To check the availability of binaries for your platform,
navigate to the duckdb search page.
Installation from r-universe
This repository serves development versions.
Binaries are available for recent versions of R and for some platforms.
Review https://docs.r-universe.dev/install/binaries.html for configuring installation of binary packages on Linux.
install.packages("duckdb", repos = c("https://duckdb.r-universe.dev", "https://cloud.r-project.org"))
Installing the package from source may take up to an hour.
Installation from GitHub
# install.packages("pak", repos = sprintf("https://r-lib.github.io/p/pak/stable/%s/%s/%s", .Platform$pkgType, R.Version()$os, R.Version()$arch))
pak::pak("duckdb/duckdb-r")
Installing the package from GitHub may take up to an hour.
Flavors
The sources in this repository are published under several names —
duckdb on CRAN,
and every flavor on r-universe.
The .dev flavors are created by an automated vendoring process;
the CRAN and LTS flavors always point at a stable upstream release.
Every row opens with the versions published, one badge per place it is
published from, and the flavor's name is a link on those rather than on the name
itself. Only duckdb is in two: CRAN releases it, and r-universe rebuilds the
same source between releases.
The three after it track a .dev series:
ahead counts commits ahead of the branch the series releases from,
in flight counts commits in CI but not yet trusted,
buffered counts commits vendored but not yet verified.
ahead is counted here, where the branch a series releases from lives and
<S>-green is mirrored to; the other two are counted in the fork, which is the
only repository carrying <S>-dev and <S>-build.
So the two greens either side of in flight are the same commit because one
push writes both and the loop stops if the second cannot fast-forward.
Upstream keeps every release branch it ever cut.
The following series are only available in the package archives:
See the handbook's
branches/
for the full model.
User Guide
See the R API in the DuckDB documentation.
Documentation
Everything this repository documents is reachable from the
handbook,
a strict topic hierarchy;
AGENTS.md
is the door for maintainers and coding agents, and
plan/README.md
names the designs, plans, and historical documents.
BRANCHES.md and
scripts/VENDORING.md
hold detail the handbook is still absorbing.
Building
To build the R package, you first need to clone this repository and install the dependencies:
# install.packages("pak", repos = sprintf("https://r-lib.github.io/p/pak/stable/%s/%s/%s", .Platform$pkgType, R.Version()$os, R.Version()$arch))
pak::pak()
Then, install:
~duckdb-r: R CMD INSTALL .
Set the MAKEFLAGS environment variable to -j8 or similar for parallel builds.
Configure ccache for faster repeated builds.
A build that links a prebuilt engine and finishes in seconds,
and other details, are described in the handbook under
build/.
Vendoring
This package includes a vendored copy of the DuckDB C++ library.
The vendoring process is automated —
a scheduled routine synchronizes each release series with the upstream DuckDB repository, commit by commit.
How it works, and how to vendor by hand, is in the handbook under operations/vendoring/.
Contributors
Thanks to all contributors to this repository,
and to those who contributed when the code was still hosted in the main duckdb/duckdb repository:
Mark Raasveldt, Pedro Holanda, Tom Ebergen, Reijo Sund, Nicolas Bennett, Patrik Schratz, Tishj, Laurens Kuiper, Sam Ansmink, Andy Teucher, Hadley Wickham, Jonathan Keane, Lindsay Wray, Richard Wesley, Elliana May, Edwin de Jonge, Dewey Dunnington, Carlo Piovesan, Andre Beckedorf, Tania Bogatsch, Pedro Ferreira, Maximilian Girlich, James Lamb, James Atkins, usurai, Ubuntu, Noam Ross, Michael Antonov, Jeroen Ooms, Jamie Lentin, Jacob, and Chilarai.
