DuckDB

The duckdb data system answers questions over one DuckDB database file. sutura opens the file read-only, inside the process, through the DuckDB ADBC driver. The crate is sutura-exec-duckdb, and the source kind is duckdb. sutura renders each plan as DuckDB SQL.

When to use it

• Your data is in one DuckDB file.
• You want the raw SQL tool without a database server.

Settings

The entry reads the settings that every data system has and this key:

Key	Type	Default	Meaning
database_file	absolute path	required	The database file. sutura opens it read-only and never creates it

Related settings:

Setting	Default	Meaning
tools.run_sql.enabled	false	Turns on the raw SQL tool. With security.identity: multi-user, only over an acknowledged shared source: every caller can then read what the shared account can read
tools.run_sql.sources	[]	The aliases of the sources the raw SQL tool runs over. Required when the tool is on. More than one needs the sql feature
runtime.working_set_max_bytes	1073741824	The memory budget for one result
SUTURA_DUCKDB_ADBC_DRIVER	not set	An absolute path to libduckdb, for a build that links no driver

The musl release binaries link the DuckDB driver. Other builds load the library that SUTURA_DUCKDB_ADBC_DRIVER names.

The library reads a file an earlier DuckDB release wrote, back to the floor DuckDB's own storage documentation promises, and no further. It refuses a file written in a newer storage format than its own, so a producer that runs ahead of sutura has to write a format the library reads. A bare SELECT NULL has the engine's NULL type, which sutura does not map, so it is refused rather than answered; cast it, as in SELECT NULL::INTEGER.

Example

security:
  identity: "single-user"
  single_user_because: "one operator, one database file"
sources:
  local:
    kind: "duckdb"
    database_file: "/srv/sutura/warehouse.duckdb"
    posture: "shared-service-user"
tools:
  run_sql:
    enabled: true
    sources: ["local"]

Identity

This data system supports shared-service-user only: DuckDB runs inside the sutura process, so no per-caller identity reaches the source.

The process opens the file with its own operating-system identity. The source must use posture: shared-service-user. sutura opens the file with external access off and the DuckDB configuration locked, so a statement cannot read other files.