dbt Mesh Project Structure

Multi-project dbt Mesh for large organizations. Domain-owned projects with cross-project dependencies and contracts.

#dbt #sql #data #mesh #enterprise #multi-project

PNG PDF

Project Directory

data-platform/

projects/

Domain-owned dbt projects

platform/

Core shared models

models/

staging/

stg_users.sql

core/

dim_users.sql

Public model

dbt_project.yml

finance/

Finance domain

models/

staging/

stg_transactions.sql

marts/

fct_revenue.sql

dbt_project.yml

marketing/

Marketing domain

models/

staging/

stg_campaigns.sql

marts/

fct_attribution.sql

dbt_project.yml

shared/

Cross-project resources

macros/

common_macros.sql

packages/

dbt_utils/

dbt-cloud.yml

dbt Cloud config

.gitignore

README.md

Why This Structure?

dbt Mesh enables data mesh architecture—domain teams own their dbt projects independently. Projects share models via cross-project refs and enforce contracts. Platform team provides core entities, domains build on top.

Key Directories

projects/platform/-Core shared models (dim_users, dim_products)
projects/{domain}/-Domain-owned projects with full autonomy
shared/macros/-Organization-wide reusable SQL/Jinja
dbt-cloud.yml-Multi-project orchestration config

Getting Started

Requires dbt Cloud or dbt-core 1.6+ for cross-project refs
Create separate dbt_project.yml per domain
Define public models with access: public in schema.yml
Use {{ ref('project_name', 'model_name') }} for cross-project refs

Model Contract

# models/core/_core__models.yml
models:
  - name: dim_users
    access: public  # Exposes to other projects
    contract:
      enforced: true
    columns:
      - name: user_id
        data_type: int
        constraints:
          - type: not_null
          - type: primary_key

Cross-Project References

Cross-project refs require the two-argument form: {{ ref('platform', 'dim_users') }}. The referenced model must have access: public. Use contracts to guarantee column types and prevent breaking changes.

When To Use This

Large organizations with multiple data teams
Need domain ownership and autonomy
100+ models across multiple business domains
Using dbt Cloud for orchestration

Trade-offs

Complexity-More moving parts than single-project setup
dbt Cloud dependency-Full mesh features require dbt Cloud (or complex self-hosting)
Coordination overhead-Contract changes need cross-team communication