env_var

The env_var function can be used to incorporate Environment Variables from the system into your dbt project. This env_var function can be used in your profiles.yml file, the dbt_project.yml file, the sources.yml file, your schema.yml files, and in model .sql files. Essentially env_var is available anywhere dbt processes jinja code.

When used in a profiles.yml file (to avoid putting credentials on a server), it can be used like this:

profiles.yml
profile:
  target: prod
  outputs:
    prod:
      type: postgres
      host: 127.0.0.1
      # IMPORTANT: Make sure to quote the entire Jinja string here
      user: "{{ env_var('DBT_USER') }}"
      password: "{{ env_var('DBT_PASSWORD') }}"
      ....

If the DBT_USER and DBT_PASSWORD environment variables are present when dbt is invoked, then these variables will be pulled into the profile as expected. If any environment variables are not set, then dbt will raise a compilation error.

Quoting, Curly Brackets, & You

Be sure to quote the entire jinja string (as shown above), or else the yaml parser will be confused by the Jinja curly brackets.

env_var accepts a second, optional argument for default value, like so:

dbt_project.yml
...
models:
  jaffle_shop:
    +materialized: "{{ env_var('DBT_MATERIALIZATION', 'view') }}"

This can be useful to avoid compilation errors when the environment variable isn't available.

Special env var prefixes

▶Changelog

If environment variables are named with one of two prefixes, it will have special behavior in dbt:

  • DBT_ENV_CUSTOM_ENV_: Any env var named with this prefix will be included in dbt artifacts, in a metadata.env dictionary, with its prefix-stripped name as its key.
  • DBT_ENV_SECRET_: Any env var named with this prefix will be scrubbed from dbt logs and replaced with *****, any time its value appears in those logs (even if the env var was not called directly). While dbt already avoids logging database credentials, this is useful for other types of secrets, such as git tokens for private packages, or AWS keys for querying data in S3.
dbt Cloud Usage

If you are using dbt Cloud, you must adhere to the naming conventions for environment variables. Environment variables in dbt Cloud must be prefixed with DBT_ (including DBT_ENV_CUSTOM_ENV_ or DBT_ENV_SECRET_). Environment variables keys are uppercased and case sensitive. When referencing {{env_var('DBT_KEY')}} in your project's code, the key must match exactly the variable defined in dbt Cloud's UI.

Edit this page