dbt-osmosis

library1.3.0pypypiunverified

dbt-osmosis is a Python CLI and package designed to enhance dbt development workflows by automating schema YAML management, column-level documentation inheritance, and providing ad-hoc SQL compile/run helpers. It aims to reduce manual toil and enforce consistency in dbt projects. The library is actively maintained, with version 1.3.0 supporting Python 3.10-3.13 and dbt Core 1.8+. It maintains a regular release cadence, addressing compatibility with newer dbt Core versions.

data devops database

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

package ↗

INSTALL

IMPORT

SIG · DBT-OSMOSIS

dbt-osmosis

datapythonv1.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

dbt-osmosis is primarily a CLI tool. To get started, configure YAML routing in your `dbt_project.yml` and then run the `yaml refactor` command. The `--dry-run --check` flags are recommended for a safe preview before applying changes with `--auto-apply`.

dbt_project.yml: your_project_name: +dbt-osmosis: "_{model}.yml" # Run a dry run to see proposed changes dbt-osmosis yaml refactor --dry-run --check # Apply changes automatically dbt-osmosis yaml refactor --auto-apply

dbt-osmosis --version

Debug

Known issues

breakingdbt-osmosis is tightly coupled with dbt Core versions. Major dbt Core upgrades (e.g., from 1.7 to 1.8, or 1.9 to 1.10+) can introduce breaking changes due to internal dbt Core API shifts. Always check the dbt-osmosis changelog and ensure compatibility before upgrading dbt Core.

fix

Refer to the official dbt-osmosis migration guide and changelog. Ensure your `dbt-osmosis` and `dbt-core` versions are compatible. Upgrade `dbt-osmosis` to the latest version to ensure `dbt-core` compatibility.

affects: <1.3.0, dbt-core <1.8, dbt-core 1.9+, dbt-core 1.10+

gotchaThe `--check` flag with `--dry-run` in older versions (prior to 1.3.0) might return an exit code 0 even if schema changes are detected, potentially giving a false sense of security that no changes are pending.

fix

Upgrade to dbt-osmosis 1.3.0 or newer. For older versions, carefully review the console output of the `--dry-run --check` command for detected changes, rather than relying solely on the exit code.

affects: <1.3.0

breakingThe internal structure for `vars.dbt-osmosis` configuration for sources was migrated. Previously, it might have been at the top level, now it nests under a `sources:` key.

fix

Update your `dbt_project.yml` to reflect the new nested structure: `vars: dbt-osmosis: sources:`. Consult the configuration guide for the latest structure.

affects: <1.3.0

deprecateddbt Core's `tests` config has been renamed to `data_tests`. While dbt-osmosis may still process `tests` in older contexts, adhering to the new naming convention is recommended for forward compatibility.

fix

Update `tests` configurations to `data_tests` in your dbt project files.

affects: dbt-core >=1.8

Errors

Common errors & fixes

AttributeError: 'ColumnInfo' object has no attribute 'config'. Did you mean: 'Config'?

This error typically occurs when `dbt-osmosis` encounters changes in the `dbt-core` internal API, specifically related to the `ColumnInfo` object's attributes, often with dbt-core versions 1.10 or higher.

fix

Ensure `dbt-osmosis` is updated to a version compatible with your `dbt-core` version. This issue was specifically addressed in dbt-osmosis versions compatible with dbt-core 1.10+.

An error was encountered while trying to flush usage events

This error can occur when `dbt-osmosis` is installed with `uv` alongside `dbt-core-interface`, leading to conflicts during the serialization of `ColumnInfo` objects or dbt's internal event flushing mechanisms.

fix

This is often a compatibility issue between `dbt-osmosis` and `dbt-core`'s internal usage event handling when `dbt-core-interface` is present. Check for updated versions of `dbt-osmosis` or `dbt-core-interface` that resolve this conflict. Alternatively, try installing with `pip` instead of `uv` if the issue persists, as package resolution differences can sometimes mitigate this.

dbt-osmosis is not generating column descriptions correctly in source.yaml (outputs empty string descriptions)

This can happen if dbt-osmosis cannot correctly infer or inherit descriptions, or if the configuration for description generation is not set up as expected. This might be due to missing upstream documentation or specific configuration settings in `dbt_project.yml`.

fix

Verify that upstream sources or models have documented columns if inheritance is expected. Review your `dbt_project.yml` configuration for `dbt-osmosis` to ensure it's correctly set up for documentation generation and inheritance. Some configurations might require manual intervention or specific flags like `--synthesize` for LLM-assisted generation.

Upgrade

Version history

1.3.0latest on PyPI · released Mar 25, 2026

Audit

Dependencies

dbt-corerequiredCore dependency for dbt project interaction. Requires dbt Core 1.8+.

dbt-<adapter>requiredA dbt adapter package (e.g., `dbt-snowflake`, `dbt-postgres`) compatible with your dbt Core version is required.

streamlitoptionalRequired for the optional Streamlit workbench functionality.

openaioptionalRequired for LLM-assisted synthesis and natural-language generation features.

Agent activity

17 hits · last 30 days

node

Bingbot

OpenAI (training)

Resources

packagehttps://pypi.org/project/dbt-osmosis/ ↗