Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nimdeveloper/better-duck/llms.txt

Use this file to discover all available pages before exploring further.

better-duck is designed to be embedded-first: DuckDB is compiled from vendored C++ source at build time via the cc crate, so there is no requirement to install or locate a system DuckDB library on any supported platform. This makes better-duck suitable for Tauri desktop applications, iOS cross-builds, CI environments, and any context where you cannot rely on a pre-installed native library. The same codebase runs unchanged across Linux, macOS, Windows, and iOS without any platform-specific feature flags.

​
Supported Targets

The following targets are verified in CI on every commit and pull request:
PlatformStatus
Linux x86_64✓ CI-tested
macOS Apple Silicon (aarch64)✓ CI-tested
macOS x86_64✓ CI-tested
Windows x86_64✓ CI-tested
iOS aarch64✓ CI cross-build
iOS Simulator x86_64✓ CI cross-build
Linux, macOS, and Windows targets run the full test suite (unit tests, integration tests, and doctests). The iOS targets run a cross-compilation check (cargo build --target aarch64-apple-ios) to verify that the crate and DuckDB’s C++ source compile cleanly for those targets; test execution on iOS hardware is not part of CI.
WASM / browser (wasm32-unknown-unknown) is listed in the roadmap as exploratory. DuckDB itself has a WASM build, and investigating whether better-duck-core can compile to WASM is on the list — but it is not currently supported. Do not use better-duck-core in a WASM context without verifying it yourself.

​
Minimum Supported Rust Version (MSRV)

better-duck requires Rust 1.96 or later. This is enforced in the workspace Cargo.toml: 
[workspace.package]
rust-version = "1.96"
The CI MSRV job pins dtolnay/rust-toolchain@1.96 and runs the full test suite against that toolchain. Using an older Rust version will produce a build error from Cargo before any source is compiled.

​
Build Requirements

DuckDB’s C++ source is vendored inside the better-duck-sys crate as a compressed archive (vendor/duckdb.tar.gz). At build time, the cc crate extracts and compiles a unity-build of DuckDB’s amalgamated source. No additional tooling is required for ordinary consumers:
1

Install Rust 1.96+

Any standard Rust toolchain installed via rustup is sufficient. No additional C++ compiler flags need to be set manually — cc picks up the system C++ compiler automatically.
2

Add the dependency

[dependencies]
better-duck-core = "0.1.0-beta.4"
Cargo will download the crate, extract the vendored DuckDB source, and compile it as part of a normal cargo build.
3

(Optional) Regenerate FFI bindings

This step is only needed by maintainers who are upgrading the vendored DuckDB version. It requires LLVM and clang to be installed and the buildtime_bindgen feature to be enabled:
cargo build -p better-duck-sys --features buildtime_bindgen
The regenerated bindings are checked in to the repository so that all consumers can build without bindgen or LLVM.

​
Embedded Environments

better-duck was designed specifically for environments where a system DuckDB library is unavailable or impractical:

Tauri desktop apps

Embed a full DuckDB database engine inside a Tauri application. The vendored build produces a static library linked directly into the Tauri binary — no installer, no runtime dependency, no DLL hell.

iOS cross-builds

The crate cross-compiles to aarch64-apple-ios and x86_64-apple-ios (Simulator). Use a standard cross-compilation toolchain (e.g. cargo-xcode or a custom build.rs linker setup) alongside a macOS host machine with Xcode installed.

CI and serverless

Because there is nothing to install beyond Rust itself, better-duck works out of the box in any CI runner or serverless environment. The first build compiles DuckDB from source; subsequent builds use Cargo’s incremental compilation and sccache/Swatinem/rust-cache to avoid recompilation.

Air-gapped environments

Cargo’s --offline flag and a pre-populated registry cache are sufficient to build better-duck with no network access. The entire DuckDB source is part of the better-duck-sys crate tarball — no network download occurs at build time.

​
Cross-compilation setup

To cross-compile for iOS, install the target and ensure Xcode’s command-line tools are present: 
rustup target add aarch64-apple-ios
rustup target add x86_64-apple-ios

cargo build -p better-duck-core --target aarch64-apple-ios
cargo build -p better-duck-core --target x86_64-apple-ios
The cc crate will automatically select xcrun --sdk iphoneos clang++ (or the simulator SDK for x86_64-apple-ios) when cross-compiling on macOS. No additional CXXFLAGS or linker flags are required for a basic cross-build.

​
Extensions

DuckDB extensions add support for additional file formats and functions. Two extensions are available as Cargo features:
FeatureDefaultDescription
json—Compiles in DuckDB’s JSON extension translation units. Enables JSON reading/writing functions (read_json, json_extract, etc.) without needing LOAD 'json' at runtime. Forwarded from better-duck-sys/json.
parquet—Compiles in DuckDB’s Parquet extension translation units. Enables read_parquet, write_parquet, and related functions. Forwarded from better-duck-sys/parquet.
Enable them in your Cargo.toml: 
[dependencies]
better-duck-core = { version = "0.1.0-beta.4", features = ["json", "parquet"] }
Because these features compile the extension code into the final binary at build time, they increase the size of the compiled library. Only enable the features you actually use. Both features require the vendored DuckDB source (which is always present) — they do not require any external libraries or runtime downloads.

Build docs developers (and LLMs) love

Get started for freeTalk to us