dbt Model Access Design Guide: When to Use public / protected / private

In dbt, access is a property that controls which models can be referenced via ref, improving design consistency and the safety of future changes. It pairs especially well with a layered architecture (staging / intermediate / marts), where it makes dependency boundaries explicit and simplifies impact assessment when you extend the project.

This article walks through the basics of public / protected / private, common design patterns, YAML implementation examples, and CI verification checkpoints. It also covers what shows up on the dbt Analytics Engineer exam: model boundaries, how access combines with contracts and versions, and how it differs from grants.

access Basics and When to Use Each Level

access is a resource property used mainly on models that controls whether they can be referenced from other packages or projects. dbt detects access violations at compile time and blocks unintended references.

The baseline policy is: private for staging, protected for integration and intermediate layers, and public for consumer-facing marts. This keeps the blast radius of changes contained in successive stages.

• private: the most closed scope. Protects raw data and unstable intermediate shapes
• protected: shared only within the project or a defined boundary. Prevents over-exposure
• public: allows references from external packages too. A stable, API-like interface

Layered Design Pattern (stg / int / mart)

The most stable approach in practice is to fix access per layer. Doing so blocks unintended back-references and skip-references (for example, referencing stg directly from mart).

External packages can only reference the public mart layer, and int (protected) is treated as untouchable from outside the boundary.

• stg_*: private (resilient to source-shape drift and naming churn)
• int_*: protected (intermediate layer for aggregation, normalization, key assignment, etc.)
• mart_*: public (curated, with explicit contracts and versions)

Dependencies and exposure boundaries (example)

Implementation Example (YAML) and Basic Verification Flow

The example below assigns access and group per layer within a single project. Combining contracts and versions raises the stability of public models.

access violations are detected during dbt's compile-to-build phase. In CI, run dbt build with dependent packages included and fail the job when a violation occurs.

• group is useful for documentation and signaling boundary intent (keep naming consistent)
• Combine contract and version on public models; ship breaking changes as a new version
• Build with dependencies in CI to detect access violations early

models/schema.yml (example)

version: 2
models:
  - name: stg_orders
    description: Raw orders from source, lightly cleaned
    config:
      access: private
      group: staging
      contract:
        enforced: true
    columns:
      - name: order_id
        data_type: int
      - name: order_ts
        data_type: timestamp

  - name: int_orders
    description: Conformed orders, with keys and normalized types
    config:
      access: protected
      group: integration
    columns:
      - name: order_id
        tests: [not_null]

  - name: dim_customers
    description: Curated customer dimension (public interface)
    config:
      access: public
      group: marts
      contract:
        enforced: true
    versions:
      - v: 1
      - v: 2
    latest_version: 2
    columns:
      - name: customer_id
        data_type: int
      - name: customer_tier
        data_type: string

Exposure Strategy Across Multiple Projects/Packages

Models that are intended to be referenced from other packages should be limited to public. If you try to ref a protected or private model from outside, dbt flags it as a violation before the build stage.

When changing a public model, separate breaking from non-breaking changes. The safe pattern is to ship breaking changes as a new version and run the old and new versions side by side until latest_version is switched over.

• External exposure = public. Non-exposure = protected/private
• Breaking changes = new version. Non-breaking = add columns within the same version (watch the contract)
• Explicitly manage the lifetime of the old version to absorb downstream upgrade timing

How access Relates to contracts, versions, and grants

access controls 'whether you can reference a model within dbt.' Database read privileges are managed separately via grants (an adapter implementation). Even a public model cannot be read by direct SQL without warehouse-side privileges.

contracts guarantee schema consistency, and versions guarantee interface compatibility over time. For public models, the three-piece combo (access + contract + version) is close to the canonical answer for both production use and the exam.

• access: dbt's ref guard (a design-level boundary)
• grants: actual privileges on the warehouse. Affects exposure to BI and external tools
• contracts/versions: manage the compatibility of public APIs (columns, types, evolution)

Exam Tips and Pitfalls

On the Analytics Engineer certification, expect frequent questions on per-layer exposure, the combination of access / contracts / versions, and how access differs from grants. Read the scenario for 'who uses it' and 'how widely it should be exposed.'

Key points: do not confuse protected with private, do not casually expand public, and use versioning for breaking changes.

• Per-layer defaults: stg = private / int = protected / mart = public
• Attach contract and version to public models (design for compatibility)
• Be clear on the split: access governs ref, grants governs warehouse privileges

Check Your Understanding

Frequently Asked Questions