Skip to main content

About profiles.yml

If you're using dbt from the command line, you need a profiles.yml file that contains the connection details for your data platform.

dbt platform accounts

dbt platform projects don't require a profiles.yml file unless you're developing from your local machine instead of the cloud-based UI.

About profiles.yml​

The profiles.yml file stores database connection credentials and configuration for dbt projects, including:

  • Connection details — Account identifiers, hosts, ports, and authentication credentials.
  • Target definitions — Define different environments (dev, staging, prod) within a single profile.
  • Default target — Set which environment to use by default.
  • Execution parameters — Thread count, timeouts, and retry settings.
  • Credential separation — Keep sensitive information out of version control.

The profile field in dbt_project.yml references a profile name defined in profiles.yml.

Location of profiles.yml​

Only one profiles.yml file is required and it can manage multiple projects and connections.

dbt searches for profiles.yml location in the following order and uses the first file it finds:

  1. --profiles-dir flag — Override for CI/CD or testing.
  2. Project root directory — Project-specific credentials.
  3. ~/.dbt/profiles.yml (Recommended location) — Shared across all projects.

~/.dbt/profiles.yml is the recommended location for the following reasons:

  • Security — Keeps credentials out of project directories and version control.
  • Reusability — A single file for all dbt projects on the machine.
  • Separation — Connection details don't travel with project code.

When should I use project root?​

Place your profiles.yml file in the project root directory for:

  • Self-contained demo or tutorial projects.
  • Docker containers with baked-in credentials.
  • CI/CD pipelines with environment-specific configs.

Create and configure the profiles.yml file​

The easiest way to create and configure a profiles.yml file is to execute dbt init after you've installed dbt on your machine. This takes you through the process of configuring an adapter and places the file into the recommended ~/.dbt/ location.

If your project has an existing profiles.yml file, running dbt init will prompt you to amend or overwrite it. If you select the existing adapter for configuration, dbt will automatically populate the existing values.

You can also manually create the file and add it to the proper location. To configure an adapter manually, copy and paste the fields from the adapter setup instructions for dbt Core or Fusion along with the appropriate values for each.

Example configuration​

The following example highlighs the format of the profiles.yml file. Note that many of the configs are adapter-specific and their syntax varies.

~/.dbt/profiles.yml
my_project_profile:  # Profile name (matches dbt_project.yml)
  target: dev  # Default target to use
  outputs:
    dev: # Development environment
      type: adapter_type # Required: snowflake, bigquery, databricks, redshift, postgres, etc
      # Connection identifiers (placeholder examples, see adapter-specific pages for supported configs)
      account: abc123  
      database: docs_team 
      schema: dev_schema       
      # Authentication (adapter-specific)
      auth_method: username_password  
      username: username
      password_credentials: password
      # Execution settings (common across adapters)
      threads: 4   # Number of parallel threads

# Multiple profiles (for multiple projects)
my_second_project_profile:
  target: dev
  outputs:
    dev:
      type: snowflake  # Example adapter
      account: account
      user: user
      password: password
      database: database
      schema: schema
      warehouse: warehouse
      threads: 4

Environment variables​

Use environment variables to keep sensitive credentials out of your profiles.yml file. Check out the env_var reference for more information.

Example:

~/.dbt/profiles.yml
my_profile:
  target: dev
  outputs:
    dev:
      type: ADAPTER_NAME
      account: "{{ env_var("ADAPTER_ACCOUNT") }}"
      user: "{{ env_var("ADAPTER_USER") }}"
      password: "{{ env_var("ADAPTER_PASSWORD") }}"
      database: "{{ env_var("ADAPTER_DATABASE") }}"
      schema: "{{ env_var("ADAPTER_SCHEMA") }}"
      warehouse: "{{ env_var("ADAPTER_WAREHOUSE") }}"
      role: "{{ env_var("ADAPTER_ROLE") }}"
      threads: 4

User config​

You can set default values of global configs for all projects that you run using your local machine. Refer to About global configs for details.

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

0
Loading