By the end of this lesson, you’ll be able to confidently read and navigate any dbt project, and you’ll have the foundation needed to start building models in a structured way.

What is a dbt Project?

A dbt project is a directory that contains the folders and configuration files dbt needs to run your transformations on a data warehouse.

Here’s what a new dbt project named demo_project looks like:

demo_project/
│── analyses/         
│── macros/           
│── models/            
│── seeds/            
│── snapshots/        
│── tests/            
│── dbt_project.yml   
│── README.md

Key Files

At a minimum, every dbt project requires the dbt_project.yml configuration file.
When you initialize a project, dbt creates a set of standard folders and files to help you organize your work:

  • models: Contains SQL models that define transformations.
  • analyses :Contains SQL files that are not considered models. These files will be compiled but not executed.
  • macros: Stores reusable Jinja templates (similar to functions in programming languages).
  • seeds: Static CSV data that can be loaded into the warehouse.
  • snapshots: Tracks changes in data over time.
  • tests: SQL queries that you can write to test the models and resources in your project.
  • dbt_project.yml: Configuration for models, tests, and execution settings.

dbt_project.yml file

The dbt_project.yml file is the main configuration file of your dbt project. It is typically divided into four main sections:

  1. Project details – name, version, and metadata

  2. Profile – specifies which database connection to use

  3. Directory paths – locations of models, seeds, snapshots, and tests

  4. Model configurations – default materializations and settings

dbt_project.yml 
# ---------------------------
# 1. Project details
# ---------------------------

# Project name (use only lowercase and underscores)
# Good practice: match your org name or use-case
name: 'demo_project'
version: '1.0.0'

# ---------------------------
# 2. Profile (database connection)
# ---------------------------

# Tells dbt which profile to use in profiles.yml
profile: 'demo_project'

# ---------------------------
# 3. Directory paths
# ---------------------------

# Where dbt should look for different types of files
model-paths: ["models"]       # SQL models
analysis-paths: ["analyses"]  # Analysis queries (not materialized)
test-paths: ["tests"]         # Data tests
seed-paths: ["seeds"]         # Static CSV files
macro-paths: ["macros"]       # Reusable Jinja macros
snapshot-paths: ["snapshots"] # Snapshots for slowly changing data

# Directories to remove when running `dbt clean`
clean-targets:
  - "target"
  - "dbt_packages"

# ---------------------------
# 4. Model configurations
# ---------------------------

# Configure how models should be materialized by default
models:
  demo_project:              # Namespace (your project name)
    example:                 # Folder inside /models/
      +materialized: view    # Default: build as views

Profiles file

When you run dbt from the command line, you need a profiles.yml file with your data platform connection settings. dbt reads dbt_project.yml to get the profile name, then finds the matching profile in profiles.yml. That profile includes everything dbt needs to connect to your data platform.

In the example below, profiles.yml defines a profile called demo_project with a dev target configured for a PostgreSQL database. Note that the username and password are shown in plain text for simplicity. In production, store sensitive values in dbt environment variables instead of hardcoding them.

profiles.yml 
demo_project:
  target: dev
  outputs:
    dev:
      type: postgres
      host: localhost
      user: dbt_user
      password: dbt_pass
      port: 5432
      dbname: test_dbt_db 
      schema: test_dbt_schema
      threads: 1

Conclusion

You explored the essential folders in the dbt project structure and concluded by connecting dbt to a PostgreSQL database. We hope you find this guide helpful for your setup dbt local postgresSQL journey. Now, it’s time to get hands-on with dbt’s capabilities.

Let’s move on to the next lesson: Explore dbt models.

PreviousNext