duckdb-rs

duckdb-rs is an ergonomic Rust wrapper for DuckDB.

You can use it to:

Query DuckDB with type-safe bindings and an API inspired by rusqlite.
Read and write Arrow, Parquet, JSON, and CSV formats natively.
Create DuckDB extensions in Rust with custom scalar and table functions.

Quickstart

Create a new project and add the duckdb crate:

cargo new quack-in-rust
cd quack-in-rust
cargo add duckdb -F bundled

Update src/main.rs with the following code:

use duckdb::{params, Connection, Result};

struct Duck {
    id: i32,
    name: String,
}

fn main() -> Result<()> {
    let conn = Connection::open_in_memory()?;

    conn.execute(
        "CREATE TABLE ducks (id INTEGER PRIMARY KEY, name TEXT)",
        [], // empty list of parameters
    )?;

    conn.execute_batch(
        r#"
        INSERT INTO ducks (id, name) VALUES (1, 'Donald Duck');
        INSERT INTO ducks (id, name) VALUES (2, 'Scrooge McDuck');
        "#,
    )?;

    conn.execute(
        "INSERT INTO ducks (id, name) VALUES (?, ?)",
        params![3, "Darkwing Duck"],
    )?;

    let ducks = conn
        .prepare("FROM ducks")?
        .query_map([], |row| {
            Ok(Duck {
                id: row.get(0)?,
                name: row.get(1)?,
            })
        })?
        .collect::<Result<Vec<_>>>()?;

    for duck in ducks {
        println!("{}) {}", duck.id, duck.name);
    }

    Ok(())
}

Execute the program with cargo run and watch DuckDB in action!

duckdb-neo: the v2 C API wrapper (experimental)

⚠ DuckDB's v2 C API is in rapid development. Consider duckdb-neo unstable. Feedback is welcome!

duckdb-neo is a second wrapper crate in this repository that targets DuckDB's new v2 C API (duckdb_v2.h) instead of the v1 API used by duckdb. Both crates share the same libduckdb-sys crate and therefore the same bundled DuckDB, build options, and version number.

cargo add duckdb-neo

use duckdb_neo::{
    Parameters,
    environment::{Environment, StorageLocation},
};

fn main() -> duckdb_neo::Result<()> {
    let environment = Environment::new()?;
    let database = environment.open(StorageLocation::InMemory)?;
    let connection = database.connect()?;

    let mut result = connection.query("SELECT $1::INTEGER", Parameters::positional(&[&42]))?;
    let chunk = result.next().transpose()?.expect("query returned no rows");
    let values = chunk.get_vector_at::<i32>(0)?;
    assert_eq!(values.get(0)?, Some(&42));
    Ok(())
}

libduckdb-sys exposes the v1 bindings as libduckdb_sys::v1 (also re-exported at the crate root) behind the default capi-v1 feature and, behind its capi-v2 feature, the v2 bindings as libduckdb_sys::v2. duckdb-neo disables the default features so only the v2 bindings are generated. duckdb-neo enables that feature itself. Its own capi-v2-p2 feature targets API surface that the bundled DuckDB does not provide yet and does not compile.

Examples

The following examples demonstrate various features and use cases of duckdb-rs:

basic - Basic usage including creating tables, inserting data, and querying with and without Arrow.
appender - Bulk data insertion using the appender API with transactions.
arrow_vtab - Querying an in-memory Arrow RecordBatch from DuckDB SQL (requires the vtab-arrow feature).
parquet - Reading Parquet files directly using DuckDB's Parquet extension.
vscalar - Defining and registering a custom scalar function (requires the vscalar feature).
vtab - Defining a custom table function returning primitive, LIST, and STRUCT columns (requires the vtab feature).
repl - Interactive SQL REPL.
hello-ext - A DuckDB extension written in Rust (see Building and loading extensions).

Run an executable example using your configured DuckDB library:

cargo run --example basic

Pass each example's required feature when applicable:

cargo run --example arrow_vtab --features vtab-arrow
cargo run --example vscalar --features vscalar
cargo run --example vtab --features vtab
cargo run --example parquet --features parquet

Without bundled, the build links against the pinned prebuilt DuckDB it downloads (or a system library, see Notes on building). To compile DuckDB from source instead, add bundled to the feature list. For example:

cargo run --example basic --features bundled
cargo run --example arrow_vtab --features "bundled vtab-arrow"

hello-ext is a library target rather than an executable, so build it instead of using cargo run:

cargo build --example hello-ext --features loadable-extension

Feature flags

The duckdb crate provides a number of Cargo features that can be enabled to add functionality:

Virtual tables and functions

vtab - Base support for creating custom table functions and virtual tables.
vtab-arrow - Apache Arrow integration for virtual tables. Enables conversion between Arrow RecordBatch and DuckDB data chunks.
vtab-excel - Deprecated no-op retained for feature compatibility.
vscalar - Create custom scalar functions that operate on individual values or rows.
vscalar-arrow - Arrow-optimized scalar functions for vectorized operations. Requires vscalar.

File formats

json - Enables reading and writing JSON files. Implies bundled.
parquet - Enables reading and writing Parquet files. Implies bundled.

Bundled DuckDB extensions

These extensions are only available through the CMake build backend and imply bundled-cmake.

autocomplete - DuckDB's autocomplete extension.
httpfs - Statically links DuckDB's HTTP(S) and S3 filesystem extension (Linux and macOS only).
icu - DuckDB's ICU extension for locale-aware operations.
tpch - DuckDB's TPC-H benchmark extension.
tpcds - DuckDB's TPC-DS benchmark extension.

Data integration

appender-arrow - Efficient bulk insertion of Arrow data into DuckDB tables.
polars - Integration with Polars DataFrames.
rust_decimal - Compatibility impls for rust_decimal::Decimal. DuckDB DECIMAL values use duckdb::types::Decimal as the core full-domain carrier; this feature restores ToSql/FromSql conversions for rust_decimal::Decimal when values fit that crate's decimal domain, including compatibility reads from FLOAT, DOUBLE, and text columns.

Convenience features

vtab-full - Enables virtual table features: vtab-arrow and appender-arrow; retains the deprecated vtab-excel compatibility flag.
extensions-full - Enables all major extensions: json, parquet, and vtab-full.
modern-full - Enables modern Rust ecosystem integrations: chrono, serde_json, url, r2d2, uuid, polars, and rust_decimal.

Build configuration

bundled - Uses a bundled version of DuckDB's source code and compiles it during build. This is the simplest way to get started and avoids needing DuckDB system libraries.
bundled-cmake - Experimental. Builds DuckDB via its upstream CMake build system instead of cc. Requires a duckdb-rs checkout (not available from crates.io). See step 2 below for details.
buildtime_bindgen - Use bindgen at build time to generate fresh bindings instead of using pre-generated ones.
capi-v1 (libduckdb-sys only, default) - Generate bindings for the v1 C API header duckdb.h, exposed as libduckdb_sys::v1 and at the crate root. Required by duckdb and by loadable-extension.
capi-v2 (libduckdb-sys only) - Also generate bindings for the v2 C API header duckdb_v2.h, exposed as libduckdb_sys::v2. duckdb-neo enables this automatically. With buildtime_bindgen, duckdb_v2.h must sit next to duckdb.h in DUCKDB_INCLUDE_DIR.
loadable-extension - Experimental support for creating loadable DuckDB extensions. Includes procedural macros for extension development. Only enable this when building an extension, never for a client application - see Database client or extension?

Installation

Versioning

Starting with DuckDB v1.5.0, the duckdb-rs version encodes the DuckDB version in its second semver component. The format is 1.MAJOR_MINOR_PATCH.x, e.g., DuckDB v1.5.0 maps to duckdb-rs 1.10500.x. Use a tilde requirement to receive duckdb-rs patch releases without automatically moving to a different bundled DuckDB version.

Using stable releases from crates.io

The recommended way to use duckdb-rs is to add it from crates.io:

cargo add duckdb -F bundled

Or manually add it to your Cargo.toml:

[dependencies]
duckdb = { version = "~1.20000.0", features = ["bundled"] }

Using the development version from git

To use the latest development version from the main branch, you can specify a git dependency in your Cargo.toml:

# Use a specific branch
duckdb = { git = "https://github.com/duckdb/duckdb-rs", branch = "main", features = ["bundled"] }

# Use a specific commit
duckdb = { git = "https://github.com/duckdb/duckdb-rs", rev = "abc123def", features = ["bundled"] }

Note: Using the main branch of duckdb-rs means you'll get the latest Rust bindings and features, but you'll still be using whatever version of DuckDB core is bundled with that commit (when using the bundled feature). Use the v1.4-andium branch for LTS releases that stay on DuckDB 1.4 Andium.

Notes on building duckdb and libduckdb-sys

libduckdb-sys is a separate crate from duckdb-rs that provides the Rust declarations for DuckDB's C API. By default, libduckdb-sys attempts to find a DuckDB library that already exists on your system using pkg-config, or a Vcpkg installation for MSVC ABI builds.

You can adjust this behavior in a number of ways:

If you use the bundled feature, libduckdb-sys will use the cc crate to compile DuckDB from source and link against that. This source is embedded in the libduckdb-sys crate and tracks the DuckDB version vendored for that duckdb-rs release. This is probably the simplest solution to any build problems. You can enable this by adding the following in your Cargo.toml file:
```
cargo add duckdb --features bundled
```
Cargo.toml will be updated.
```
[dependencies]
duckdb = { version = "~1.20000.0", features = ["bundled"] }
```
If you use the bundled-cmake feature, libduckdb-sys will build DuckDB from the local checkout in crates/libduckdb-sys/duckdb-sources using upstream CMake. This keeps plain bundled unchanged while allowing CMake-only extensions such as httpfs and icu.

Example:
```
[dependencies]
duckdb = { git = "https://github.com/duckdb/duckdb-rs", branch = "main", features = ["bundled-cmake", "icu"] }
```
Notes:
- bundled-cmake is experimental and requires a git/workspace checkout. Published crates omit the full duckdb-sources tree.
- It implies bundled for conditional-compilation gates, but uses CMake instead of the cc backend. Any CMake-only extension feature (e.g. icu) enables it automatically.
- It always links DuckDB's default static extensions (core_functions and parquet) and therefore implies the parquet Cargo feature.
- Plain bundled uses DuckDB's standard allocator and skips jemalloc. bundled-cmake enables upstream jemalloc on supported 64-bit, non-musl Linux targets. Other targets follow DuckDB's CMake checks. Set DUCKDB_DISABLE_JEMALLOC=1 to force the standard allocator.
- Extension autoload/autoinstall are enabled to match bundled, despite upstream CMake defaults. Set DUCKDB_DISABLE_EXTENSION_LOAD=1 or DISABLE_EXTENSION_LOAD=1 to disable external extension install/load support and force autoload/autoinstall off. Statically linked extensions remain available.
- If ninja is on PATH, the build uses Ninja by default. Set CMAKE_GENERATOR to override.
- DuckDB builds in Release mode by default, even for Rust debug builds, avoiding DuckDB's much slower debug/sanitizer profile. Override with DUCKDB_CMAKE_BUILD_TYPE or CMAKE_BUILD_TYPE. DUCKDB_CMAKE_BUILD_TYPE takes precedence.
- httpfs requires CMake, a C++ compiler, pkg-config, and the libcurl and OpenSSL development libraries. On Debian/Ubuntu, install cmake pkg-config libcurl4-openssl-dev libssl-dev; on macOS, install cmake pkg-config openssl@3 with Homebrew (the macOS SDK provides libcurl). OpenSSL must be discoverable through pkg-config; for a custom installation, set PKG_CONFIG_PATH to its lib/pkgconfig directory. Network access is required at CMake configure time to fetch the HTTPFS extension sources. Windows is currently unsupported for httpfs. Once built, LOAD httpfs needs no downloaded extension artifact, including when external extension loading is disabled.
- DUCKDB_EXTENSION_CONFIGS is unsupported. Setting it fails fast.
- Use cargo build -vv -F bundled-cmake for CMake configure/build logs.
- On Windows (MSVC), keep the Cargo target directory short (e.g. CARGO_TARGET_DIR=D:/t). DuckDB's unity build includes sources by a path relative to the build directory, and deep paths exceed MSVC's 260-character limit with C1083. Alternatively set DUCKDB_DISABLE_UNITY=1.
When linking against a DuckDB library already on the system (so not using any of the bundled features), you can set the DUCKDB_LIB_DIR environment variable to point to a directory containing the library. You can also set the DUCKDB_INCLUDE_DIR variable to point to the directory containing duckdb.h (and duckdb_v2.h when using capi-v2 with buildtime_bindgen).

The examples below fetch the same prebuilt build the crate pins in crates/libduckdb-sys/.duckdb-release (see step 4). Once DuckDB publishes the v2.0.0 release, its duckdb-shared-libs-<platform>.tar.gz assets on GitHub Releases work the same way. Each archive is a flat tarball with the shared library and the public headers.

Linux ARM64 example:
```
source crates/libduckdb-sys/.duckdb-release   # sets DUCKDB_RELEASE_URL
mkdir libduckdb
curl -fL "$DUCKDB_RELEASE_URL/duckdb-shared-libs-linux-arm64.tar.gz" | tar -xz -C libduckdb

export DUCKDB_LIB_DIR=$PWD/libduckdb
export DUCKDB_INCLUDE_DIR=$DUCKDB_LIB_DIR
export LD_LIBRARY_PATH=$DUCKDB_LIB_DIR

cargo build --examples
```
For x86-64 Linux, replace arm64 with amd64 in the archive name.

macOS example:
```
source crates/libduckdb-sys/.duckdb-release   # sets DUCKDB_RELEASE_URL
mkdir libduckdb
curl -fL "$DUCKDB_RELEASE_URL/duckdb-shared-libs-osx-universal.tar.gz" | tar -xz -C libduckdb

export DUCKDB_LIB_DIR=$PWD/libduckdb
export DUCKDB_INCLUDE_DIR=$DUCKDB_LIB_DIR
export DYLD_FALLBACK_LIBRARY_PATH=$DUCKDB_LIB_DIR

cargo build --examples
```
On Windows the windows-amd64 and windows-arm64 archives contain duckdb.dll and its duckdb.lib import library; put both in DUCKDB_LIB_DIR and add that directory to PATH.
When none of the bundled features is enabled and DUCKDB_LIB_DIR is not set, the build script downloads pre-built DuckDB binaries and links against the dynamic library in the archive, effectively automating the manual steps above. Which build it downloads is pinned in crates/libduckdb-sys/.duckdb-release: a DUCKDB_RELEASE_URL directory holding the duckdb-shared-libs-<platform>.tar.gz archives, currently a staging build of a v2.0.0 preview commit, plus a DUCKDB_RELEASE_VERSION label and the DUCKDB_RELEASE_COMMIT those libraries were built from. ./upgrade.sh --sync vendors that same commit into the bundled sources, so bundled and the download always agree. Without a pin file the build falls back to the GitHub release matching the DuckDB version encoded in the crate version.

Set DUCKDB_DOWNLOAD_LIB=0 to opt out and probe the system (vcpkg, pkg-config) instead, or DUCKDB_DOWNLOAD_LIB=1 to force the download. Leave DUCKDB_STATIC unset: setting it requests a static duckdb_static library, which the downloaded archives do not contain. The archives are cached in target/duckdb-download/<target>/<version> and that directory is automatically added to the linker search path.
```
cargo test                          # downloads the pinned build on first use
DUCKDB_DOWNLOAD_LIB=0 cargo test    # use a system DuckDB instead
```
The download needs the download-lib feature, which pulls an HTTP client (ureq/rustls) into the build script. It is on by default; consumers building with bundled or a system DuckDB can drop it (and the HTTP client) with default-features = false, in which case the build probes the system unless DUCKDB_DOWNLOAD_LIB=1 is set explicitly.

The pinned staging archives do not ship duckdb_v2.h yet, so buildtime_bindgen together with capi-v2 needs DUCKDB_INCLUDE_DIR or a bundled build until the pin moves to a newer DuckDB build.
Installing the DuckDB development packages will usually be all that is required, but the build helpers for pkg-config and vcpkg have some additional configuration options. vcpkg-rs uses static libraries by default. To opt into dynamic linking, set the VCPKGRS_DYNAMIC=1 environment variable before building.

When none of the options above are used, the build script falls back to this discovery path and will emit the appropriate cargo:rustc-link-lib directives if DuckDB is found on your system.

Cross-compiling with bundled is best-effort (not covered by CI): it compiles DuckDB from C++ source and so needs a working C++ cross-compiler for the target, not just the Rust toolchain. If you can't get one working, prefer one of the non-bundled options above (e.g. DUCKDB_LIB_DIR or DUCKDB_DOWNLOAD_LIB=1) and link a pre-built library for the target instead.

ICU extension and the bundled features

When using the bundled feature, the ICU extension is not included due to crates.io's 10MB package size limit. This means some date/time operations (like now() - interval '1 day' or ts::date casts) will fail. You can load ICU at runtime:

conn.execute_batch("INSTALL icu; LOAD icu;")?;

Alternatively, link against a system libduckdb that was compiled with ICU (see build instructions above).

If you are working from a duckdb-rs checkout, you can also use bundled-cmake,icu to compile ICU in through DuckDB's CMake build.

Binding generation

We use bindgen to generate the Rust declarations from DuckDB's C header file. bindgen recommends running this as part of the build process for libraries that use it. We tried this briefly (duckdb 0.10.0, specifically), but it had some annoyances:

The build time for libduckdb-sys (and therefore duckdb) increased dramatically.
Running bindgen requires a relatively recent version of Clang, which many systems do not have installed by default.
Running bindgen also requires the DuckDB header file to be present.

So we try to avoid running bindgen at build time by shipping pregenerated bindings for DuckDB.

If you use the bundled feature, you will get pregenerated bindings for the bundled version of DuckDB. If you want to run bindgen at build time to produce your own bindings, use the buildtime_bindgen Cargo feature.

Three pregenerated files ship with libduckdb-sys: the v1 bindings, the v1 loadable-extension bindings, and (for capi-v2) the v2 bindings. The upgrade.sh script regenerates all of them.

Thread safety

A Connection is Send but not Sync: you may move it between threads, but you cannot share a single connection across threads at the same time. DuckDB does support concurrent access through multiple connections to the same database (see DuckDB's concurrency docs.

For multi-threaded applications, give each thread its own connection. The simplest way is a connection pool via the r2d2 feature:

use duckdb::{DuckdbConnectionManager, params};

let manager = DuckdbConnectionManager::file("file.db")?;
let pool = r2d2::Pool::new(manager)?;

// Each worker checks out its own connection from the pool.
let conn = pool.get()?;
conn.execute("INSERT INTO foo (bar) VALUES (?)", params![1])?;

Database client or extension?

duckdb-rs covers two distinct use cases, and you normally pick exactly one:

As a database client (most common): embed DuckDB in your Rust application to run queries, as shown in the Quickstart.
For writing DuckDB extensions: build a loadable .duckdb_extension that DuckDB loads at runtime. Enable the loadable-extension feature.

Do not enable loadable-extension for a regular client application. It replaces DuckDB's normal C API functions with extension wrappers that are only initialized when DuckDB loads your extension. Outside an extension context, calls such as Connection::open_in_memory() then panic with DuckDB API not initialized or DuckDB feature omitted.

Building and loading extensions

The hello-ext example shows the extension API in action: it registers a hello(name) table function via the loadable-extension feature and the duckdb_entrypoint_c_api macro.

cargo build alone does not produce a loadable extension though. DuckDB only loads files ending in .duckdb_extension that carry a metadata footer matching the target DuckDB version. A bare shared library fails with The file is not a DuckDB extension. The metadata at the end of the file is invalid. Appending that footer requires DuckDB's extension build tooling.

So rather than wiring this up by hand, start from the official extension-template-rs template for a complete, ready-to-build Rust extension. It handles the metadata step, platform/version detection, tests, and CI. Its make debug builds the shared library and then appends the footer, producing a .duckdb_extension you load with duckdb -unsigned.

Rust version compatibility

duckdb-rs is built and tested with stable Rust, and keeps a rolling MSRV (minimum supported Rust version) that may only be updated when the encoded DuckDB major/minor version changes, on a need basis (e.g. project dependencies bump their MSRV or a particular Rust feature is useful for us). The new MSRV will be at least 6 months old. DuckDB patch updates and crate patch releases (e.g. 1.10500.0 to 1.10500.1) are guaranteed to keep the same MSRV.

Contributing

We welcome contributions! Take a look at CONTRIBUTING.md for more information.

Join our Discord to chat with the community in the #rust channel.

License

Copyright (c) Stichting DuckDB Foundation

Licensed under the MIT license.

Name		Name	Last commit message	Last commit date
.cargo		.cargo
.github		.github
crates		crates
scripts		scripts
.gitignore		.gitignore
.gitmodules		.gitmodules
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
rust-toolchain.toml		rust-toolchain.toml
rustfmt.toml		rustfmt.toml
upgrade.sh		upgrade.sh

Navigation Menu

Repository navigation

About

Repository files navigation

duckdb-rs

Quickstart

duckdb-neo: the v2 C API wrapper (experimental)

Examples

Feature flags

Virtual tables and functions

File formats

Bundled DuckDB extensions

Data integration

Convenience features

Build configuration

Installation

Versioning

Using stable releases from crates.io

Using the development version from git

Notes on building duckdb and libduckdb-sys

ICU extension and the bundled features

Binding generation

Thread safety

Database client or extension?

Building and loading extensions

Rust version compatibility

Contributing

License

About

Releases

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

duckdb-rs

Quickstart

duckdb-neo: the v2 C API wrapper (experimental)

Examples

Feature flags

Virtual tables and functions

File formats

Bundled DuckDB extensions

Data integration

Convenience features

Build configuration

Installation

Versioning

Using stable releases from crates.io

Using the development version from git

Notes on building duckdb and libduckdb-sys

ICU extension and the bundled features

Binding generation

Thread safety

Database client or extension?

Building and loading extensions

Rust version compatibility

Contributing

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Used by

Contributors

Languages