building-models-and-dashboards

Files (1)

• SKILL.md

SKILL.md (first lines)

# Building models and dashboards

## Getting a dbt project

```bash
tycoon register dbt --create              # bootstrap a sibling repo ../<name>-dbt
tycoon register dbt --create ./dbt_project  # or bootstrap in-project
tycoon register dbt ../existing-dbt --profile my_profile --target dev  # BYO
```

- `--create` refuses if `dbt_project.yml` already exists at the target, and
  only supports DuckDB/MotherDuck warehouses (Snowflake/BigQuery: hand-author
  the project, then register it).
- Registering ATTACHes the observability DB as `tycoon_meta` in profiles.yml
  and generates `models/_tycoon/` unless `--no-attach-metadata`.
- If the dbt profile targets a different database than `tycoon.yml`, expect a
  warehouse-alignment prompt.

Profile resolution order for `data transform *`: `--profiles-dir` →
`tycoon.yml dbt_profiles_dir` → the dbt project dir → `$DBT_PROFILES_DIR` →
`~/.dbt`. Profile name: `--profile` → `tycoon.yml dbt_profile` →
`dbt_project.yml`. Target: `--target` → `tycoon.yml dbt_target` → profile
default → `dev`.

## Generating staging models

```bash
tycoon data analyze <source>            # scaffold stg_<source>__<table> models
tycoon data analyze <source> --build    # + dbt build --select staging
tycoon data analyze <source> --rill     # + Rill source/metrics/explore YAML
tycoon data analyze --all               # every source, but silently SKIPS --rill/--build
```

Models land in `models/staging/<source>/stg_<source>__<table>.sql`.

## Sentinel ownership: why regeneration refuses

Every generated file's first line is a sentinel (`-- @generated by tycoon
analyze` / YAML equivalent). Regeneration only overwrites files whose
sentinel is intact. Deleting the sentinel line claims the file as
hand-authored, and tycoon then skips it forever unless `--force`. This is the
mechanism, not a bug; edit generated models by removing the sentinel.

## Running dbt

```bash
tycoon data transform run   [-s SELECTOR] [-t TARGET] [--full-refresh]
tycoon data transform test  [-s SELECTOR]
tycoon data transform build [-s SELECTOR]
tycoon data transform docs  [-p PORT]     # generate + serve
```

These use the venv-co-located dbt binary and record run history in the
observability DB. Prefer them over raw `dbt` calls so history stays complete.

## Rill dashboards

`--rill` exports each raw table to Parquet under `data/parquet/<schema>/` and
generates Rill source/metrics-view/explore YAML. The Parquet bridge is
deliberate: Rill reading the DuckDB files directly would conflict with
tycoon's locks. Start the dashboard with `tycoon start` (Rill + Quack;
`--only rill` to skip Quack), stop with `tycoon stop`.

From Database-Tycoon/tycoon-cli, MIT.

More from Database-Tycoon/tycoon-cli