О функции env_var
Функция env_var может использоваться для подключения переменных окружения из системы к вашему проекту dbt. Вы можете использовать функцию env_var в файле profiles.yml, в файле dbt_project.yml, в файле sources.yml, в файлах schema.yml, а также в .sql‑файлах моделей. По сути, env_var доступна везде, где dbt обрабатывает Jinja‑код.
При использовании в файле 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') }}"
....
Если переменные окружения DBT_USER и DBT_ENV_SECRET_PASSWORD заданы на момент запуска dbt, dbt будет использовать их в конфигурации подключения — например, в profiles.yml при локальном запуске или в профилях подключения, если у вас есть проект в dbt platform. Если ваш проект ссылается на переменные окружения, которые не заданы, dbt выдаст ошибку компиляции.
Использование файла .env
При локальном запуске dbt через CLI, расширение для VS Code или в версии dbt v1.12 переменные автоматически загружаются из файла .env в текущем рабочем каталоге. Переменные окружения оболочки имеют приоритет над значениями в файле.
Создайте файл .env, обычно в корне проекта dbt, и задайте переменные в формате KEY=value. Например:
DBT_USER=user
DBT_PASSWORD=password
DBT_SCHEMA=dbt_schema
Сошлитесь на них в profiles.yml через env_var():
my_profile:
target: dev
outputs:
dev:
type: postgres
host: localhost
user: "{{ env_var('DBT_USER') }}"
password: "{{ env_var('DBT_PASSWORD') }}"
schema: "{{ env_var('DBT_SCHEMA') }}"
port: 5432
threads: 4
При определении переменных окружения в файле .env учитывайте следующее:
- Файл
.envпозволяет удобно задавать переменные окружения, которые работают как в CLI, так и в расширении для VS Code. - Рекомендуем размещать файл
.envв корневом каталоге проекта и запускать команды dbt из этого каталога, поскольку файл загружается только из текущего рабочего каталога. Загрузка файла не поддерживает флаг--project-dirили переменную окружения (Версии dbt: v1.11 и новее)DBT_ENGINE_PROJECT_DIR, и dbt не будет искать файл в корневом каталоге проекта, если вы запускаете команды из другого каталога. - Добавьте
.envв файл.gitignore, чтобы конфиденциальные учетные данные не попали в репозиторий при коммите. - Переменные окружения, заданные непосредственно в командной оболочке (например,
export DBT_ENV_VAR=value), имеют приоритет над значениями, определенными в файле.env.
Преобразование переменных окружения
Значения переменных окружения всегда являются строками. Для параметров, которые ожидают целые числа или логические значения, тип нужно преобразовать явно.
Для преобразования используйте фильтр Jinja:
-
Целые числа — преобразуйте строку через
intилиas_number, чтобы избежать ошибок вида'1' is not of type 'integer'. Например,"{{ env_var('DBT_THREADS') | int }}"или"{{ env_var('DB_PORT') | as_number }}". -
Логические значения — явно преобразуйте строку фильтром
as_bool. Например,"{{ env_var('DBT_PERSIST_DOCS_RELATION', False) | as_bool }}".
В качестве логических значений по умолчанию используйте True или False с заглавной буквы. Варианты true и false будут обработаны как строки и могут дать неожиданный результат.
Например, чтобы отключить persist_docs через переменные окружения:
+persist_docs:
relation: "{{ env_var('DBT_PERSIST_DOCS_RELATION', False) | as_bool }}"
columns: "{{ env_var('DBT_PERSIST_DOCS_COLUMNS', False) | as_bool }}"
Обязательно заключайте всю строку Jinja в кавычки. Иначе фигурные скобки Jinja приведут к ошибке при разборе YAML.
Значения по умолчанию
Вы также можете указать значение по умолчанию в качестве второго аргумента:
...
models:
jaffle_shop:
+materialized: "{{ env_var('DBT_MATERIALIZATION', 'view') }}"
Это может быть полезно для избежания ошибок компиляции, когда переменная окружения недоступна.
Секреты
Для определенных конфигураций вы можете использовать "секретные" переменные окружения. Любая переменная окружения с префиксом DBT_ENV_SECRET будет:
- Доступна для использования в
profiles.yml+packages.ymlчерез ту же функциюenv_var() - Запрещена везде, включая
dbt_project.ymlи SQL моделей, чтобы предотвратить случайную запись этих секретных значений в data warehouse или метаданные артефактов - Удалена из логов dbt и заменена на
*****, всякий раз, когда ее значение появляется в этих логах (даже если переменная окружения не была вызвана напрямую)
Основной случай использования секретных переменных окружения — это токены доступа git для частных пакетов.
Примечание: Когда dbt загружает учетные данные профиля и конфигурацию пакета, секретные переменные окружения будут заменены строковым значением переменной окружения. Вы не можете изменять секреты с помощью фильтров Jinja, включая фильтры приведения типов, такие как as_number или as_bool, или передавать их в качестве аргументов в другие макросы Jinja. Вы можете использовать один секрет на конфигурацию:
# работает
host: "{{ env_var('DBT_ENV_SECRET_HOST') }}"
# не работает
host: "www.{{ env_var('DBT_ENV_SECRET_HOST_DOMAIN') }}.com/{{ env_var('DBT_ENV_SECRET_HOST_PATH') }}"
Пользовательские метаданные
Любая переменная окружения с префиксом DBT_ENV_CUSTOM_ENV_ будет включена в двух местах, с именем без префикса в качестве ключа:
- Артефакты dbt:
metadata->env - События и структурированные логи:
info->extra
Словарь этих переменных окружения с префиксом также будет доступен в контекстной переменной dbt_metadata_envs:
-- {{ dbt_metadata_envs }}
select 1 as id
$ DBT_ENV_CUSTOM_ENV_MY_FAVORITE_COLOR=indigo DBT_ENV_CUSTOM_ENV_MY_FAVORITE_NUMBER=6 dbt compile
Компилируется в:
-- {'MY_FAVORITE_COLOR': 'indigo', 'MY_FAVORITE_NUMBER': '6'}
select 1 as id
Использование платформы dbt
Если вы используете dbt platform, переменные окружения должны:
- Иметь префикс
DBT_(в том числеDBT_ENV_CUSTOM_ENV_илиDBT_ENV_SECRET) - Быть записаны в верхнем регистре
- Учитывать регистр символов
При обращении к {{env_var('DBT_KEY')}} в коде вашего проекта ключ должен в точности совпадать с именем переменной, заданным в пользовательском интерфейсе dbt platform.
Если вы используете dbt Cloud, вы должны соблюдать соглашения о наименовании переменных окружения. Переменные окружения в dbt Cloud должны иметь префикс DBT_ (включая DBT_ENV_CUSTOM_ENV_ или DBT_ENV_SECRET). Ключи переменных окружения пишутся заглавными буквами и чувствительны к регистру. При обращении к {{env_var('DBT_KEY')}} в коде вашего проекта ключ должен точно соответствовать переменной, определенной в интерфейсе dbt Cloud.