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 a safe, embedded-first Rust client for DuckDB with an optional Diesel 2.3 ORM backend. It bundles the DuckDB C library directly into your binary — no system package or separate install required — and exposes a fully safe public API with zero unsafe leaking into user code. Whether you are building a Tauri desktop app, an iOS cross-compiled binary, or a server-side analytics service, better-duck gives you the full power of DuckDB’s embedded OLAP engine from idiomatic Rust.
Why better-duck?
Most Rust DuckDB bindings depend on Arrow for columnar I/O or require a system-installed DuckDB library.better-duck takes a different approach, prioritising safety, portability, and simplicity for app-level code that just needs rows.
Bundled DuckDB
The DuckDB C library is compiled from vendored source via the
cc crate at build time. No system package, no runtime download, no pkg-config headaches — the library ships inside your binary.No Arrow Dependency
Columnar I/O is powerful for data-pipeline code, but most app-level OLAP queries just need rows.
better-duck skips Arrow entirely, keeping compile times short and the dependency tree lean.Diesel ORM Support
The
better-duck-diesel crate is a full Diesel 2.3 backend. Your existing table! macros, query DSL, migrations, and r2d2 connection pools work without changes.Embedded-First Design
Built to run inside Tauri desktop apps, iOS cross-builds, and other environments where you cannot rely on a system library. Tested in CI against Linux, macOS, Windows, and iOS targets.
Safe Public API
Every FFI call is wrapped inside the crate. Nothing
unsafe leaks into user code — all raw DuckDB C API calls are hidden behind safe Rust abstractions.Full Type Coverage
Native support for DuckDB’s complete type hierarchy: integers, floats, decimals, text, blobs, dates, timestamps, intervals, lists, arrays, structs, maps, unions, enums, UUIDs, and more.
Crate Structure
Thebetter-duck workspace is split into four focused crates. Two are intended for direct use; two are internal plumbing.
| Crate | Purpose |
|---|---|
better-duck-core | Low-level DuckDB wrapper — connections, prepared statements, bulk appender, full DuckValue type hierarchy, async facade, connection pool, and user-defined functions. This is the primary crate for direct SQL use. |
better-duck-diesel | Full Diesel 2.3 backend for DuckDB. Implements Connection, LoadConnection, TransactionManager, and MigrationConnection so existing Diesel DSL code works against any DuckDB database. |
better-duck-macros | Proc-macro crate powering the #[duckdb_scalar] and #[duckdb_table_function] attribute macros (re-exported from better-duck-core when the udf feature is enabled). Not used directly. |
better-duck-sys | Low-level FFI bindings crate. Vendors DuckDB’s C++ source as a unity-build archive and compiles it via the cc crate. Pre-generated bindings are checked in so consumers never need bindgen or LLVM. Not used directly. |
better-duck-sys → better-duck-macros → better-duck-core → better-duck-diesel.
Current Status
Beta:
better-duck is currently on 0.1.0-beta.4. The API is settling, but breaking changes before 1.0 are possible. Always check the CHANGELOG before upgrading. The minimum supported Rust version (MSRV) is 1.96.Supported Platforms
All platforms below are verified in CI on every push and pull request.| Platform | Status |
|---|---|
| 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 |
cc crate can drive a C++ compiler for that target — no pre-built native library distribution is required.