Skip to main content
Every project has a committed streambuild_project.toml. Legacy YAML project files are rejected.
name and default_target are required. adapter defaults to clickhouse. Commands that connect to ClickHouse require host, port, username, and password after all configuration layers are merged. StreamBuild supplies no connection defaults. Use password = "" when the ClickHouse account intentionally has an empty password.

​
Managed source retention

Set an optional project-wide TTL for StreamBuild-managed Kafka landing tables:
The value is a ClickHouse TTL expression. _replay_landed_at is the recommended clock because it tracks when StreamBuild persisted the Kafka record, independently of the event timestamp. A managed source can override this default with its own ttl. When neither level defines a value, StreamBuild does not add a TTL clause and retains landing data indefinitely.

​
Direct mode and virtual environments

Direct mode is selected when virtual_environments is omitted or false:
Enable the staged lifecycle for the entire invocation with:
The setting is project- or local-level only. It is not accepted on individual targets, pipelines, or models.

​
Local overrides

Use ignored streambuild_local.toml for developer-specific values:
Local configuration can override the target, adapter, settings, connection, variables, and target values. It cannot replace the project name or authored resources.

​
Precedence

​
Target

  1. CLI --target
  2. local target
  3. project default_target

​
Variables, lowest to highest

  1. project [vars]
  2. selected project target vars
  3. selected local target vars
  4. local [vars]
  5. CLI --vars

​
Database

  1. CLI --database
  2. selected local target database
  3. selected project target database

​
Connection, lowest to highest

  1. project connection
  2. selected project target connection
  3. selected local target connection
  4. local connection
  5. STREAMBUILD_CLICKHOUSE_HOST, STREAMBUILD_CLICKHOUSE_PORT, STREAMBUILD_CLICKHOUSE_USERNAME, and STREAMBUILD_CLICKHOUSE_PASSWORD
  6. CLI connection flags
There is no public metadata-database override. Metadata lives in the selected target database.

​
Interpolation

Use project variables and environment variables in values:
Interpolation is recursive through arrays and mappings. A whole token preserves scalar or structured value types. Objects and arrays cannot be embedded inside surrounding text; consume structured variables through a Python macro instead. Connection secrets are expanded only when a command actually connects. stb discover and stb compile remain connection-free.