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!

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 any example with cargo run --example <name>.

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.

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.
• 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.
• 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.10504.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:

1. 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.10504.0", features = ["bundled"] }
   

2. 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 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.