working-with-dbt-mesh

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-engineering skill)
• Unit testing models (use the adding-dbt-unit-test skill)
• Semantic layer work (use the building-dbt-semantic-layer skill)

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:

Alternative	Mesh multi-project
{{ source('stripe', 'payments') }}	{{ ref('core_platform', 'stg_payments') }}
Data comes from raw database tables	Data comes from another dbt project's public models
Defined in sources.yml	Declared in dependencies.yml