dbt profiles.yml

The profiles.yml file stores all the connection information dbt needs to talk to your data warehouse. It includes credentials like usernames, passwords, host addresses, and schema names. This file lives on your computer — not inside the dbt project folder — so sensitive credentials stay out of version control.

Where profiles.yml Lives

Default location:   ~/.dbt/profiles.yml                    (your home directory, .dbt folder)
Windows:            C:\Users\YourName\.dbt\profiles.yml
macOS/Linux:        /home/yourname/.dbt/profiles.yml
Custom location:    set with --profiles-dir flag or DBT_PROFILES_DIR env var

Basic Structure

profile_name:              ← matches the 'profile' key in dbt_project.yml
  target: dev              ← which output to use by default
  outputs:
    dev:                   ← development environment
      type: ...
      ...connection details...
    prod:                  ← production environment
      type: ...
      ...connection details...

Snowflake Profile

my_snowflake_project:
  target: dev
  outputs:
    dev:
      type: snowflake
      account: abc12345.us-east-1
      user: alice
      password: my_secure_password
      role: TRANSFORMER
      database: ANALYTICS
      warehouse: COMPUTE_WH
      schema: DBT_DEV
      threads: 4
      client_session_keep_alive: false
    prod:
      type: snowflake
      account: abc12345.us-east-1
      user: dbt_service_account
      password: "{{ env_var('SNOWFLAKE_PASSWORD') }}"
      role: TRANSFORMER_PROD
      database: ANALYTICS
      warehouse: COMPUTE_WH_PROD
      schema: DBT_PROD
      threads: 8

BigQuery Profile

my_bigquery_project:
  target: dev
  outputs:
    dev:
      type: bigquery
      method: oauth              ← uses your gcloud credentials
      project: my-gcp-project
      dataset: dbt_dev
      threads: 4
      timeout_seconds: 300
    prod:
      type: bigquery
      method: service-account
      project: my-gcp-project
      dataset: dbt_prod
      keyfile: /path/to/service-account-key.json
      threads: 8

PostgreSQL Profile

my_postgres_project:
  target: dev
  outputs:
    dev:
      type: postgres
      host: localhost
      port: 5432
      user: alice
      password: localpassword
      dbname: analytics
      schema: dbt_dev
      threads: 4
    prod:
      type: postgres
      host: prod-db.company.com
      port: 5432
      user: dbt_prod_user
      password: "{{ env_var('POSTGRES_PASSWORD') }}"
      dbname: analytics
      schema: dbt_prod
      threads: 8

DuckDB Profile

my_duckdb_project:
  target: dev
  outputs:
    dev:
      type: duckdb
      path: /home/alice/projects/my_project/dev.duckdb
      threads: 4

Using Environment Variables for Secrets

Never put real passwords in profiles.yml for production. Use the env_var() Jinja function to read from environment variables instead:

password: "{{ env_var('DBT_PASSWORD') }}"
account: "{{ env_var('SNOWFLAKE_ACCOUNT') }}"

Set the environment variable in your shell or CI system:

export DBT_PASSWORD=my_secure_password
export SNOWFLAKE_ACCOUNT=abc12345.us-east-1
dbt run   ← reads password from environment, not the file

Switching Targets

# Use the default target (set in 'target: dev')
dbt run

# Override to use production target
dbt run --target prod

# Override to use a CI target
dbt run --target ci

Checking Your Connection

# Test the connection defined in profiles.yml
dbt debug

# Test a specific target
dbt debug --target prod

Multiple Projects in One profiles.yml

One profiles.yml file holds profiles for all your dbt projects. Each project's dbt_project.yml specifies which profile it uses:

# profiles.yml — holds ALL your project profiles
project_alpha:
  target: dev
  outputs:
    dev:
      type: snowflake
      ...

project_beta:
  target: dev
  outputs:
    dev:
      type: postgres
      ...

threads Configuration

The threads setting controls how many models dbt runs in parallel. More threads finish runs faster but use more warehouse compute resources.

threads: 1    ← run one model at a time (slowest, least resource use)
threads: 4    ← run 4 models simultaneously (good for development)
threads: 8    ← run 8 models simultaneously (good for production)
threads: 16   ← maximum for most setups (check warehouse concurrency limits)

Keep profiles.yml Out of Git

# .gitignore — never commit profiles.yml
~/.dbt/profiles.yml   ← already outside project folder (safe)

# If you store it in the project folder, add to .gitignore:
profiles.yml