dbt Setting Up a Project

A dbt project is a folder on your computer that contains all your SQL models, tests, documentation, and configuration files. This topic shows you how to create a project from scratch using the dbt init command and connect it to a database.

The dbt init Command

The dbt init command creates a new project folder with a ready-to-use structure. Open your terminal, activate your dbt virtual environment, and run:

dbt init my_first_project

Replace my_first_project with any name you like. dbt creates a folder with that name in your current directory.

What dbt init Asks You

dbt init asks a few questions to configure your project:

Which database adapter do you want to use?
[1] duckdb
[2] postgres
[3] snowflake
...
Enter a number: 1

Profile my_first_project written to ~/.dbt/profiles.yml

After you answer, dbt creates two things: the project folder and a profile entry in your home directory at ~/.dbt/profiles.yml.

Connecting to DuckDB (Beginner-Friendly)

DuckDB requires no server, no account, and no credentials. The database is a single file on your laptop. When dbt init asks for adapter and you choose DuckDB, your profiles.yml entry looks like this:

my_first_project:
  target: dev
  outputs:
    dev:
      type: duckdb
      path: /home/yourname/my_first_project/dev.duckdb

The path points to a file that dbt creates automatically on first run. Nothing else to configure.

Connecting to PostgreSQL

If you have a PostgreSQL database, your profile looks like this:

my_first_project:
  target: dev
  outputs:
    dev:
      type: postgres
      host: localhost
      port: 5432
      user: your_username
      password: your_password
      dbname: analytics
      schema: dbt_dev
      threads: 4

The schema field controls where dbt writes its output tables. Using dbt_dev keeps development tables separate from production data.

Connecting to Snowflake

my_first_project:
  target: dev
  outputs:
    dev:
      type: snowflake
      account: abc12345.us-east-1
      user: your_username
      password: your_password
      role: TRANSFORMER
      database: ANALYTICS
      warehouse: COMPUTE_WH
      schema: DBT_DEV
      threads: 4

Testing the Connection

After setting up your profile, run this command from inside your project folder:

cd my_first_project
dbt debug

dbt debug checks your configuration and tests the warehouse connection. A successful result looks like:

All checks passed!
  Connection test: OK
  dbt_project.yml valid: OK
  profiles.yml valid: OK

If you see errors, read the error message carefully. Most errors point to a wrong hostname, incorrect password, or a missing schema.

Editing dbt_project.yml

The dbt_project.yml file lives in the root of your project folder. It controls the project name, paths, and default settings for models. Open it in any text editor. The default content looks like this:

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

profile: 'my_first_project'

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

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

models:
  my_first_project:
    +materialized: view

Key Settings to Understand

profile — The name dbt uses to look up connection details in ~/.dbt/profiles.yml. It must match the top-level key in that file.

model-paths — The folder where dbt looks for your SQL model files. Default is models/.

+materialized: view — The default materialization for all models. You can override this per model or per folder.

Writing Your First Model

dbt init creates an example model file at models/example/my_first_dbt_model.sql. Open it and you will see a simple SELECT statement. Replace it with your own SELECT to start building.

Create a new file at models/stg_customers.sql with this content:

select
    1 as customer_id,
    'Alice' as name,
    'alice@example.com' as email

union all

select
    2,
    'Bob',
    'bob@example.com'

This model creates a small table from hardcoded values. It is useful for testing your setup before connecting real source data.

Running the Project for the First Time

dbt run

dbt compiles your models and executes them in the warehouse. You see output like:

Running with dbt=1.8.3
Found 1 model, 0 tests, 0 snapshots

Concurrency: 4 threads (target='dev')

1 of 1 START sql view model dbt_dev.stg_customers ........... [RUN]
1 of 1 OK created sql view model dbt_dev.stg_customers ....... [OK in 0.32s]

Finished running 1 view model in 0.55 seconds.

Completed successfully.

Project Setup Checklist

[ ] Python 3.8+ installed
[ ] dbt adapter installed via pip
[ ] dbt init ran successfully
[ ] profiles.yml has correct credentials
[ ] dbt debug shows "All checks passed"
[ ] First model file created in models/
[ ] dbt run completes without errors

Once all items are checked, your dbt project is live and ready for real models. Every subsequent model you add follows the same pattern: write a SQL SELECT statement in a .sql file inside the models/ folder, then run dbt run.