Setting up your dbt_project.yml

The dbt_project.yml file is the core configuration file for any dbt project. It defines essential settings such as the project name, version, and model configurations, ensuring your project runs correctly and consistently.


Why dbt_project.yml Matters

The dbt_project.yml file serves several important functions:

  • Identifies the root of your dbt project

  • Configures project-wide settings

  • Sets default materializations for your models

  • Defines model-specific configurations

  • Controls directory paths and behaviors

A well-configured project file ensures consistent behavior across environments and team members.


Core Components of dbt_project.yml

Here's a breakdown of the key sections and their purposes:

Project Metadata

name: 'my_dbt_project'  # The unique name of your dbt project
version: '1.0.0'        # Optional versioning for project tracking
config-version: 2       # The version of dbt's config schema

This section defines:

  • name: A unique identifier for your project (used in compiled SQL)

  • version: Optional versioning for tracking project changes

  • config-version: The version of dbt's configuration schema (should be 2 for current projects)

Profile Configuration

profile: 'my_profile'  # Specifies the profile to use from profiles.yml

This tells dbt which profile to use from your profiles.yml file. Profiles define database connections and credentials.

Setting
Purpose
Example

profile

Specifies which connection profile to use

profile: 'snowflake_analytics'

Directory Paths

# Paths for different dbt components
model-paths: ["models"]
analysis-paths: ["analyses"]
test-paths: ["tests"]
seed-paths: ["seeds"]
macro-paths: ["macros"]
snapshot-paths: ["snapshots"]

These settings define where dbt should look for different types of files:

Path Setting
Default
Purpose

model-paths

["models"]

Where your SQL models are stored

seed-paths

["seeds"]

Where your CSV files are stored

test-paths

["tests"]

Where singular tests are stored

analysis-paths

["analyses"]

Where analytical queries are stored

macro-paths

["macros"]

Where macros are stored

snapshot-paths

["snapshots"]

Where snapshot definitions are stored

Model Configuration

This section defines how your models should be materialized and configured:

models:
  my_dbt_project:  # Must match your project name
    +materialized: view   # Default materialization for all models
    
    # Configure specific directories
    staging:
      +materialized: view  # Staging models as views
    
    marts:
      +materialized: table # Mart models as tables
      
      # Configure specific subdirectories
      marketing:
        +schema: marketing_schema  # Custom schema

Key points about model configuration:

  • Configuration is hierarchical - lower levels inherit from higher levels

  • The top-level project name must match your name value

  • The + prefix indicates a dbt configuration property

  • You can override configurations at any level

Seed Configuration

For controlling how CSV files are loaded into your database:

seeds:
  my_dbt_project:
    +schema: raw_data     # Default schema for seed files
    +quote_columns: false # Whether to quote column names
    
    # Configuration for specific seeds
    country_codes:
      +column_types:
        country_code: varchar(2)

Variables

Define project-wide variables that can be used in models:

vars:
  start_date: '2020-01-01'  # Available as {{ var('start_date') }}
  countries: ['US', 'CA', 'UK']
  # Environment-specific variables
  dev:
    debug_mode: true
  prod:
    debug_mode: false

On-Run Hooks

Execute SQL before or after your dbt runs:

on-run-start:
  - "create schema if not exists {{ target.schema }}_staging"
  
on-run-end:
  - "grant usage on schema {{ target.schema }} to role reporter"
  - "grant select on all tables in schema {{ target.schema }} to role reporter"

Cleaning Up Artifacts

Define which directories should be cleaned by dbt clean:

clean-targets:
  - "target"
  - "dbt_packages"
  - "logs"

Complete Example

Here's a complete example of a dbt_project.yml file:

name: 'ecommerce'
version: '1.0.0'
config-version: 2

profile: 'snowflake_analytics'

model-paths: ["models"]
seed-paths: ["seeds"]
test-paths: ["tests"]
analysis-paths: ["analyses"]
macro-paths: ["macros"]
snapshot-paths: ["snapshots"]
docs-paths: ["docs"]

target-path: "target"
clean-targets:
  - "target"
  - "dbt_packages"
  - "logs"

vars:
  start_date: '2020-01-01'
  include_test_accounts: false

models:
  ecommerce:
    +materialized: view
    
    staging:
      +materialized: view
      +schema: staging
      
    intermediate:
      +materialized: view
      +schema: intermediate
    
    marts:
      +materialized: table
      +schema: analytics
      
      finance:
        +schema: analytics_finance
        +tags: ["finance", "daily"]
      
      marketing:
        +schema: analytics_marketing
        +tags: ["marketing"]

seeds:
  ecommerce:
    +schema: reference_data

snapshots:
  ecommerce:
    +target_schema: snapshots

on-run-end:
  - "grant select on all tables in schema {{ target.schema }} to role analyst"

Best Practices for dbt_project.yml

Category
Best Practices

Use Meaningful Names and Structure

✅ Group models logically by function or business domain ✅ Use consistent naming patterns for schemas ✅ Document non-obvious configurations with comments

Set Sensible Defaults

✅ Define default materializations for different model types ✅ Use views for staging/intermediate models and tables for final models ✅ Configure schemas to match your data warehouse organization

Optimize for Team Collaboration

✅ Use environment-specific variables where needed ✅ Set appropriate permissions with on-run hooks ✅ Document variables and their purposes

Maintain and Evolve

✅ Review your project configuration regularly ✅ Update as your project grows and changes ✅ Document changes to configuration in version control


Common Issues and Solutions

Issue
Solution

Models building in wrong schema

Check schema configuration and target profile

Incorrect materialization

Verify hierarchy of materialization settings

Variable not available

Ensure variable is defined at the correct level

Path not found

Verify directory paths match actual project structure

Your dbt_project.yml file is a living document that will evolve with your project. Taking the time to configure it correctly will lead to a more maintainable and consistent dbt implementation.

Last updated

Was this helpful?