Перейти к основному содержимому

Переменные окружения

Переменные окружения можно использовать для настройки поведения dbt‑проекта в зависимости от того, где именно он выполняется. Подробнее о том, как вызывать Jinja‑функцию {{env_var('DBT_KEY','OPTIONAL_DEFAULT')}} в коде проекта, см. документацию по env_var.

Именование и префиксы переменных окружения

Переменные окружения в dbt должны иметь префикс DBT_, DBT_ENV_SECRET_ или DBT_ENV_CUSTOM_ENV_. Ключи переменных окружения приводятся к верхнему регистру и являются чувствительными к регистру. При использовании {{env_var('DBT_KEY')}} в коде проекта ключ должен точно совпадать с именем переменной, заданной в интерфейсе dbt.

Установка и переопределение переменных окружения​

В этом разделе описано, как задавать и переопределять переменные окружения в dbt.

Порядок приоритета​

Значения переменных окружения могут быть заданы в нескольких местах внутри dbt. В результате dbt интерпретирует переменные окружения в следующем порядке приоритета (от низшего к высшему):

Порядок приоритета переменных окруженияПорядок приоритета переменных окружения

Существует четыре уровня задания переменных окружения:

  1. Необязательный аргумент значения по умолчанию, переданный в Jinja‑функцию env_var в коде ( самый низкий приоритет )
  2. Значение по умолчанию на уровне проекта, которое может быть переопределено
  3. Значение на уровне окружения, которое, в свою очередь, тоже может быть переопределено
  4. Значение на уровне job (job override) или в Studio IDE для конкретного разработчика (personal override) ( самый высокий приоритет )

Задание переменных окружения​

Чтобы задать переменные окружения на уровне проекта и окружения, нажмите Orchestration в левом меню, затем выберите Environments. Нажмите Environment variables, чтобы добавить или обновить переменные окружения.

Вкладка Environment variablesВкладка Environment variables

Обратите внимание на колонку Project default. Это удобное место для задания значения, которое будет применяться ко всему проекту независимо от того, где выполняется код. Мы рекомендуем использовать это поле, если вам нужен универсальный дефолт или если вы хотите добавить токен или секрет на уровне всего проекта.

Справа от колонки Project default находятся все ваши окружения. Значения, заданные на уровне окружения, имеют более высокий приоритет, чем значения по умолчанию на уровне проекта. Здесь, например, можно указать, что dbt должен по‑разному интерпретировать значение переменной в окружениях Staging и Production.

Задание значений на уровне проекта и окруженияЗадание значений на уровне проекта и окружения

Переопределение переменных окружения на уровне job​

У вас может быть несколько job, которые выполняются в одном и том же окружении, и при этом вы хотите, чтобы переменная окружения интерпретировалась по‑разному в зависимости от job.

При создании или редактировании job вы увидите раздел, в котором можно переопределить значения переменных окружения, заданные на уровне проекта или окружения.

Переход к настройкам переопределения переменных окружения для jobПереход к настройкам переопределения переменных окружения для job

Каждый job выполняется в конкретном deployment‑окружении и по умолчанию наследует значения, заданные на уровне этого окружения (или на самом высоком доступном уровне приоритета). Если вы хотите задать другое значение на уровне job, просто отредактируйте его — оно переопределит унаследованное значение.

Задание значения переопределения для jobЗадание значения переопределения для job

Переопределение переменных окружения на персональном уровне​

Вы также можете задать персональное переопределение значения переменной окружения при разработке в интегрированной среде разработчика dbt (Studio IDE). По умолчанию dbt использует значения переменных окружения, заданные в development‑окружении проекта. Чтобы просмотреть и переопределить эти значения, в dbt выполните следующие шаги:

  • Нажмите на имя вашей учетной записи в левом меню и выберите Account settings.
  • В разделе Your profile нажмите Credentials, затем выберите ваш проект.
  • Прокрутите до секции Environment variables и нажмите Edit, чтобы внести необходимые изменения.
Переход к настройкам персонального переопределения переменных окруженияПереход к настройкам персонального переопределения переменных окружения

Чтобы задать переопределение, разработчики могут указать другое значение для использования. Эти значения будут применяться в Studio IDE как на вкладке Results, так и на вкладке Compiled SQL.

Задание персонального значения переопределенияЗадание персонального значения переопределения
Достаточное покрытие

Если вы не задали значение по умолчанию на уровне проекта для каждой переменной окружения, может возникнуть ситуация, когда dbt не сможет корректно интерпретировать значение переменной во всех контекстах. В таких случаях dbt выдаст ошибку компиляции: Env var required but not provided.

Изменение переменных окружения в середине сессии в Studio IDE

Если вы измените значение переменной окружения во время активной сессии в Studio IDE, может потребоваться обновить Studio IDE, чтобы изменения вступили в силу.

Чтобы обновить Studio IDE во время разработки, нажмите либо на зеленый индикатор ready, либо на красное сообщение compilation error в правом нижнем углу Studio IDE. Появится модальное окно — в нем выберите кнопку Restart IDE. Это загрузит актуальные значения переменных окружения в вашу среду разработки.

Обновление IDE во время сессииОбновление IDE во время сессии

Существуют известные проблемы, связанные с частичным парсингом проекта и изменением переменных окружения в середине сессии IDE. Если вы обнаружили, что ваш dbt‑проект компилируется не с теми значениями, которые вы задали, попробуйте удалить файл target/partial_parse.msgpack в проекте dbt — это заставит dbt перекомпилировать весь проект целиком.

Локальные переменные окружения​

Если вы используете расширение dbt для VS Code, вы можете задать переменные окружения локально — в профиле shell (~/.zshrc или ~/.bashrc) либо в файле .env в корне вашего dbt‑проекта.

Подробнее см. страницу Configure the dbt VS Code extension.

Работа с секретами​

Хотя все переменные окружения в dbt хранятся в зашифрованном виде, dbt предоставляет дополнительные возможности для управления переменными, содержащими секреты или чувствительные данные. Если вы хотите, чтобы определенная переменная окружения была удалена (scrubbed) из всех логов и сообщений об ошибках, а также чтобы ее значение было скрыто в UI, вы можете добавить к ключу префикс DBT_ENV_SECRET. Эта функциональность поддерживается начиная с dbt v1.0.

Обфускация с префиксом DBT_ENV_SECRETОбфускация с префиксом DBT_ENV_SECRET

Примечание: Переменную окружения можно использовать для хранения git‑токена для клонирования репозитория. Мы рекомендуем выдавать git‑токену права только на чтение и рассмотреть использование machine‑account или PAT сервисного пользователя с ограниченным доступом к репозиториям — это поможет соблюдать хорошие практики безопасности.

Специальные переменные окружения​

В dbt есть ряд предопределенных переменных окружения. Эти переменные задаются автоматически и не могут быть изменены.

Детали Studio IDE​

Следующая переменная окружения автоматически задается для Studio IDE:

  • DBT_CLOUD_GIT_BRANCH — Содержит имя Git‑ветки разработки в Studio IDE.
    • Значение переменной меняется при смене ветки.
    • Не требует перезапуска Studio IDE после смены ветки.
    • В настоящее время недоступна в CLI dbt.

Сценарий использования — Полезно в случаях, когда нужно динамически использовать имя Git‑ветки в качестве префикса для схемы разработки ( {{ env_var ('DBT_CLOUD_GIT_BRANCH') }} ).

Контекст платформы dbt​

Следующие переменные окружения задаются автоматически:

  • DBT_ENV — Этот ключ зарезервирован для приложения dbt и всегда имеет значение prod. Используется только для deployment‑запусков.
  • DBT_CLOUD_ENVIRONMENT_NAME — Имя окружения dbt, в котором выполняется dbt.
  • DBT_CLOUD_ENVIRONMENT_TYPE — Тип окружения dbt, в котором выполняется dbt. Допустимые значения: dev, staging или prod. Для General deployment environments значение будет пустым, поэтому используйте значение по умолчанию, например {{ env_var('DBT_CLOUD_ENVIRONMENT_TYPE', '') }}.
  • DBT_CLOUD_INVOCATION_CONTEXT — Тип контекста, в котором был запущен dbt. Возможные значения: dev, staging, prod или ci.
    • Дополнительно, используйте DBT_CLOUD_INVOCATION_CONTEXT в макросе generate_schema_name(), чтобы задать явные правила использования схемы по умолчанию (с префиксом dbt_cloud_pr) в CI‑job, даже если эти CI‑job выполняются в том же окружении, что и production‑job.

Детали запуска​

  • DBT_CLOUD_PROJECT_ID — ID проекта dbt для данного запуска
  • DBT_CLOUD_JOB_ID — ID job dbt для данного запуска
  • DBT_CLOUD_RUN_ID — ID конкретного запуска
  • DBT_CLOUD_RUN_REASON_CATEGORY — «Категория» триггера запуска (одно из значений: scheduled, github_pull_request, gitlab_merge_request, azure_pull_request, other)
  • DBT_CLOUD_RUN_REASON — Конкретный триггер запуска (например, Scheduled, Kicked off by <email> или пользовательский триггер через API)
  • DBT_CLOUD_ENVIRONMENT_ID — ID окружения для данного запуска
  • DBT_CLOUD_ACCOUNT_ID — ID аккаунта dbt для данного запуска

Детали Git​

Следующие переменные в настоящее время доступны только для сборок Pull Request в GitHub, GitLab и Azure DevOps, запущенных через webhook

  • DBT_CLOUD_PR_ID — ID Pull Request в подключенной системе контроля версий
  • DBT_CLOUD_GIT_SHA — SHA git‑коммита, который выполняется для этой сборки Pull Request

Примеры использования​

Переменные окружения можно использовать множеством способов — они дают вам гибкость и упрощают реализацию нужных сценариев в dbt.

 Клонирование приватных пакетов

Теперь, когда вы можете задавать секреты в виде переменных окружения, вы можете передавать git‑токены в HTTPS‑URL пакетов, чтобы динамически клонировать приватные репозитории. Подробнее см. раздел о клонировании приватных пакетов.

 Динамическая настройка warehouse в подключении Snowflake

Переменные окружения позволяют динамически изменять размер виртуального warehouse Snowflake в зависимости от job. Вместо прямого указания имени warehouse в настройках подключения проекта вы можете сослаться на переменную окружения, значение которой будет задано во время выполнения.

Например, вы хотите запускать job с full-refresh в XL‑warehouse, а инкрементальный job — в warehouse среднего размера. Оба job настроены в одном и том же окружении dbt. В конфигурации подключения вы можете использовать переменную окружения и указать имя warehouse как {{env_var('DBT_WAREHOUSE')}}. Затем в настройках job задать разные значения переменной DBT_WAREHOUSE в зависимости от нагрузки job.

В настоящее время невозможно динамически менять значения переменных окружения между моделями в рамках одного запуска. Это связано с тем, что каждая env_var может иметь только одно значение на всю продолжительность run.

Примечание — Этот метод также можно использовать с Databricks SQL Warehouse.

Добавление переменных окружения в учетные данные подключенияДобавление переменных окружения в учетные данные подключения
Ограничения Snowflake OAuth и переменных окружения

Переменные окружения корректно работают с аутентификацией по имени пользователя/паролю и keypair, включая запланированные job, поскольку dbt Core обрабатывает Jinja, подставленный в автоматически сгенерированный profiles.yml, и выполняет env_var‑lookup.

Однако при использовании Snowflake OAuth Connection существуют ограничения:

  • Нельзя использовать переменные окружения в поле account/host, но их можно использовать для database, warehouse и role. Для этих полей используйте extended attributes.

Важно отметить: если вы укажете переменную окружения в поле account/host, Snowflake OAuth Connection не сможет подключиться. Это происходит потому, что это поле не проходит через Jinja‑рендеринг, и dbt передает буквальный код env_var в URL, например {{ env_var("DBT_ACCOUNT_HOST_NAME") }}.snowflakecomputing.com, что является некорректным hostname. Вместо этого используйте extended attributes.

 Аудит метаданных запуска

Вот еще один пример использования автоматически заданного ID запуска dbt. Это дополнительное поле данных можно использовать для аудита и отладки:


{{ config(materialized='incremental', unique_key='user_id') }}

with users_aggregated as (

    select
        user_id,
        min(event_time) as first_event_time,
        max(event_time) as last_event_time,
        count(*) as count_total_events

    from {{ ref('users') }}
    group by 1

)

select *,
    -- Inject the run id if present, otherwise use "manual"
    '{{ env_var("DBT_CLOUD_RUN_ID", "manual") }}' as _audit_run_id

from users_aggregated
 Настройка учетных данных Semantic Layer

Используйте Расширенные атрибуты и Переменные окружения при подключении к Семантическому слою. Если вы задаете значение непосредственно в Учетных данных Семантического слоя, оно будет иметь более высокий приоритет, чем Расширенные атрибуты. При использовании переменных окружения будет использоваться значение по умолчанию для окружения.

Например, задайте хранилище, используя {{env_var('DBT_WAREHOUSE')}} в ваших учетных данных Семантического слоя.

Аналогично, если вы задаете значение учетной записи с помощью {{env_var('DBT_ACCOUNT')}} в Расширенных атрибутах, dbt проверит как Расширенные атрибуты, так и переменную окружения.

Нашли ошибку?

0
Loading