Skip to main content
better-duck is a pre-1.0 project with a deliberate pinning and compatibility story. This page gathers everything you need to depend on it responsibly: the beta policy, the exact-version pinning rule, the minimum Rust version, the platforms CI covers, how the vendored DuckDB relates to your code, and what to expect when you upgrade.

​
Beta release policy

The current release is 0.1.0-beta.8.
Beta — the API is still settling. Breaking changes before 1.0 are possible between pre-release versions. Read the changelog before upgrading, and pin the exact version (below).
Under Cargo SemVer, a 0.x version treats the minor component as the breaking boundary, and pre-release identifiers (-beta.N) sit below the corresponding release. Treat each -beta.N bump as potentially breaking until the project reaches 1.0.

​
Pinning the exact version

Cargo’s default version requirement excludes pre-release versions: a requirement like "0.1" will not match 0.1.0-beta.8. You must pin the exact pre-release string.
Keep the sibling crates (better-duck-core, better-duck-diesel, better-duck-tauri) on the same version — better-duck-diesel and better-duck-tauri build on a specific better-duck-core. better-duck-macros is pulled in automatically by core’s udf / derive features and is never a direct dependency.

​
Minimum supported Rust version (MSRV)

The MSRV is Rust 1.96. Check yours with rustc --version; update with rustup update if needed. A toolchain older than 1.96 will not build the crates.

​
Supported platforms

The iOS targets are what make better-duck’s embedded-first design concrete: because DuckDB is compiled and statically linked rather than loaded from a system package, it cross-builds to mobile where a system library is not an option.

​
The vendored DuckDB version

DuckDB itself is compiled from vendored source and pinned in better-duck-sys — you do not install or match a system DuckDB. DuckDB ships an every-other-version LTS cadence from 1.4 (1.4 LTS, 1.5 current, …); better-duck pins a specific vendored engine, and a beta bump may move it.
Record library_version() in your app’s diagnostics / about screen. It is the authoritative answer to “which DuckDB am I running,” independent of any system install (there isn’t one).

​
Licensing

better-duck is licensed under either MIT or Apache-2.0, at your option.

​
Capabilities and known limitations

The library is usable today for most workloads. Because it is pre-1.0, a few edges are still in progress — knowing them up front avoids surprises.
  • Full scalar and composite type coverage (LIST / ARRAY / STRUCT / MAP / UNION / ENUM), plus UUID, BIT, and BIGNUM end-to-end — see Type system.
  • TIME_TZ with its UTC offset preserved on read and write.
  • User-defined functions: scalar, table (named params, projection pushdown, state), aggregate, and cast — plus experimental replacement scans.
  • Data derives (FromRow / ToRow / DuckEnum / DuckStruct).
  • Async facade (async) and connection pooling (pool / r2d2).
  • An extensive Diesel DSL of DuckDB functions, aggregates, and operators, plus a spatial module.
Capabilities move between these lists as the project approaches 1.0. Treat the changelog as the source of truth for a given version.

​
Upgrading checklist

1

Read the changelog

Review the CHANGELOG for breaking changes between your version and the target — expected on any -beta.N bump.
2

Bump all sibling crates together

Update better-duck-core, better-duck-diesel, and better-duck-tauri to the same new version string in Cargo.toml.
3

Rebuild from clean if the engine moved

If the vendored DuckDB version changed, the first rebuild recompiles the engine and is slow — this is expected. Watch for library_version() changing.
4

Re-check #[non_exhaustive] matches

DuckValue, Error, EngineErrorKind, and ResultType are #[non_exhaustive]. Your _ arms keep you compiling, but a new variant may be worth handling explicitly after an upgrade. See type system and error handling.
5

Mind the release profile

If you build release with panic = "abort", confirm your UDFs return Err rather than panicking — see panics and the abort profile.

Installation

Add the crates and understand bundled-DuckDB build times.

Architecture

The crate family and the embedded-DuckDB model.

Feature flags

What changes behind each Cargo feature.

Error handling

Handling #[non_exhaustive] errors across upgrades.