tycoon.yml reference¶
Every key in the project's config file, with defaults and worked examples.
Minimal example¶
name: my-project
version: 0.1.0
database:
raw: data/raw.duckdb
warehouse: data/warehouse.duckdb
sources: {}
Anything not declared falls back to the defaults below.
Top-level keys¶
| Key | Type | Default | Notes |
|---|---|---|---|
name |
string | my-project |
Used in dlt pipeline names |
version |
string | 0.1.0 |
Project's own version, free-form |
schema_version |
int | unset | Managed by tycoon — see schema_version below. Don't edit by hand. |
database |
block | see below | Where data lives |
sources |
map[name → source] | {} |
Registered ingestion sources |
dbt_project_dir |
string | dbt_project |
Path to dbt project root |
dbt_profiles_dir |
string | unset | Override the profiles.yml directory. See dbt profiles below. |
dbt_profile |
string | unset | Profile name within profiles.yml. Defaults to the profile: field in dbt_project.yml. |
dbt_target |
string | unset | Target within the profile (dev / prod / ...). Defaults to the profile's own target:, then dev. |
rill_dir |
string | rill |
Path to Rill project dir |
sync |
block | unset | tycoon data sync defaults |
stack |
block | see below | Tool-by-tool stack toggle |
schema_version¶
An integer marking which revision of the tycoon.yml format the file
was written against. Tycoon manages this field — tycoon init
stamps it on new projects, and tycoon init --upgrade advances it when
migrating an older file. You never need to set or edit it.
Not to be confused with version, which is yours: a free-form label
for your project that tycoon never touches.
version |
schema_version |
|
|---|---|---|
| Owned by | you | tycoon |
| Type | free-form string | integer |
| Meaning | your project's version | the tycoon.yml format revision |
Files without schema_version (or with an older one) still load — data
commands print a warning pointing at
tycoon init --upgrade,
which migrates the file in place while preserving comments and blank
lines. A schema_version newer than the installed tycoon supports is
an error: commands exit and ask you to upgrade tycoon-cli rather than
risk misreading a future format.
database¶
database:
raw: data/raw.duckdb # where dlt writes
warehouse: data/warehouse.duckdb # where dbt writes (or md:catalog)
| Key | Type | Default | Notes |
|---|---|---|---|
raw |
string | data/raw.duckdb |
Where dlt loads source data: a local DuckDB file, or md:<name> (or motherduck:<name>) for a MotherDuck database. The MotherDuck database must exist first, and MOTHERDUCK_TOKEN must be exported. |
warehouse |
string | data/warehouse.duckdb |
Local file or md:<catalog> for MotherDuck. |
For Snowflake / BigQuery / Redshift warehouses, the warehouse field
isn't load-bearing — dbt resolves the connection from
dbt_project/profiles.yml. Use stack.warehouse: snowflake (etc.) to
tell tycoon what kind of warehouse it's looking at.
sources¶
A map keyed by source name. Each source is a block declaring its type and config:
sources:
files:
type: filesystem
schema: raw_files
config:
bucket_url: data/input
file_glob: "*.csv"
github:
type: rest_api
schema: raw_github
config:
base_url: https://api.github.com
datasets: [repos, issues, pulls]
| Key | Type | Default | Notes |
|---|---|---|---|
type |
string | (required) | Source type: filesystem, rest_api, sql_database, or any catalog source |
schema |
string | raw_<name> |
Target schema name in the raw DB |
config |
dict | {} |
Type-specific config passed through to dlt |
tables |
list[string] | unset | Optional table-name list (for sql_database and similar) |
dbt_package |
string | unset | Optional dbt package to install when this source is registered |
A filesystem source's path (or bucket_url) can be a directory or a
single local file, given as a plain path or a file:// URL. For a directory, file_glob picks the files under it
(the flat shape defaults to **/*). For a single file, leave file_glob
unset: tycoon reads the file's directory and matches just that file name.
Setting both a file path and a file_glob is an error.
Source types not in tycoon data sources catalog need to be installed
via tycoon data sources add <type> first (it runs dlt init
under the hood and stages the source files under the resolved sources
dir, project-local once the project has its own .venv, otherwise the
shared ~/.tycoon/sources/).
sync¶
Configures defaults for tycoon data sync (cloud → local snapshots).
Optional.
sync:
to: data/local_snapshot.duckdb
mode: replace
sources:
- from: md:my_catalog
schemas: ['mart']
tables: ['dim_*', 'fct_*']
- from: md:another_catalog
schemas: ['*']
| Key | Type | Default | Notes |
|---|---|---|---|
to |
string | data/local_snapshot.duckdb |
Default destination DuckDB file |
mode |
string | replace |
replace / append / skip-existing |
sources |
list[block] | [] |
One block per remote source. Each carries its own filter globs. |
sync.sources[]¶
| Key | Type | Default | Notes |
|---|---|---|---|
from |
string | (required) | DuckDB-attachable URL: md:<catalog> for MotherDuck, /path/to/other.duckdb for a local file |
schemas |
list[string] | ["*"] |
fnmatch globs — which schemas to include |
tables |
list[string] | ["*"] |
fnmatch globs — which tables within selected schemas |
stack¶
Tells tycoon which tools you use. Drives tycoon doctor checks,
tycoon start services, and template scaffolding.
stack:
ingestion: dlt
ingestion_managed: true
warehouse: duckdb # or motherduck, snowflake, bigquery, redshift, other
transformation: dbt
transformation_managed: true # tycoon scaffolds + manages this
bi: rill # or metabase, looker, tableau, other, none
bi_managed: true
| Key | Type | Default | Notes |
|---|---|---|---|
ingestion |
enum | dlt |
dlt, airbyte, fivetran, meltano, none |
warehouse |
enum | duckdb |
duckdb, motherduck, snowflake, bigquery, redshift, other |
transformation |
enum | dbt |
dbt, none |
bi |
enum | rill |
rill, metabase, looker, tableau, other, none |
<tool>_managed |
bool | true |
If true, tycoon scaffolds + maintains this tool's project. If false, tycoon just records the path and stays out of the way. |
Setting any tool to none skips its scaffolding and tycoon doctor
checks. Setting _managed: false is for "I have my own dbt project
already, just point at it" workflows — used by tycoon register dbt
and friends.
Environment variable interpolation¶
Any string value can reference an environment variable with ${VAR}
syntax:
sources:
github:
type: rest_api
schema: raw_github
config:
base_url: https://api.github.com
access_token: ${GITHUB_TOKEN}
Tycoon expands these at config-load time. Unexpanded ${VAR} in any
field that gets passed to dlt produces a clear warning before the API
call ("Config key 'access_token' contains an unexpanded env var:
${GITHUB_TOKEN}").
dbt profiles¶
Tycoon resolves a dbt profile every time it shells out to dbt build /
dbt test / dbt docs / dbt run. Resolution order matches dbt's own
CLI so anything that works for dbt --profiles-dir foo works for
tycoon ... --profiles-dir foo:
- CLI flag —
--profiles-dir,--profile,--targetontycoon data transform run/test/build/docsandtycoon profiles list/show/doctor. tycoon.yml—dbt_profiles_dir,dbt_profile,dbt_target.<dbt_project_dir>/profiles.yml(dbt 1.5+ co-located file).$DBT_PROFILES_DIRenv var.~/.dbt/profiles.yml(dbt's default).
You generally don't need to touch any of the tycoon.yml fields —
co-located + ~/.dbt covers most setups. Set dbt_profiles_dir only
when your profile lives somewhere unusual (e.g. you keep it under
version control in a separate config/ directory).
Inspect what tycoon will use:
tycoon profiles list # every profile + targets + adapters; flags the active one
tycoon profiles show # pretty-print the active profile, secrets redacted
tycoon profiles doctor # verify resolution + adapter matches stack.warehouse
tycoon doctor includes the profiles doctor check too, so you'll
catch a duckdb-vs-snowflake adapter mismatch before a dbt build does.
transform¶
transform:
auto_scaffold: true # default
auto_osi_scaffold: false # default — opt in once you're happy with OSI scaffolds
| Key | Type | Default | Notes |
|---|---|---|---|
auto_scaffold |
bool | true |
After tycoon data sources run <name>, automatically run tycoon data analyze if no staging models exist for that source yet. |
auto_osi_scaffold |
bool | false |
After a successful tycoon data transform run/build, auto-emit dbt_project/semantic/osi.yaml via tycoon semantics scaffold. Best-effort — never breaks the underlying transform on failure. See the tycoon semantics docs. |
Things that aren't in tycoon.yml¶
- Secrets — keep them in
.envor your shell environment, then reference via${VAR}interpolation. Tycoon never asks you to put raw tokens intycoon.yml. - Per-machine paths — anything that varies between dev machines
belongs outside the file. The defaults assume
./data,./dbt_project,./rillrelative to the project root, which works on every machine. - Run history — that lives in
.tycoon/metadata.duckdb(auto-gitignored in scaffolded projects).