What you will be able to do
- Name the environment types a dbt project can have, and say how many of each are allowed
- Explain why the producer project needs a Production deployment environment with a successful job before its consumers' cross-project refs resolve
- Predict which upstream environment a consumer's cross-project ref resolves to from Development, Staging and Production
- Introduce a Staging environment in a producer project without breaking downstream developers
- Isolate production data with environments instead of duplicate dbt projects
Key concept
Production environment as the mesh source of truth — Each dbt project has exactly one deployment environment marked Production. The metadata that environment's successful jobs publish is what other projects' cross-project refs resolve against, unless a Staging environment takes over that role for non-production work.
1.Environment types inside one dbt project
A cross-project ref such as ref('jaffle_finance', 'monthly_revenue') always names a project, but what it resolves to depends on an environment. A ref in a downstream model is resolved against a database, a schema and a table that some upstream job actually built. Which upstream environment built them depends on the environment types both projects have set up. The labels you choose under Set deployment type therefore decide where a consumer's query reads data from, so they matter beyond housekeeping.
dbt has two kinds of environment. The Development environment holds the settings for the Studio IDE and the dbt platform CLI. Each project gets exactly one. Deployment environments hold the settings for job runs, and each one carries a deployment type: General, Staging or Production. A project can have any number of General environments but only one Staging and one Production environment.
| Environment type | Determines settings for | How many per project |
|---|---|---|
| Development | Studio IDE or dbt platform CLI | 1 |
| General (deployment) | dbt Job runs | Any number |
| Staging (deployment) | dbt Job runs | 1 |
| Production (deployment) | dbt Job runs | 1 |
The limit of one Production environment is what makes the mesh work. Because each project has a single Production environment, a consumer never has to say which upstream deployment it means. A General environment can run the same code against the same warehouse, but it is meant for deployment development. It is not recommended as the final source of truth, so the data you treat as truth belongs in Production.
Checkpoint 1 of 8· Check yourself
A producer team wants several deployment environments: one for nightly production builds, one for pre-production validation, and two for experiments. Which setup does dbt allow and recommend?
A project can have only one Production and one Staging environment, but any number of General environments. A General environment is not recommended as the source of truth.
“can have any number of General deployment environments, one Production deployment environment and one Staging deployment environment.”Source: docs.getdbt.com
Checkpoint 2 of 8· Exam question
A dbt Mesh consumer project has both a development environment and a deployment environment marked as Staging. The upstream producer project defines a Production deployment environment and a Staging deployment environment, both with at least one successful job run. When a model in the consumer's Staging environment issues a two-argument `ref()` call to a public model in the producer project, which producer environment does the reference resolve against?
Correct answer: A — The producer's Staging environment, since Mesh routes a Staging consumer to the producer's Staging metadata whenever that environment is defined and published.
- A. This is correct. When a producer project defines a Staging environment alongside Production, Mesh matches a consumer job running in Staging (or development) to the producer's Staging metadata instead of Production, guaranteeing data separation without duplicating the project.
- B. This is incorrect for this scenario. Falling back to Production regardless of consumer environment is only the behavior when the producer has not defined a Staging environment; here one exists and takes precedence for Staging and development consumers.
- C. This is incorrect. General deployment environments do not publish the manifest metadata that cross-project references resolve against; only Production and Staging environments serve that role in Mesh.
- D. This is incorrect. Mesh distinguishes consumer environment types explicitly and never substitutes a producer's own development environment, since development environments never run scheduled jobs or publish manifests.
2.What the producer's Production environment must publish
Cross-project refs never read the producer's code. On Enterprise and Enterprise+ plans, a metadata service resolves each reference against what the upstream project has already published. The consumer doesn't parse or run the upstream models. That is why the producer's environment setup comes first: the producer needs a deployment environment marked Production, and at least one deployment job there has to finish successfully. That job writes the manifest.json containing the metadata downstream projects need.
The order of these steps matters. The successful run has to come after the models are marked public, because a run from before the change publishes metadata in which those models aren't yet public. This explains a common confusion: the access: public change is merged, the consumer's ref still fails, and a single production run fixes it. If the producer also has a Staging environment, that environment needs its own successful deployment job too, because some consumers will resolve against Staging. The next section shows which ones. The access setting itself belongs to [model governance](lesson:7.3), and declaring the dependency belongs to [setting up additional projects](lesson:7.1).
Bidirectional dependencies let two projects each depend on the other's public models: project_a refs project_b, and project_b also refs project_a. They are allowed as long as no node-level cycle results, and dbt raises an error if it finds one. Because a dependency can only resolve against models that a deployment run has already published, they have to be built step by step. First, project_a runs in a deployment environment and produces public models. Second, project_b adds project_a as a dependency. Third, project_b runs in a deployment environment and produces public models. Only then can project_a add project_b as a dependency. Reverse the order and the second dependency points at metadata that does not exist yet.
Checkpoint 3 of 8· Check yourself
A producer project has a Production environment with a successful job and a Staging environment that has never run. What must still happen so that downstream cross-project references resolve correctly?
Consumers working in staging resolve against the producer's Staging environment, so that environment needs its own successful deployment run.
“If the upstream project has a Staging environment, run at least one successful deployment job there to ensure downstream cross-project references resolve correctly.”Source: docs.getdbt.com
Sources3
3.Which upstream environment a consumer's ref resolves to
The consumer's environment chooses the producer's environment. Without a Staging environment, a developer working in the Development environment gets cross-project refs that resolve to the producer's Production environment. That is convenient, but it means everyday development reads production data.
Adding Staging environments changes the mapping so that environments line up. When the consumer runs in staging, Mesh fetches public model information from the producer's Staging environment. When the consumer runs in production, it fetches from the producer's Production environment. IDE work in the consumer project also resolves to the producer's Staging environment. Only Production reads production data.
| Consumer is working in | Producer has no Staging environment | Producer has a Staging environment |
|---|---|---|
| Development (Studio IDE / platform CLI) | Producer's Production environment | Producer's Staging environment |
| Staging deployment | n/a | Producer's Staging environment |
| Production deployment | Producer's Production environment | Producer's Production environment |
The consumer never has to work out the upstream database or schema itself. A cross-project ref resolves to wherever the producer builds the model, so the consumer doesn't copy the producer's vars, environment variables or target.name logic. If the Finance team renames the schema that its production models land in, the Marketing team's refs still resolve. Resolution depends only on the developer using the dbt platform, through the Studio IDE or the platform CLI. Self-hosted dbt can't resolve these refs dynamically.
Checkpoint 4 of 8· Match them up
Project B depends on Project A, and both projects have Staging environments. Match where Project B is running to the environment its cross-project refs resolve to, and the reason.
Tap a term, then the definition that fits it.
With Staging in place, development and staging work resolve to the producer's Staging environment, and only production resolves to the producer's Production environment.
“When developers work in the IDE for Project B, cross-project refs will resolve to the staging environment of Project A, rather than production.”Source: docs.getdbt.com
Checkpoint 5 of 8· Exam question
A dbt Mesh producer project has only a Production deployment environment; no Staging environment has been configured. A developer working in their personal development environment in the consumer project issues a cross-project `ref()` to a public model owned by that producer. Which producer environment supplies the metadata for this reference?
Correct answer: A — The producer's Production environment, because references fall back to Production whenever the producer has not defined a Staging environment.
- A. This is correct. By default, cross-project references resolve against the upstream project's Production deployment environment, and that default applies to any consumer environment type when the producer has not defined a Staging environment.
- B. This is incorrect. A missing Staging environment on the producer does not block resolution; it simply means every consumer, including development, falls back to reading Production's published metadata.
- C. This is incorrect. Development environments never run scheduled jobs and therefore never publish the manifest metadata that Mesh consumes, so they cannot be a resolution target.
- D. This is incorrect. A General deployment environment does not automatically substitute for a missing Staging environment; Mesh's fallback target when Staging is absent is specifically Production.
4.Adding a Staging environment without breaking consumers
Marking an environment as Staging takes effect immediately and has no safety net. As soon as a Staging environment exists in a producer project, dbt uses it to resolve downstream cross-project refs. There is no fail-over to Production, even if the Staging environment has never had a successful run. If the producer creates an empty Staging environment at 10:00, every downstream developer whose refs now point at Staging starts getting errors at 10:00 too.
The safe approach is to fill the environment with metadata before giving it the Staging label. Create the environment as an ordinary deployment environment, define a job in it, and run that job to completion. Only after that should you change its deployment type to Staging. Consumers then switch over to metadata that already exists.
Checkpoint 6 of 8· Put it in order
Put the steps for introducing a Staging environment in a producer project in order, so that downstream developers see no downtime.
- 1.Create a new environment, but do NOT mark it as Staging.
- 2.Trigger the job to run, and ensure it completes successfully.
- 3.Define a job in that environment.
- 4.Update the environment to mark it as Staging.
Staging takes over resolution the moment it is marked, so a successful run has to exist before the label is applied.
“To avoid causing downtime for downstream developers, you should define and trigger a job before marking the environment as Staging”Source: docs.getdbt.com
Checkpoint 7 of 8· Exam question
For a single dbt Cloud project, which statement correctly describes the environment cardinality that dbt Mesh cross-project reference resolution relies on?
Correct answer: A — The project has exactly one development environment, at most one Production deployment environment, at most one Staging deployment environment, and any number of General deployment environments.
- A. This is correct. A project always has exactly one development environment, and among deployment environments it can designate at most one as Production and at most one as Staging, while any remaining deployment environments are simply General.
- B. This is incorrect. Production and Staging are distinct deployment environment types with separate metadata publication behavior; a single environment cannot hold both designations simultaneously.
- C. This is incorrect. A project is limited to exactly one development environment, not an unlimited number, and it can hold multiple deployment environments beyond a single Production one.
- D. This is incorrect. Production and Staging deployment types are standard environment settings available regardless of plan tier; they are not gated Enterprise+ add-ons, and General is not the only deployment type permitted.
5.Isolating data with environments, not duplicate projects
Teams used to isolate production data by creating separate dbt projects for one codebase, such as Jaffle Marketing - Dev and Jaffle Marketing - Prod. Cross-project refs rule this out. Both projects would run the same codebase and so share one project name in dbt_project.yml, which is the name a cross-project ref uses. Each project name must be unique in the account, and each codebase must correspond to exactly one dbt platform project. With two projects for the same codebase, a consumer's ref would have no single producer to resolve against.
Isolation is handled at the environment level instead. A Staging environment gives developers deployment tooling, ad hoc jobs, deferral and cross-project refs without exposing production data, while environment-level permissions keep Production locked down. Connections let each environment use a different data platform connection, so even a different warehouse account for Production doesn't require a second project.
Checkpoint 8 of 8· Check yourself
A platform team needs non-production work to use a different warehouse connection from production, and wants the Marketing project to stay referenceable from Finance. What should they do?
Project names must be unique for cross-project refs to work, and Connections let each environment use its own warehouse connection within the same project.
“Connections allows different data platform connections per environment, eliminating the need to duplicate projects.”Source: docs.getdbt.com
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.A newly created Staging environment falls back to Production for cross-project refs until it has had a successful run.Why is that wrong?
Once Staging exists, dbt resolves downstream refs against it with no fail-over to Production, so a Staging environment that has never run breaks downstream developers.
Covered in Adding a Staging environment without breaking consumers
2.Any deployment environment, including a General one, can serve as the producer's source of truth for consumers.Why is that wrong?
Only one environment can be marked for final production workflows, and General is not recommended for that purpose. The Production deployment type is what powers cross-project refs.
Covered in Environment types inside one dbt project
3.Separating Dev and Prod into two dbt projects for the same codebase is the right way to isolate production data in a mesh.Why is that wrong?
Project names must be unique for cross-project refs. Isolation belongs at the environment level, through Staging, environment permissions and per-environment connections.
Covered in Isolating data with environments, not duplicate projects
4.Once
access: publicis merged to main, consumers can reference the model immediately.Why is that wrong?Refs resolve against published metadata, so a successful job has to run after access is defined.
Covered in What the producer's Production environment must publish
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“can have any number of General deployment environments, one Production deployment environment and one Staging deployment environment.”
↩︎ Environment types inside one dbt project - 2.
“In dbt, each project can have one designated deployment environment, which serves as its production environment.”
↩︎ Environment types inside one dbt project“Only the production environment will reference the production data, keeping the data and access isolated without needing separate projects.”
↩︎ Which upstream environment a consumer's ref resolves to“Provide developers with the ability to create, edit, and trigger ad hoc jobs in the staging environment, while keeping the production environment locked down”
↩︎ Isolating data with environments, not duplicate projects“This production environment is essential for using features like Catalog and cross-project references.”
↩︎ Key concept“There can be only one environment marked for final production workflows and we don't recommend using a General environment for this purpose.”
↩︎ Exam trap 2“When developers work in the IDE for Project B, cross-project refs will resolve to the staging environment of Project A, rather than production.”
↩︎ Checkpoint - 3.
“Define a Production deployment environment in the upstream project and make sure at least one deployment job has run successfully there.”
↩︎ What the producer's Production environment must publish“This job should generate a manifest.json file — it includes the metadata needed for downstream projects.”
↩︎ What the producer's Production environment must publish“Each project must run and produce public models before the original producer project can take a dependency on the original consumer project.”
↩︎ What the producer's Production environment must publish“so long as the new dependency doesn't introduce any node-level cycles.”
↩︎ What the producer's Production environment must publish“When working in a Development environment, cross-project refs normally resolve to the Production environment of the project.”
↩︎ Which upstream environment a consumer's ref resolves to“Mesh automatically fetches public model information from the producer’s staging environment if the consumer is also in staging.”
↩︎ Which upstream environment a consumer's ref resolves to“You don't need to mirror any conditional configuration of the upstream project such as vars, environment variables, or target.name.”
↩︎ Which upstream environment a consumer's ref resolves to“dbt will consistently use metadata from the Staging environment to resolve references in downstream projects, even if there haven't been any successful runs”
↩︎ Adding a Staging environment without breaking consumers“The dbt_project.yml file is case-sensitive, which means the project name must exactly match the name in your dependencies.yml.”
↩︎ Isolating data with environments, not duplicate projects“dbt will consistently use metadata from the Staging environment to resolve references in downstream projects, even if there haven't been any successful runs”
↩︎ Exam trap 1“avoid creating projects for Jaffle Marketing - Dev and Jaffle Marketing - Prod; use environment-level isolation instead.”
↩︎ Exam trap 3“Configure models in upstream project with access: public and have at least one successful job run after defining access.”
↩︎ Exam trap 4“If the upstream project has a Staging environment, run at least one successful deployment job there to ensure downstream cross-project references resolve correctly.”
↩︎ Checkpoint“To avoid causing downtime for downstream developers, you should define and trigger a job before marking the environment as Staging”
↩︎ Checkpoint“Connections allows different data platform connections per environment, eliminating the need to duplicate projects.”
↩︎ Checkpoint - 4.https://docs.getdbt.com/guides/dbt-migration-3Official docs
“To dynamically resolve cross-project references, all developers need to develop with the dbt platform (either with the dbt platform CLI or Studio IDE).”
↩︎ Which upstream environment a consumer's ref resolves to“We strongly discourage defining multiple projects for the same codebase, even if you're trying to manage access permissions, connect to different data warehouses”
↩︎ Isolating data with environments, not duplicate projects - 5.https://docs.getdbt.com/docs/platform/about-deferOfficial docs
“The defer feature in the Studio IDE won't work if a Staging environment exists but no deploy job has run.”
↩︎ Adding a Staging environment without breaking consumers“Pull down the most recent manifest from the staging or production environment for comparison”
↩︎ Adding a Staging environment without breaking consumers
Also cited
“When defined, rerun a production job to apply the change”
↩︎ Prediction