Working With Dbt Mesh
Use when changing a dbt model in a way that could break its consumers, renaming...
Install
npx skills add dbt-labs/dbt-agent-skills --skill working-with-dbt-mesh -g -a claude-code -y- Repository
- dbt-labs/dbt-agent-skills750
- Category
- Engineering
- Updated
- 6d ago
- License
- Apache-2.0
- Context cost
- Mediumabout 3,000 tokens
- Runs scripts
- No, instructions only
What it does
Use when changing a dbt model in a way that could break its consumers, renaming, removing, or retyping a column, or changing a model that downstream models, exposures, dashboards, or BI tools depend on, to judge whether the change is breaking and who it affects. Also use when versioning a model (model versions, latest_version, latest_version_pointer, deprecation_date, migration windows), enforcing contracts, setting access or groups, or doing multi-project dbt Mesh work (cross-project refs via dependencies.yml, disambiguating similarly-named models, splitting a monolith). Covers single- and multi-project, and planning or advising as well as implementing.
Working with dbt Mesh
Core principle: In a mesh project, upstream data comes through ref(), not source(). Every cross-project reference requires the project name. When in doubt, read dependencies.yml first.
When to Use
- Making a potentially breaking change to a model, renaming, removing, or retyping a column, especially when other models, exposures, or BI tools depend on it. Assess the blast radius before changing it, and reach for model versions rather than editing in place.
- Versioning a model (
versions:,latest_version,latest_version_pointer,deprecation_date), this applies in a single project, not just multi-project setups - Working in a dbt project that references models from other dbt projects
- Resolving ambiguity when multiple upstream projects have similarly-named models (e.g. multiple
stg_models) - Adding model contracts, access modifiers, or groups
- Setting up cross-project references with
dependencies.yml - Splitting a monolithic dbt project into multiple mesh projects
Do NOT use for:
- General model building or debugging (use the
using-dbt-for-analytics-engineeringskill) - Unit testing models (use the
adding-dbt-unit-testskill) - Semantic layer work (use the
building-dbt-semantic-layerskill)
First: Orient Yourself in a Multi-Project Setup
Before writing or modifying any SQL in a project that uses dbt Mesh, follow these steps:
1. Read dependencies.yml
This file at the project root tells you which upstream projects exist:
# dependencies.yml
projects:
- name: core_platform
- name: marketing_platform
If this file has a projects: key, you are in a multi-project mesh setup. Every model you reference from those upstream projects must use cross-project ref().
2. Understand how upstream data gets into this project
In a mesh setup, upstream project models replace what would alternatively be sources:
