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

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

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

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

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

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

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

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

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

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

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

Чтобы установить переменные окружения на уровне проекта и окружения, нажмите Deploy в левом верхнем углу, затем выберите Environments. Нажмите Environments Variables, чтобы добавить и обновить ваши переменные окружения.

Вкладка переменных окружения

Вы заметите, что есть колонка Project Default. Это отличное место для установки значения, которое будет сохраняться во всем вашем проекте, независимо от того, где выполняется код. Мы рекомендуем устанавливать это значение, когда вы хотите предоставить универсальное значение по умолчанию или добавить токен или секрет для всего проекта.

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

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

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

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

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

Навигация к настройкам переопределения переменных окружения для задания

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

Установка значения переопределения для задания

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

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

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

Навигация к настройкам личного переопределения переменных окружения

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

Установка личного значения переопределения

Соответствующее покрытие

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

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

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

Чтобы обновить IDE в середине разработки, нажмите на зеленый сигнал "готов" или красное сообщение об ошибке компиляции в правом нижнем углу IDE. Появится новое модальное окно, и вам следует выбрать кнопку Refresh IDE. Это загрузит значения ваших переменных окружения в вашу среду разработки.

Обновление IDE в середине сессии

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

Обработка секретов

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

Скрытие с префиксом DBT_ENV_SECRET

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

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

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

Детали IDE dbt Cloud

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

• DBT_CLOUD_GIT_BRANCH — Предоставляет имя ветки Git в IDE dbt Cloud.
  • Доступно в dbt v1.6 и позже.
  • Переменная изменяется при изменении ветки.
  • Не требует перезапуска IDE после изменения ветки.
  • В настоящее время недоступно в CLI dbt Cloud.

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

Контекст dbt Cloud

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

• DBT_ENV — Этот ключ зарезервирован для приложения dbt Cloud и всегда будет разрешаться как 'prod'. Только для запусков развертывания.
• DBT_CLOUD_ENVIRONMENT_NAME — Имя окружения dbt Cloud, в котором выполняется dbt.
• DBT_CLOUD_ENVIRONMENT_TYPE — Тип окружения dbt Cloud, в котором выполняется dbt. Допустимые значения: dev, staging или prod. Может быть не установлен, поэтому используйте значение по умолчанию, например {{env_var('DBT_CLOUD_ENVIRONMENT_TYPE', '')}}.

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

• DBT_CLOUD_PROJECT_ID — ID проекта dbt Cloud для этого запуска
• DBT_CLOUD_JOB_ID — ID задания dbt Cloud для этого запуска
• 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 Cloud для этого запуска

Детали Git

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

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

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

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

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

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

 Динамическая установка вашего склада в соединении Snowflake

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

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

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

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

Добавление переменных окружения в ваши учетные данные соединения

Переменные окружения и ограничения Snowflake OAuth

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

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

• Вы не можете использовать их в поле аккаунта/хоста, но они могут быть использованы для базы данных, склада и роли. Для этих полей используйте расширенные атрибуты.

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

 Аудит метаданных вашего запуска

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

{{ 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 *,
    -- Вставьте ID запуска, если он присутствует, в противном случае используйте "manual"
    '{{ env_var("DBT_CLOUD_RUN_ID", "manual") }}' as _audit_run_id

from users_aggregated

 Настройка учетных данных Семантического слоя

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

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

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