dbt-osmosis manages the schema YAML a dbt project forgets to keep tidy

Schema YAML is the thing that rots

dbt-osmosis is a Python CLI and package for dbt development workflows, and it is built around four primary surfaces. The first is schema YAML management through the yaml organize, yaml document and yaml refactor commands. The second is column level documentation inheritance across dbt lineage, so a description written on a source table can reach the models built on it. The third is ad-hoc SQL compile and run helpers, and the fourth is an optional Streamlit workbench for interactive dbt SQL development.

The problem behind the first surface is worth stating plainly. In most dbt projects the YAML files are written once, when the model is first created, and then drift. Columns are added to the model and not to the YAML, descriptions are written in one place and not in another, and the files end up describing a schema that no longer exists. Fixing that by hand across hundreds of models is the kind of chore that never gets scheduled.

The documentation inheritance feature addresses the other half. Rather than asking an analyst to paste the same column description into twelve model YAML files, the tool propagates it along the lineage, and that is the piece that turns YAML from a chore into something worth keeping current.

The audience is a dbt user with a large project, or with a team where the YAML has to be right because something else reads it, such as a documentation site or a catalogue.

A dozen command families under one entry point

The readme lists the top level commands that dbt-osmosis --help currently exposes, and it is a useful map of what the tool has grown into.

The core four are yaml for schema YAML management and documentation inheritance, sql to compile or run ad-hoc SQL in dbt context, workbench to launch the Streamlit workbench, and generate for sources, staging models, models and SQL.

Around them are the newer surfaces. nl covers natural-language query and model helpers, and test-llm validates LLM client configuration. test suggests dbt tests. diff reports schema drift between YAML and the database, and migration plans database migration SQL from those schema diffs, which is a pair that only makes sense together. validate does a dry-run of selected models without building them, analyze inspects documentation coverage, gaps and style, and lint lints SQL strings, models or a whole project.

Two observations. The generate and test commands overlap with what dbt itself can do, so the case for the tool is strongest where dbt has no answer, which is the YAML and documentation work. And the readme says explicitly that for command by command flags and examples you should use the docs-site CLI reference rather than this landing page, which is an honest admission that the readme is a summary and the Docusaurus site at z3z1ma.github.io/dbt-osmosis is the canonical reference for the CLI, the configuration model, the support matrix and the workflow guides.

Installing means installing your dbt adapter too

The install is short, and it deliberately pairs the tool with the adapter you already use. With uv:

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

and with pip:

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

You replace the adapter placeholder with your dbt adapter package, for example duckdb, snowflake, bigquery, postgres or redshift.

The readme is explicit about who owns adapter compatibility. It says to install a dbt adapter version that is compatible with the dbt Core runtime in your environment, and that adapter compatibility is owned by the adapter and dbt Core pairing, not by dbt-osmosis extras. In other words, dbt-osmosis is not a place to pin or upgrade your adapter, and an adapter mismatch is a problem to solve in the adapter's own release notes.

The package metadata backs this up. The dependencies list includes dbt-core>=1.8, dbt-common, dbt-core-interface, ruamel.yaml, PyYAML, sqlglot, click, pluggy, agate, rapidfuzz and rich. The presence of both ruamel.yaml and PyYAML is the round trip problem made visible, since YAML that a tool rewrites has to keep its formatting and comments as much as possible, and rapidfuzz is there for fuzzy name matching, which is what makes documentation inheritance work when a column has been renamed somewhere in the lineage.

Routing YAML files with keys in dbt_project.yml

The tool needs to know which YAML files belong to which models, and that mapping is declared in dbt_project.yml rather than in a separate config file:

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

The value is a template, so each model resolves to a predictable file name and the tool can find the file that describes it.

Behaviour can then be tuned per folder with the +dbt-osmosis-options key, and the repository level configuration file dbt-osmosis.yml can set a formatter:

formatter: "prettier --write"

That formatter setting is the answer to the classic YAML tooling complaint. A tool that rewrites YAML files will, by default, reformat them in a way your editor does not want, which produces diffs full of noise. Pointing the formatter at prettier, or whatever your project already uses, keeps the diff limited to the meaning change.

The same repository level file holds the rest of the configuration, and the docs site has a dedicated configuration guide under the tutorial-yaml section of the reference.

Dry run first, apply second

The quick start ends with two commands, and the order matters. First you preview:

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

and then, once the diff looks right, you apply the update:

dbt-osmosis yaml refactor --auto-apply

A refactoring tool that edits dozens of YAML files is only trustworthy if you can see what it will do first. The dry run and check flags exist for exactly that, and the naming of the apply flag, with auto in front of it, is a signal that the tool is willing to make sweeping changes without per-file confirmation once you have switched it on.

The practical routine is therefore to run the dry run, read the diff, commit or discard it, and only then apply. Teams that want this to happen automatically have a third option, the pre-commit hook, which runs the same refactor as part of the commit.

The diff command has a related role. It reports schema drift between YAML and the database, so the same tool answers both questions, what does the YAML say and what does the warehouse actually contain, and the migration command turns that drift into database migration SQL.

Audited dbt versions versus canary versions

The support policy is the most carefully worded part of the readme, and it is worth reading in full before you pin anything.

The package targets Python 3.10 to 3.13 and dbt Core 1.8 and later, and the metadata intentionally keeps dbt-core>=1.8 without an upper bound so installers can resolve newer dbt releases. But audited blocking support covers dbt Core 1.8.x through 1.11.x in CI, and future dbt Core minors are canary-only until they are explicitly audited.

The mechanism for that is described too. Scheduled and manual canary CI uses unpinned latest dbt-core and dbt-duckdb, so upstream breakage becomes visible in CI without redefining what is supported.

That is a careful way to handle the fact that a tool which parses dbt artefacts and talks to dbt internals breaks when dbt changes shape. The practical consequence for you is that a dependency resolution that picks dbt Core 1.12 will not be blocked at install time, but it is also not covered by the tested matrix, so behaviour changes in that combination are possible. If your project is on a newer dbt release, run the test suite against it before you let the tool rewrite your YAML.

The workbench and the pre-commit hook

The optional workbench is a Streamlit app for interactive dbt SQL development. It is installed with its extra and launched with the workbench command:

pip install "dbt-osmosis[workbench]" "dbt-<adapter>"
dbt-osmosis workbench

The extra pulls in streamlit, pandas, ydata-profiling, streamlit-ace, ipython, feedparser and streamlit-elements-fluence, so it is a heavyweight optional dependency set, which is why it is behind an extra rather than in the base install. A hosted demo is linked from the badge at the top of the readme, so you can see the interface before installing anything.

The pre-commit hook is the other piece worth understanding, because it changes how the tool is used rather than when it is run:

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>]

The readme says the hook keeps schema YAML changes visible in the commit that introduced them. The reason to prefer this over a nightly job is that the change is attributed to the person who caused it, and a reviewer sees the YAML diff next to the model diff. The rev is pinned to a version, and the adapter is installed as an additional dependency of the hook environment.

The SQL proxy extra is an experiment, not a feature

One of the extras deserves a separate warning, because the readme spends a paragraph on it. The proxy extra only installs dependencies for the experimental opt-in SQL proxy runtime. It does not expand the supported product surface, start a proxy server, configure authentication, TLS or listen and bind settings, or make the comment middleware durable.

The readme says the proxy module entrypoint is a local-only experiment with mysql-mimic defaults, not a hardened user-facing server, and that it should not be exposed to untrusted networks, because the proxy comment middleware is in-memory only.

That is a clear enough statement, and it is worth repeating that a middleware which is in-memory and a server with no authentication or TLS configuration are not the kind of component you put between a client and a database. If you are evaluating dbt-osmosis for a data platform with external consumers, the proxy runtime is not part of that decision.

The project itself is licensed under Apache-2.0, with the version recorded as 1.5.0 in the package metadata and the latest release tag v1.5.0 from 2026-07-05, following v1.4.0 in May and v1.3.0 in March. The classifiers call it Beta. The last push was on 2026-08-15 and the repository is not archived. The developer tooling is built around uv, task and Ruff, with task format, task lint and task test as the common commands, and the documentation site is built with the Node toolchain under docs/.

Editorial conclusion

Adopt dbt-osmosis if your dbt project has schema YAML that has drifted, columns that need descriptions inherited across the lineage, or a team that wants YAML changes to appear in the commit that introduced them through the pre-commit hook. Skip it if your project already keeps its YAML in good shape, since the tool earns its value by rewriting files, and treat the workbench and the SQL proxy extras as experiments rather than product surface. Before you run it, set the routing keys in dbt_project.yml, run dbt-osmosis yaml refactor --dry-run --check and read the diff, and confirm your dbt Core version falls inside the audited range, since minors beyond 1.11 are canary only.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. z3z1ma/dbt-osmosis on GitHub