> ## Documentation Index
> Fetch the complete documentation index at: https://better-duck.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](/core/opening-connections) 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.

```rust theme={null}
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` |

<Note>
  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`](/core/configuration) (default on). The Diesel `spatial` module's
  `ensure_loaded` wraps this for the `ST_*` DSL — see the [Diesel docs](/diesel/overview).
</Note>

## 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).

```rust theme={null}
// 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)));
```

<Info>
  `icu` adds timezone/collation support and requires a DuckDB archive re-vendored with ICU sources.
  See [feature flags](/guide/feature-flags) for how to enable each bundled extension.
</Info>

## 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]`](/macros/entrypoint) macro, which generates the C-ABI entrypoint.

```rust theme={null}
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](/core/errors) — `Error::Engine` with `EngineErrorKind::MissingExtension` / `Autoload`.
* [`#[duckdb_entrypoint]`](/macros/entrypoint) — authoring loadable extensions.
* [Configuration](/core/configuration) — `enable_external_access`, `allow_unsigned_extensions`.
* [Feature flags](/guide/feature-flags) — `json`, `parquet`, `icu`, `loadable-extension`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.