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.

​Why dbt_project.yml Matters

​Core Components of dbt_project.yml

​Project Metadata

​Profile Configuration

​Directory Paths

​Model Configuration

​Seed Configuration

​Variables

​On-Run Hooks

​Cleaning Up Artifacts

​Complete Example

​Best Practices for dbt_project.yml

​Common Issues and Solutions