Extensions

DuckDB’s functionality extends through extensions. better-duck-core lets you load them at runtime, bundle a few at build time, and build your own loadable extension.

Runtime extension management

These Connection methods drive INSTALL / LOAD and read duckdb_extensions(), so a feature can check for an extension and force it to load rather than failing later with an opaque SQL error.

conn.ensure_extension("spatial")?;                 // load, installing first if needed
let loaded: bool = conn.is_extension_loaded("spatial")?;

// lower-level:
conn.install_extension("spatial")?;                // INSTALL (downloads if absent)
conn.load_extension("spatial")?;                   // LOAD into this connection

Method	Behavior
`install_extension(name)`	`INSTALL name` (downloads if absent)
`load_extension(name)`	`LOAD name` into this connection
`is_extension_loaded(name) -> Result<bool>`	Queries `duckdb_extensions()`; an unknown extension reports `false` (no row), not an error
`ensure_extension(name)`	No-op if already loaded, else `LOAD`, else `INSTALL` + `LOAD`

Extension names must be bare identifiers ([A-Za-z0-9_]+); anything else is rejected up front, so the name can be embedded in SQL safely. Runtime loading needs network/filesystem access and enable_external_access (default on). The Diesel spatial module’s ensure_loaded wraps this for the ST_* DSL — see the Diesel docs.

Bundled extensions (build-time features)

The core features json, parquet, and icu compile that DuckDB extension into the static library (forwarded to better-duck-sys), so it is available with no runtime INSTALL / LOAD — ideal for offline/embedded builds (Tauri, iOS, air-gapped servers).

// With feature = "json", the JSON type and json_* functions work out of the box:
let row = conn
    .execute("SELECT json_extract('{\"a\":1}', '$.a')::INTEGER AS a")?
    .next()
    .expect("row")?;
assert_eq!(row.get("a"), Some(&better_duck_core::types::value::DuckValue::Int(1)));

icu adds timezone/collation support and requires a DuckDB archive re-vendored with ICU sources. See feature flags for how to enable each bundled extension.

Loadable extensions (experimental)

The loadable-extension feature builds for a loadable .duckdb_extension: it links no DuckDB and routes every FFI call through the host’s dynamically-loaded API table, so the crate builds a cdylib that a running DuckDB loads. It implies udf and pairs with the #[duckdb_entrypoint] macro, which generates the C-ABI entrypoint.

use better_duck_core::{connection::Connection, duckdb_entrypoint, duckdb_scalar};

#[duckdb_scalar(name = "hello")]
fn hello(name: &str) -> String { format!("hello, {name}!") }

#[duckdb_entrypoint(name = "my_ext", min_duckdb_version = "v1.5.5")]
fn init(conn: &mut Connection) -> better_duck_core::error::Result<()> {
    hello::register(conn)?;
    Ok(())
}

This is distinct from using extensions as above — it is how you author one. The generated entrypoint symbol is <name>_init_c_api, and extension_api::c_api_init (exposed under the same feature) initializes the host API table.

Connecting

Querying

Values & Types

Parameters & Statements

Writing Data

Columnar

Concurrency

Interop

Errors & Extensions

User-Defined Functions

Derives & Helpers

Runtime extension management

Bundled extensions (build-time features)

Loadable extensions (experimental)

See also

​Runtime extension management

​Bundled extensions (build-time features)

​Loadable extensions (experimental)

​See also

Runtime extension management

Bundled extensions (build-time features)

Loadable extensions (experimental)

See also