Extensions

Load DuckDB extensions at runtime (INSTALL / LOAD / check), bundle json / parquet / icu at build time, and build loadable extensions with the loadable-extension feature.

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.

See also

• Errors — Error::Engine with EngineErrorKind::MissingExtension / Autoload.
• #[duckdb_entrypoint] — authoring loadable extensions.
• Configuration — enable_external_access, allow_unsigned_extensions.
• Feature flags — json, parquet, icu, loadable-extension.