> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqlbuild.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DuckDB

> DuckDB adapter configuration for SQLBuild.

DuckDB is included as a core dependency. No extra installation needed.

## Connection config

```toml theme={null}
adapter = "duckdb"

[connection]
database = "my_project.duckdb"
```

| Field        | Description                                                               |
| ------------ | ------------------------------------------------------------------------- |
| `database`   | Path to the DuckDB database file. Use `:memory:` for in-memory databases. |
| `extensions` | List of DuckDB extensions to install and load on connect.                 |
| `settings`   | Key-value pairs passed as `SET` statements on connect.                    |
| `attach`     | List of additional databases to attach.                                   |

## Extensions and settings

```toml theme={null}
[connection]
database = "my_project.duckdb"
extensions = ["httpfs", "parquet"]

[connection.settings]
memory_limit = "4GB"
```

## Attaching additional databases

```toml theme={null}
[connection]
database = "my_project.duckdb"

[[connection.attach]]
path = "external_data.duckdb"
alias = "external"
read_only = true
```

## Table promotion mode

DuckDB defaults to `staged` promotion: tables are materialized into a staging table, audited, then swapped into the target. This is configurable in `settings`:

```toml theme={null}
[settings]
table_promotion_mode = "staged"
```