Feature Flags

better-duck-core keeps its dependency tree lean by putting almost everything behind a Cargo feature. This page lists every feature the core crate defines, grouped by purpose, with what each turns on, which other features it implies, and when you’d reach for it.

Defaults and opting out

The default feature set is ["chrono", "decimal"]:

[dependencies]
better-duck-core = "0.1.0-beta.8"   # => default = ["chrono", "decimal"]

Opt out of the defaults and pick features à la carte with default-features = false:

[dependencies]
better-duck-core = { version = "0.1.0-beta.8", default-features = false, features = ["arrow", "udf"] }

Pin the exact pre-release version — Cargo’s default match excludes pre-releases. See Installation and Versioning.

Date, time & numeric types

These change which Rust type a temporal / numeric column reads as — see Type system.

Feature	Default	What it enables	When to use
`chrono`	✓	`chrono` conversions for `DATE`, `TIME`, `TIMESTAMP`, `TIMESTAMPTZ`, `INTERVAL`.	Keep on for `chrono` types. Disable (via `default-features = false`) for the native `DuckDate` / `DuckTime` / `SystemTime` structs.
`decimal`	✓	`rust_decimal::Decimal` for `DECIMAL` columns.	Keep on for exact decimal arithmetic. Without it, `DECIMAL` surfaces as the native `DuckDecimal`.
`time`	—	Bind/append `time`-crate values (`Date`, `Time`, `PrimitiveDateTime`, `OffsetDateTime`, `Duration`).	You already use the `time` crate and want to bind its values directly.
`uuid`	—	Convert between the native `DuckUuid` and `uuid::Uuid`.	You want `uuid::Uuid` interop instead of the native type.

chrono and the native date/time path are mutually exclusive for the read type — only one set of DuckValue temporal conversions compiles at a time. time is an independent bind/append path that coexists with either.

Bundled DuckDB extensions

These compile the extension straight into the embedded static library — there is no runtime INSTALL / LOAD. See Extensions for bundled-vs-runtime guidance.

Feature	Default	What it enables	When to use
`json`	—	Bundles DuckDB’s JSON extension.	JSON functions available offline, no runtime install.
`parquet`	—	Bundles DuckDB’s Parquet extension.	You read or write Parquet files.
`icu`	—	Bundles DuckDB’s ICU extension (timezones / collations). Requires a DuckDB archive re-vendored with ICU sources.	You need full timezone and collation support.

Each bundled extension recompiles a DuckDB variant, so these features make the build noticeably slower. See Installation.

Data interop

Feature	Default	What it enables	Implies	When to use
`arrow`	—	Export results via the Arrow C Data Interface. No new dependency — the crate defines the ABI structs directly.	—	Hand results to an Arrow pipeline with no Arrow dependency cost.
`polars`	—	Polars `DataFrame` interop, bridged through the Arrow C Data Interface. Pulls in `polars` + `polars-arrow`.	`arrow`	You want results as a Polars `DataFrame`, or to query a `DataFrame` back.
`columnar`	—	Columnar chunk read/write: `fetch_chunk`, zero-copy `as_slice`, build-and-bulk-insert.	—	Read large results fast, or access columns zero-copy.

Enabling udf turns the columnar APIs on too — they share the same vector / data-chunk machinery. Enable columnar explicitly only when you want those APIs without the proc-macro dependency udf pulls in. See columnar access.

Concurrency

Feature	Default	What it enables	When to use
`async`	—	A Tokio facade: `AsyncConnection`, `AsyncDatabase`, `AsyncPool`. Each call runs on `spawn_blocking`, so it never blocks the executor.	Async apps that must not block runtime threads on DB calls.
`pool`	—	An `r2d2` pool backed by a shared `Database` handle.	You want connection pooling. Combine with `async` for `AsyncPool`.

See async & pooling. async + pool together unlock AsyncPool.

Macros: UDFs & derives

Both come from better-duck-macros, reached through core — you never depend on the macros crate directly. See UDFs and data derives.

Feature	Default	What it enables	Implies	When to use
`udf`	—	`#[duckdb_scalar]` / `#[duckdb_table_function]` / `#[duckdb_aggregate]` / `#[duckdb_cast]`.	`columnar`	Register plain Rust functions as DuckDB functions.
`derive`	—	`#[derive(FromRow / ToRow / DuckEnum / DuckStruct)]` plus the `transaction!` and `params!` macros.	—	Map structs/enums to rows and types; ergonomic transaction / parameter macros.
`derive-diesel`	—	Makes the data derives additionally emit `better_duck_diesel` `FromSql` / `ToSql` impls.	`derive`	Turned on for you by `better-duck-diesel/derive`; rarely by hand. Core itself gains no Diesel dependency — the emitted code resolves `::better_duck_diesel` in your crate.

Advanced

Feature	Default	What it enables	Implies	When to use
`loadable-extension`	—	Experimental. Build for a loadable `.duckdb_extension`: links no DuckDB and routes every FFI call through the host’s API table. Pairs with `#[duckdb_entrypoint]`.	`udf`	Writing a DuckDB extension in Rust loaded into a host DuckDB.

loadable-extension changes the linking model — no DuckDB is linked in. Don’t enable it for a normal embedded application.

Feature implications at a glance

A few features turn others on automatically. Enabling the left turns on everything to its right:

You enable	Also enabled
`polars`	`arrow`
`udf`	`columnar`
`derive-diesel`	`derive`
`loadable-extension`	`udf` → `columnar`

Recommended presets

Lean embedded
Analytics / fast reads
Async service
UDFs + mapping

better-duck-core = "0.1.0-beta.8"  # defaults: chrono + decimal

The smallest useful footprint — row-oriented access with chrono/rust_decimal types.

better-duck-core = { version = "0.1.0-beta.8", features = ["parquet", "columnar"] }

Bundled Parquet plus zero-copy columnar reads for large results.

better-duck-core = { version = "0.1.0-beta.8", features = ["async", "pool"] }

AsyncConnection + AsyncPool for a Tokio application.

better-duck-core = { version = "0.1.0-beta.8", features = ["udf", "derive"] }

Choosing an API

A decision tree for which features and crates fit your task.

Architecture

How features flow down to the vendored DuckDB in -sys.

Type system

How chrono / decimal / uuid change the read type.

Core crate

The APIs these features unlock.

Getting Started

Concepts

Reference

Defaults and opting out

Date, time & numeric types

Bundled DuckDB extensions

Data interop

Concurrency

Macros: UDFs & derives

Advanced

Feature implications at a glance

Recommended presets

Choosing an API

Architecture

Type system

Core crate

​Defaults and opting out

​Date, time & numeric types

​Bundled DuckDB extensions

​Data interop

​Concurrency

​Macros: UDFs & derives

​Advanced

​Feature implications at a glance

​Recommended presets

​Related

Choosing an API

Architecture

Type system

Core crate

Defaults and opting out

Date, time & numeric types

Bundled DuckDB extensions

Data interop

Concurrency

Macros: UDFs & derives

Advanced

Feature implications at a glance

Recommended presets

Related