dbt-osmosis

1.3.0 · active · verified Thu Apr 16

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.

Common errors

```
AttributeError: 'ColumnInfo' object has no attribute 'config'. Did you mean: 'Config'?
```
cause 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
```
cause 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)
```
cause 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.

Warnings

breaking dbt-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.
gotcha The `--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.
breaking The 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.
deprecated dbt 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.

Install

pip install "dbt-osmosis" "dbt-<adapter>" Basic Installation
pip install "dbt-osmosis[workbench]" "dbt-<adapter>" With Streamlit Workbench
pip install "dbt-osmosis[openai]" "dbt-<adapter>" With OpenAI for LLM Features

Quickstart

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

view raw JSON →