Configuration Reference

Complete reference for interlace.yaml, located at the project root. Every field has a default — a project works with no config file at all. All paths resolve relative to the project root.

Full Example

name: my-project
default_dialect: duckdb
default_engine: default

# The warehouse (the synthesised "default" engine)
database: 'ducklake:postgres:${WAREHOUSE_DSN}'
data_path: s3://my-bucket/warehouse/
metadata_schema: my_project_meta

secrets:
  lake:
    type: s3
    key_id: ${AWS_ACCESS_KEY_ID}
    secret: ${AWS_SECRET_ACCESS_KEY}
    region: eu-west-2

engines:
  pg:
    type: postgres
    database: 'postgresql://[email protected]:5432/analytics'

attach:
  crm: crm.duckdb
  erp: 'postgres:host=db.internal dbname=erp'

model_paths: [models]
macro_paths: [macros]
parallelism: 4
state_path: .interlace/state.db
stream_path: .interlace/streams.db

Top-Level Fields

Field	Type	Default	Description
`name`	`str`	`"interlace"`	Project name (also the default warehouse catalog alias)
`database`	`str`	`".interlace/warehouse.duckdb"`	Warehouse URI — see engine URIs
`default_dialect`	`str`	`"duckdb"`	SQL dialect models are written in
`engines`	`mapping`	`{}`	Named engines — see engine fields
`default_engine`	`str`	`"default"`	Engine unpinned models run on
`alias`	`str`	project name	Warehouse catalog’s ATTACH alias
`data_path`	`str`	—	DuckLake data location (local dir or `s3://...`)
`metadata_schema`	`str`	—	Catalog schema holding this warehouse’s DuckLake metadata
`secrets`	`mapping`	`{}`	Secrets created on the engine at open — see secrets
`attach`	`mapping`	`{}`	Databases to ATTACH: `alias: uri`
`quack_token`	`str`	—	Token for `quack:` databases (or `INTERLACE_QUACK_TOKEN`)
`model_paths`	`list[str]`	`["models"]`	Where models are discovered
`macro_paths`	`list[str]`	`["macros"]`	Where `CREATE MACRO` definitions are discovered
`parallelism`	`int` (min 1)	`4`	Models building concurrently (`--parallelism` overrides)
`state_path`	`str`	`".interlace/state.db"`	Control-plane SQLite database
`stream_path`	`str`	`".interlace/streams.db"`	Durable stream log (SQLite WAL)
`event_log_path`	`str`	—	Optional NDJSON mirror of the operator event log
`connections`	`mapping`	`{}`	Named `http` and `postgres` sources that are not warehouse engines
`inputs`	`mapping`	`{}`	DuckDB file scans (`parquet`, `csv`, `json`, `delta`, `iceberg`)
`cdc`	`mapping`	`{}`	Postgres logical slots copied into a `@stream`

Engine URIs

The database string determines the engine type:

Form	Meaning
`.interlace/warehouse.duckdb`	Plain DuckDB file (the default)
`ducklake:.interlace/warehouse.ducklake`	DuckLake, local catalog file
`ducklake:postgres:dbname=lake host=db.internal`	DuckLake, catalog hosted in Postgres
`warehouse.duckdb`	Plain DuckDB file (another path)
`:memory:`	In-memory DuckDB
`quack:localhost:4213`	Warehouse served by `interlace serve --quack`

Postgres as an execution engine is declared under engines: with type: postgres (never via the top-level database), and requires the adbc extra:

engines:
  pg:
    type: postgres
    database: 'postgresql://user@host:5432/dbname'

Every Postgres DSN — engine, DuckLake catalog, or attach: — must name a host explicitly (host=, a URI host, service=, or PGHOST/PGSERVICE).

Engine Fields

Each entry under engines: accepts:

Field	Type	Default	Description
`type`	`str`	`"duckdb"`	`duckdb`, `ducklake`, `quack`, or `postgres`
`database`	`str`	—	Path/URI (falls back to `.interlace/warehouse.duckdb`)
`dialect`	`str`	from `type`	SQL dialect (duckdb-family → `duckdb`, postgres → `postgres`)
`alias`	`str`	engine name	Catalog ATTACH alias
`data_path`	`str`	—	DuckLake data location
`metadata_schema`	`str`	—	DuckLake metadata schema
`secrets`	`mapping`	`{}`	Per-engine secrets
`attach`	`mapping`	`{}`	Per-engine ATTACHes
`quack_token`	`str`	—	Token when `database` is `quack:`

An engine named default overrides the synthesised warehouse engine entirely.

Secret Fields

Each entry under secrets: becomes a CREATE SECRET on the engine at open — how a DuckLake warehouse on object storage authenticates:

Field	Default	Description
`type`	`"s3"`	Secret type
`key_id`	`""`	Access key ID
`secret`	`""`	Secret access key
`endpoint`	—	`host[:port]`, no scheme (MinIO, R2, …); unset = AWS default
`region`	—	Region
`url_style`	—	`path` for MinIO-style endpoints
`use_ssl`	—	`true`/`false`
`scope`	—	Pin the secret to a prefix, e.g. `s3://bucket`

Connections, inputs, and CDC

connections: entries are http (base_url, headers) or postgres (dsn). A Python model calls connection(name) while it is building. Sensitive header values and DSN credentials are redacted on GET /connections.

inputs: entries are DuckDB scans a model can FROM by name. format is parquet, csv, json, delta, or iceberg. path accepts ${date}, ${datetime}, and ${workspace}. connection is an http connection (sent as an httpfs secret) or the name of an engine secrets: entry. A model on any other engine that reads an input is a config error.

cdc: entries copy a Postgres logical slot into a @stream. Each names connection (a postgres connection), slot, publication, tables, and stream. interlace serve reads pgoutput. The stored LSN advances only after those offsets have been flushed. The slot and publication are created outside Interlace.

event_log_path, when set, appends one JSON object per operator event after the SQLite commit.

Environment Variable Interpolation

${VAR} anywhere in the file is substituted before YAML parsing — from the process environment first, then from a .env file next to interlace.yaml:

database: 'ducklake:postgres:${WAREHOUSE_DSN}'

Only the braced ${VAR} form is recognised (no $VAR, no ${VAR:-default})
Unset variables stay as literal ${VAR}; if one survives into the warehouse config, startup fails with the variable named — never a silent empty string
The .env parser accepts comments, blank lines, an optional export prefix, and quoted values; it never modifies your process environment

Environment Variables Read by Interlace

Variable	Effect
`INTERLACE_ENV`	Default for `--env`
`INTERLACE_QUACK_TOKEN`	Token for `quack:` databases
`PGHOST` / `PGSERVICE`	Satisfy the Postgres host requirement

Configuration Reference#

Full Example#

Top-Level Fields#

Engine URIs#

Engine Fields#

Secret Fields#

Connections, inputs, and CDC#

Environment Variable Interpolation#

Environment Variables Read by Interlace#