dbt-osmosis

dbt-osmosis is a Python CLI and package for dbt development workflows.

It centers on four primary surfaces:

• schema YAML management (yaml organize, yaml document, yaml refactor)
• column-level documentation inheritance across dbt lineage
• ad-hoc SQL compile/run helpers
• an optional Streamlit workbench for interactive dbt SQL development

The repository also ships additional command families for generation, natural-language helpers, schema diffing, SQL linting, and test suggestions.

The Docusaurus site is the canonical reference for the current CLI, configuration model, support matrix, and workflow guides:

• Docs site: https://z3z1ma.github.io/dbt-osmosis/
• CLI reference: https://z3z1ma.github.io/dbt-osmosis/docs/reference/cli
• Configuration guide: https://z3z1ma.github.io/dbt-osmosis/docs/tutorial-yaml/configuration
• Migration guide: https://z3z1ma.github.io/dbt-osmosis/docs/migrating

Supported runtime

dbt-osmosis currently targets:

• Python 3.10-3.13
• dbt Core 1.8+
• a dbt adapter version compatible with the dbt Core runtime in that environment

Repository-managed DuckDB fixture coverage is explicitly exercised through the published DuckDB-backed matrix in CI today (1.8-1.10) plus a latest-core compatibility job that runs basedpyright, dbt parse, and the full pytest suite under dbt-core 1.11 with the latest published dbt-duckdb adapter (currently 1.10.1). Package metadata and install paths are not capped at dbt Core 1.10.

Optional extras:

• dbt-osmosis[workbench] for the Streamlit workbench and related UI dependencies
• dbt-osmosis[openai] for LLM-assisted synthesis and natural-language generation features

Install

With uv:

uv tool install --with="dbt-<adapter>" dbt-osmosis

With pip:

pip install "dbt-osmosis" "dbt-<adapter>"

Replace <adapter> with your dbt adapter package, for example duckdb, snowflake, bigquery, postgres, or redshift.

Quick start

1. Configure YAML routing in dbt_project.yml:

models:
  your_project_name:
    +dbt-osmosis: "_{model}.yml"

2. Optionally set per-folder behavior with +dbt-osmosis-options and a repo-level YAML formatter in dbt-osmosis.yml:

formatter: "prettier --write"

3. Preview changes safely:

dbt-osmosis yaml refactor --dry-run --check

4. Apply the update once the diff looks right:

dbt-osmosis yaml refactor --auto-apply

CLI surface

Top-level commands currently exposed by dbt-osmosis --help:

• yaml — manage schema YAML files and documentation inheritance
• sql — compile or run ad-hoc SQL in dbt context
• workbench — launch the Streamlit workbench
• generate — generate sources, staging models, models, and SQL
• nl — natural-language query/model helpers
• test — suggest dbt tests
• test-llm — validate LLM client configuration
• diff — report schema drift between YAML and the database
• lint — lint SQL strings, models, or a whole project

For command-by-command flags and examples, use the docs-site CLI reference rather than relying on this landing page.

Developer tooling

Local development in this repository is built around uv, task, and Ruff.

Common workflows:

task format
task lint
task test

Notes:

• Ruff is the active formatter, linter, and import sorter.
• task is not just verification; the default task formats, lints, runs tests, and then ensures the dev environment is synced.
• Repository test fixtures are DuckDB-only today; contributor examples use demo_duckdb, and targeted core tests may need uv run dbt parse --project-dir demo_duckdb --profiles-dir demo_duckdb -t test to refresh demo_duckdb/target/manifest.json.
• Docs-site commands use the Node toolchain under docs/:

npm --prefix docs run start
npm --prefix docs run build
npm --prefix docs run serve

Workbench

The optional workbench is a Streamlit app for interactive dbt SQL development.

Install the extra and launch it with:

pip install "dbt-osmosis[workbench]"
dbt-osmosis workbench

The hosted demo is linked from the badge at the top of this README.

Pre-commit hook

You can run dbt-osmosis yaml refactor -C as a pre-commit hook:

repos:
  - repo: https://github.com/z3z1ma/dbt-osmosis
    rev: v1.3.0
    hooks:
      - id: dbt-osmosis
        files: ^models/
        args: [--target=prod]
        additional_dependencies: [dbt-<adapter>]

That hook keeps schema YAML changes visible in the commit that introduced them.