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

# Project Configuration

> TOML targets, local overrides, variables, connections, and mode selection.

Every project has a committed `streambuild_project.toml`. Legacy YAML project files are rejected.

```toml theme={null}
name = "analytics"
default_target = "dev"
adapter = "clickhouse"

[settings]
virtual_environments = false

[connection]
host = "localhost"
port = 8123
username = "default"
password = "${ENV:CLICKHOUSE_PASSWORD}"

[vars]
environment_name = "dev"

[defaults]
managed_source_ttl = "_replay_landed_at + INTERVAL 14 DAY"

[targets.dev]
database = "analytics_dev"

[targets.dev.connection]
host = "dev-clickhouse"

[targets.dev.vars]
environment_name = "target-dev"
```

`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:

```toml theme={null}
[defaults]
managed_source_ttl = "_replay_landed_at + INTERVAL 14 DAY"
```

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:

```toml theme={null}
[settings]
virtual_environments = false
```

Enable the staged lifecycle for the entire invocation with:

```toml theme={null}
[settings]
virtual_environments = true
```

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:

```toml theme={null}
target = "personal"
adapter = "clickhouse"

[settings]
virtual_environments = true

[connection]
host = "localhost"
port = 18123

[targets.personal]
database = "analytics_klonge"
```

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`

```bash theme={null}
stb plan --vars '{"environment_name":"ci"}'
```

### 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:

```toml theme={null}
[vars]
database_suffix = "dev"
credentials = {username = "reader", role = "analytics"}

[targets.dev]
database = "analytics_${database_suffix}"

[connection]
password = "${ENV:CLICKHOUSE_PASSWORD}"
```

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.