Prerequisite for project dependencies: 1 dbt project == 1 dbt Cloud project

[jtcohen6]

Contributions

• I have read the contribution docs, and understand what's expected of me.

Link to the page on docs.getdbt.com requiring updates

https://docs.getdbt.com/docs/collaborate/govern/project-dependencies
https://docs.getdbt.com/docs/deploy/deploy-environments#staging-environment
https://docs.getdbt.com/best-practices/how-we-mesh/mesh-4-faqs

What part(s) of the page would you like to see updated?

• Project dependencies (for cross-project references) require that 1 dbt project == 1 dbt Cloud project.
  • If the same project name is duplicated across multiple dbt Cloud projects, then cross-project references will resolve non-deterministically.
• To that end, if one dbt project should have both a Staging environment and a Production environment, then the Staging + Production environments need to be defined within the same dbt Cloud project.

Additional information

We don't live in this reality yet, but we're very close.

Copying context from dbt-labs/dbt-core#10092 (comment):

To that end, we are working hard to remove the historical limitations that required customers to "duplicate" projects in dbt Cloud — Staging environments for data isolation (beta), env-level permissions and env-level data warehouse connections (coming very soon).

[jtcohen6]

Also (in conversation with @will-sargent-dbtlabs):

• 1 source == 1 source
• Always use conditional logic within the same source definition (e.g. env_var) to add prefixes/suffixes conditionally, if different source data for Production versus Staging/Development environments
• (Corollary: Strongly discourage overriding ref/source macros to accomplish this, or elsehow putting this as conditional logic within models)

sources:
  - name: my_source
    schema: "my_source_schema_{{ env_var('ENV_SUFFIX') }}"