duckdb-rs

A Connection in duckdb-rs is Send but not Sync. This means you can move a connection between threads, but you cannot share a single connection across multiple threads simultaneously.

To handle multi-threaded applications, you should provide each thread with its own connection. The recommended way to do this is using a connection pool via the r2d2 feature.

Example using r2d2:

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])?;

When using the bundled feature, the ICU extension is omitted to comply with crates.io's 10MB package size limit. Without ICU, certain date/time operations (e.g., now() - interval '1 day') will fail.

You have three ways to resolve this:

1. Runtime Loading: Load the extension at runtime using SQL: conn.execute_batch("INSTALL icu; LOAD icu;")?
2. System Library: Link against a system-installed libduckdb that was compiled with ICU support.
3. Bundled-CMake: Use the bundled-cmake feature with the icu feature enabled (requires a git/workspace checkout).

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

The duckdb-rs crate serves two distinct purposes. You should choose exactly one based on your goal:

1. Database Client (Most Common): Use this to embed DuckDB in your Rust application to run queries. Do not enable the loadable-extension feature for this use case.
2. DuckDB Extension: Use this to build a loadable .duckdb_extension that DuckDB loads at runtime. Enable the loadable-extension feature for this.

Warning: If you enable loadable-extension in a regular client application, calls like Connection::open_in_memory() will panic because the DuckDB API is only initialized when the extension is loaded by DuckDB.

If you prefer not to use the bundled features, you can link against a DuckDB library already present on your system. You must provide the paths to the library and the header file using environment variables.

Linux ARM64 Example:

wget https://github.com/duckdb/duckdb/releases/download/v1.5.5/libduckdb-linux-arm64.zip
unzip libduckdb-linux-arm64.zip -d libduckdb

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

cargo build --examples

macOS Example:

wget https://github.com/duckdb/duckdb/releases/download/v1.5.5/libduckdb-osx-universal.zip
unzip libduckdb-osx-universal.zip -d 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

Setting the DUCKDB_DOWNLOAD_LIB=1 environment variable instructs the build script to download pre-built DuckDB binaries from GitHub Releases. This automates the manual process of downloading and setting paths. The downloaded version matches the DuckDB version encoded in the libduckdb-sys crate.

Note: Leave DUCKDB_STATIC unset, as the downloaded archives do not contain a static library.

Usage:

DUCKDB_DOWNLOAD_LIB=1 cargo test

The simplest way to install duckdb-rs and avoid build problems is to use the bundled feature. This tells libduckdb-sys to compile DuckDB from source using the cc crate and link against it. The source is embedded in the crate and tracks the DuckDB version vendored for that specific release.

To enable this, add the following to your Cargo.toml:

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

cargo add duckdb --features bundled

To build a valid DuckDB extension, you cannot simply run cargo build. DuckDB requires extensions to be files ending in .duckdb_extension that contain a specific metadata footer matching the target DuckDB version.

To handle the metadata and platform/version detection correctly, it is highly recommended to use the official extension-template-rs template.

Using the template, you can run make debug to build a shared library and automatically append the required footer, resulting in a valid .duckdb_extension file that can be loaded via duckdb -unsigned.

The Rows struct is a lazy handle for the resulting rows of a query. It implements FallibleStreamingIterator, meaning each call to next() can return an error.

Important: Rows is not compatible with Rust's standard Iterator trait because the lifetime of the returned Row is tied to the lifetime of the Rows handle. To avoid manual loop management, use Statement::query_map or Statement::query_and_then which return standard Iterator types.

To iterate manually, use a while let loop with rows.next()?.

use duckdb::{Connection, Result};

fn process_results(conn: &Connection) -> Result<()> {
    let mut stmt = conn.prepare("SELECT id, name FROM people")?;
    let mut rows = stmt.query([])?;

    while let Some(row) = rows.next()? {
        // Process row...
    }
    Ok(())
}

The Value enum is an owning container for DuckDB's dynamic types. It is used to represent scalar values when interacting with the database. Note that the specific variant of Value is typically determined by DuckDB's logical types rather than the caller.

For non-owning (borrowed) access to dynamic values, use ValueRef instead.