{"id":8931,"library":"dbt-osmosis","title":"dbt-osmosis","description":"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.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/z3z1ma/dbt-osmosis","tags":["dbt","cli","yaml","documentation","data-governance","automation","analytics-engineering"],"install":[{"cmd":"pip install \"dbt-osmosis\" \"dbt-<adapter>\"","lang":"bash","label":"Basic Installation"},{"cmd":"pip install \"dbt-osmosis[workbench]\" \"dbt-<adapter>\"","lang":"bash","label":"With Streamlit Workbench"},{"cmd":"pip install \"dbt-osmosis[openai]\" \"dbt-<adapter>\"","lang":"bash","label":"With OpenAI for LLM Features"}],"dependencies":[{"reason":"Core dependency for dbt project interaction. Requires dbt Core 1.8+.","package":"dbt-core","optional":false},{"reason":"A dbt adapter package (e.g., `dbt-snowflake`, `dbt-postgres`) compatible with your dbt Core version is required.","package":"dbt-<adapter>","optional":false},{"reason":"Required for the optional Streamlit workbench functionality.","package":"streamlit","optional":true},{"reason":"Required for LLM-assisted synthesis and natural-language generation features.","package":"openai","optional":true}],"imports":[],"quickstart":{"code":"dbt_project.yml:\n  your_project_name:\n    +dbt-osmosis: \"_{model}.yml\"\n\n# Run a dry run to see proposed changes\ndbt-osmosis yaml refactor --dry-run --check\n\n# Apply changes automatically\ndbt-osmosis yaml refactor --auto-apply","lang":"bash","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.3.0, dbt-core <1.8, dbt-core 1.9+, dbt-core 1.10+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.3.0"},{"fix":"Update your `dbt_project.yml` to reflect the new nested structure: `vars: dbt-osmosis: sources:`. Consult the configuration guide for the latest structure.","message":"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.","severity":"breaking","affected_versions":"<1.3.0"},{"fix":"Update `tests` configurations to `data_tests` in your dbt project files.","message":"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.","severity":"deprecated","affected_versions":"dbt-core >=1.8"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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+.","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.","error":"AttributeError: 'ColumnInfo' object has no attribute 'config'. Did you mean: 'Config'?"},{"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.","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.","error":"An error was encountered while trying to flush usage events"},{"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.","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`.","error":"dbt-osmosis is not generating column descriptions correctly in source.yaml (outputs empty string descriptions)"}]}