/working-with-dbt-mesh

name: working-with-dbt-mesh
description: 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.
user-invocable: false
metadata:
  author: dbt-labs

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` |

The upstream project has already staged and transformed the raw data. Your project builds on top of their public models, not their raw sources.

3. Disambiguate similarly-named models

When multiple upstream projects have models with the same name (e.g. `stg_customers` in both `core_platform` and `marketing_platform`), you **must** use the two-argument `ref()`:

-- Correct: explicit project name, no ambiguity
select * from {{ ref('core_platform', 'stg_customers') }}
select * from {{ ref('marketing_platform', 'stg_customers') }}

-- WRONG: dbt cannot determine which project's stg_customers you mean
select * from {{ ref('stg_customers') }}

4. Check existing patterns in the codebase

Before writing new SQL:

• Search for existing two-argument `ref()` calls to see which upstream projects and models are already in use
• Look at the upstream project's YAML for `access: public` models — only these are referenceable cross-project
• The first argument of `ref()` must exactly match the `name` field in the upstream project's `dbt_project.yml` (case-sensitive)

5. Know what you can and cannot reference

| Upstream model access | Can you `ref()` it cross-project? | |---|---| | `access: public` | Yes | | `access: protected` (default) | No — only within the same project | | `access: private` | No — only within the same group |

If you need a model that isn't `public`, coordinate with the upstream team to widen its access.

Cross-Project Refs Require dbt Cloud Enterprise

Cross-project `ref()` and the `projects:` key in `dependencies.yml` are only available on **dbt Cloud Enterprise or Enterprise+** plans. Before setting up any cross-project collaboration, verify plan eligibility:

1. **If `dependencies.yml` already has a `projects:` key and the project is actively using cross-project refs** — Enterprise is already in place. Proceed. 2. **Otherwise** — ask the user to confirm they are on dbt Cloud Enterprise or Enterprise+ before adding `projects:` to `dependencies.yml` or writing new two-argument `ref()` calls.

If the user cannot confirm the plan level, or confirms they are on a plan below Enterprise, **do not set up cross-project refs**. Explain that this feature requires upgrading to Enterprise or Enterprise+ and suggest they use the intra-project governance features (groups, access modifiers, contracts) instead.

Cross-Project `ref()` Syntax

-- Reference an upstream model (latest version)
select * from {{ ref('upstream_project', 'model_name') }}

-- Reference a specific version
select * from {{ ref('upstream_project', 'model_name', v=2) }}

For full cross-project setup details (dependencies.yml, prerequisites, orchestration), see [references/cross-project-collaboration.md](references/cross-project-collaboration.md).

Governance Features

dbt Mesh includes four governance features. These work independently and can be adopted incrementally:

| Feature | Purpose | Key Config | Reference | |---------|---------|------