dbt makes it easy to put SQL transformations into version control. To make the project useful to a growing team, you also need a few shared conventions: where data comes from, how models are organised, what gets tested and who looks after each part. Start small and make those choices clear.

A practical foundation gives people a consistent place to start. It helps catch damaging changes early and makes it possible to trace a number in a report back to its source.

Be clear about your sources

Start by defining warehouse inputs as dbt sources rather than referring to raw tables directly throughout the project. dbt’s source documentation explains how sources name and describe loaded data, support tests and enable freshness checks.

For each source, capture:

  • the source system and ingestion owner;
  • table purpose and grain;
  • stable keys and important timestamps;
  • expected load schedule and freshness;
  • fields containing personal or sensitive data;
  • known limitations, deletion behaviour and late-arriving records.

This makes the hand-off between ingestion and transformation visible. A stale source is not a failed model, and the response may belong to a different team. The project should make that distinction clear.

Use layers that communicate intent

A three-part structure works for many teams:

  1. Staging models rename, cast and lightly standardise one source relation at a time.
  2. Intermediate models express reusable business transformations or joins.
  3. Marts present governed facts, dimensions and reporting entities to consumers.

The names matter less than the boundaries. Avoid embedding major business rules in staging, and avoid making dashboard-specific models the only place where a core measure is defined. Keep each model’s grain explicit in its description.

Do not create a layer merely to satisfy a diagram. An intermediate model is useful when it isolates complexity or is reused. A pass-through model with no contract or purpose adds navigation cost.

Test the assumptions that would hurt

Tests should protect decisions, not maximise a count on a dashboard. dbt supports generic data tests such as uniqueness, non-null, accepted values and relationships, as described in its data tests guide. Custom singular tests can express business invariants.

Prioritise:

  • uniqueness and non-null checks on declared keys;
  • relationship checks where an orphan changes business meaning;
  • accepted values for controlled classifications;
  • source freshness for time-sensitive data;
  • reconciliation of important counts and values;
  • assertions about model grain and mutually exclusive states.

Choose severity deliberately. A missing optional classification might warn while duplicate invoice keys should stop publication. Document tolerated exceptions rather than weakening a test until it always passes.

Tests do not replace source-to-target reconciliation. A model can have unique keys and still be missing half of yesterday’s input. Combine structural checks with freshness, volume and business totals.

Treat documentation as part of the model

Generated documentation is useful only when model and column descriptions explain meaning rather than repeat names. dbt’s documentation guidance covers descriptions and the generated lineage site.

Every published model should answer:

  • What business question does this support?
  • What is one row?
  • Which records are included or excluded?
  • Which timezone, currency and status rules apply?
  • Who owns the definition?
  • How fresh should it be?

Use docs and lineage during review. A seemingly local model change can alter several downstream metrics. Seeing that impact before merge is part of the control.

Build a reviewable delivery path

Keep the project in version control and require a pull request for production changes. A useful continuous-integration job should parse and compile the project, run modified models and their tests against an isolated target, and report failures before merge. dbt documents patterns for continuous integration, including building changed resources in a staging environment.

Isolation prevents one branch from overwriting another developer’s relations. Limit credentials to the schemas and actions required by the job. Never put warehouse secrets in the repository or public build logs.

A change review should consider more than SQL style:

  • Does the model preserve its declared grain?
  • Are breaking column or semantic changes explicit?
  • Are tests proportional to the risk?
  • Does the query have a plausible cost at production volume?
  • Are downstream owners affected?
  • Can the change be rolled back or rebuilt safely?

Separate environments and promotion

Development should use personal or branch-scoped schemas. CI should use an isolated, disposable target. Production credentials should be available only to the deployment process and a small operating group.

Promote the same reviewed code rather than copying SQL between environments. Pin package versions and review updates. Store environment-specific database, warehouse, role and schema settings outside the model logic.

For incremental models, document the unique key, update strategy, late-arrival window and full-refresh procedure. An incremental model that nobody can rebuild within an acceptable window is an operational dependency, not merely a performance optimisation.

Establish ownership and routine

Assign owners at a useful domain or model level. Ownership should include definition quality, expected freshness, consumer communication and incident response—not necessarily execution of every technical fix.

A lightweight weekly operating review can cover:

  • failed or warned tests;
  • source freshness breaches;
  • unusually long or expensive models;
  • undocumented published assets;
  • upcoming source or semantic changes;
  • recurring manual corrections.

Use the evidence to improve the project. A test that fires every week without action has lost its control value.

Start smaller than the target architecture

Choose one valuable domain and build the complete path: declared source, staged models, governed output, meaningful tests, documentation, CI and a production runbook. Confirm that a second person can understand and operate it. Then use the pattern for the next domain.

Your team should be able to explain how data enters the project, where business logic lives, how changes are reviewed and how quality is checked. Add a clear owner for each part, and you have a foundation people can use and build on.