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

Переменные окружения позволяют настраивать поведение проекта dbt в зависимости от того, где он выполняется. Обратитесь к документации по [env\_var](https://docs.getdbt.tech/reference/dbt-jinja-functions/env_var.md), чтобы узнать подробнее о том, как вызывать Jinja-функцию `{{env_var('DBT_KEY','OPTIONAL_DEFAULT')}}` в коде вашего проекта.

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

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

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

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

* [Порядок приоритета](#order-of-precedence)
* [Задание переменных окружения](#setting-environment-variables)
* [Переопределение переменных окружения на уровне job](#overriding-environment-variables-at-the-job-level)
* [Переопределение переменных окружения на персональном уровне](#overriding-environment-variables-at-the-personal-level)
* [Локальные переменные окружения](#local-environment-variables)

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

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

[![Порядок приоритета переменных окружения](</img/docs/dbt-platform/using-dbt-platform/Environment Variables/env-var-precdence.png?v=2> "Порядок приоритета переменных окружения")](#)Порядок приоритета переменных окружения

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

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

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

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

[![Вкладка переменных окружения](</img/docs/dbt-platform/using-dbt-platform/Environment Variables/navigate-to-env-vars.png?v=2> "Вкладка переменных окружения")](#)Вкладка переменных окружения

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

Справа от столбца **Значение по умолчанию для проекта** отображаются все ваши окружения. Значения, заданные на уровне окружения, имеют приоритет над значением по умолчанию на уровне проекта. Здесь можно, например, указать dbt, что значение переменной окружения следует интерпретировать по-разному в промежуточном (staging) и производственном (production) окружениях.

[![Настройка значений на уровне проекта и окружения](</img/docs/dbt-platform/using-dbt-platform/Environment Variables/project-environment-view.png?v=2> "Настройка значений на уровне проекта и окружения")](#)Настройка значений на уровне проекта и окружения

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

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

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

[![Переход к настройкам переопределения переменных среды для задания](</img/docs/dbt-platform/using-dbt-platform/Environment Variables/job-override.gif?v=2> "Переход к настройкам переопределения переменных среды для задания")](#)Переход к настройкам переопределения переменных среды для задания

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

[![Задание переопределяющего значения на уровне задания](</img/docs/dbt-platform/using-dbt-platform/Environment Variables/job-override.png?v=2> "Задание переопределяющего значения на уровне задания")](#)Задание переопределяющего значения на уровне задания

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

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

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

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

[![Настройка персонального переопределения значения](</img/docs/dbt-platform/using-dbt-platform/Environment Variables/personal-override.png?v=2> "Настройка персонального переопределения значения")](#)Настройка персонального переопределения значения

Значения для всех контекстов

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

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

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

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

[![Перезапуск IDE во время сеанса](</img/docs/dbt-platform/using-dbt-platform/Environment Variables/refresh-ide.png?v=2> "Перезапуск IDE во время сеанса")](#)Перезапуск IDE во время сеанса

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

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

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

Дополнительную информацию см. в разделе [Настройка расширения dbt для VS Code](https://docs.getdbt.tech/docs/configure-dbt-extension.md#set-environment-variables-locally).

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

Хотя все переменные окружения в dbt шифруются при хранении, dbt предоставляет дополнительные возможности для управления переменными окружения, содержащими секретные или другие конфиденциальные значения. Если вы хотите, чтобы значение определённой переменной окружения не только скрывалось в dbt, но и удалялось из всех журналов и сообщений об ошибках, добавьте к имени переменной префикс `DBT_ENV_SECRET_`.

Для переменных окружения с префиксом `DBT_ENV_SECRET_` действуют дополнительные меры безопасности. Они шифруются при хранении с помощью ключа шифрования (например, AWS KMS, если ваш экземпляр размещён в AWS), и доступ к ним возможен только после расшифровки с использованием этого ключа. Расшифровка разрешена только в определённых процессах, в которых требуется значение переменной, например при выполнении задания. Значения секретных переменных никогда не записываются в журналы или сообщения об ошибках и скрываются в dbt, поэтому они не раскрываются в пользовательском интерфейсе или артефактах и доступны dbt только во время выполнения, когда это необходимо.

[![Скрытие значений с помощью префикса DBT\_ENV\_SECRET](</img/docs/dbt-platform/using-dbt-platform/Environment Variables/DBT_ENV_SECRET.png?v=2> "Скрытие значений с помощью префикса DBT_ENV_SECRET")](#)Скрытие значений с помощью префикса DBT\_ENV\_SECRET

**Примечание**: Переменную окружения можно использовать для хранения [git‑токена для клонирования репозитория](https://docs.getdbt.tech/docs/build/environment-variables.md#clone-private-packages). Мы рекомендуем выдавать git‑токену права только на чтение и рассмотреть использование machine‑account или PAT сервисного пользователя с ограниченным доступом к репозиториям — это поможет соблюдать хорошие практики безопасности.

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

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

#### Детали Studio IDE

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

* `DBT_CLOUD_GIT_BRANCH` — Содержит имя Git-ветки разработки в [Studio IDE](https://docs.getdbt.tech/docs/platform/studio-ide/develop-in-studio.md).

  * Значение переменной меняется при смене ветки.
  * После смены ветки перезапуск Studio IDE не требуется.
  * В настоящее время недоступна в [dbt CLI](https://docs.getdbt.tech/docs/platform/dbt-cli-installation.md).

Пример использования — Эта переменная полезна, когда нужно динамически использовать имя Git-ветки в качестве префикса для [схемы разработки](https://docs.getdbt.tech/docs/build/custom-schemas.md) (`{{ env_var('DBT_CLOUD_GIT_BRANCH') }}`).

[]()

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

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

* `DBT_ENV` — Этот ключ зарезервирован для приложения dbt и всегда принимает значение 'prod'. Только для запусков развертывания.
* `DBT_CLOUD_ENVIRONMENT_NAME` — Имя среды dbt, в которой выполняется `dbt`.
* `DBT_CLOUD_ENVIRONMENT_TYPE` — Тип среды dbt, в которой выполняется `dbt`. Допустимые значения: `dev`, `staging` или `prod`. Для [сред развертывания общего назначения](https://docs.getdbt.tech/docs/dbt-platform-environments.md#types-of-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, даже если эти задания CI выполняются в той же среде, что и производственные задания.

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

* `DBT_CLOUD_PROJECT_ID` — Идентификатор проекта dbt для этого запуска
* `DBT_CLOUD_JOB_ID` — Идентификатор задания dbt для этого запуска
* `DBT_CLOUD_RUN_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` — Идентификатор среды для этого запуска
* `DBT_CLOUD_ACCOUNT_ID` — Идентификатор аккаунта dbt для этого запуска

#### Детали Git

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

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

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

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

[]()

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

Теперь, когда вы можете задавать секреты в виде переменных окружения, вы можете передавать git‑токены в HTTPS‑URL пакетов, чтобы динамически клонировать приватные репозитории. Подробнее см. раздел о [клонировании приватных пакетов](https://docs.getdbt.tech/docs/build/packages.md#private-packages).

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

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

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

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

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

[![Добавление переменных окружения в учетные данные подключения](</img/docs/dbt-platform/using-dbt-platform/Environment Variables/warehouse-override.png?v=2> "Добавление переменных окружения в учетные данные подключения")](#)Добавление переменных окружения в учетные данные подключения

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

Переменные окружения корректно работают при аутентификации с помощью имени пользователя и пароля или пары ключей, в том числе в заданиях, запускаемых по расписанию, поскольку dbt v1 обрабатывает Jinja, вставленный в автоматически сгенерированный файл [`profiles.yml`](https://docs.getdbt.tech/docs/local/profiles.yml.md), и выполняет поиск значения переменной окружения с помощью `env_var`.

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

* Нельзя использовать переменные окружения в поле account/host, но их можно использовать для database, warehouse и role. Для этих полей используйте [extended attributes](https://docs.getdbt.tech/docs/deploy/deploy-environments.md#deployment-connection).

Обратите внимание: если вы укажете переменную окружения в поле account/host, подключение к Snowflake через OAuth **не удастся** установить. Это происходит потому, что содержимое этого поля не обрабатывается шаблонизатором Jinja, поэтому dbt просто передаёт код `env_var` как есть в строку URL вида `{{ env_var("DBT_ACCOUNT_HOST_NAME") }}.snowflakecomputing.com`, что приводит к недопустимому имени хоста. Вместо этого используйте [расширенные атрибуты](https://docs.getdbt.tech/docs/dbt-platform-environments.md#extended-attributes).

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

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

```sql

{{ 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

Используйте [расширенные атрибуты](https://docs.getdbt.tech/docs/dbt-platform-environments.md#extended-attributes) и [переменные окружения](https://docs.getdbt.tech/docs/build/environment-variables.md) при подключении к семантическому слою. Если задать значение непосредственно в учетных данных семантического слоя, оно будет иметь более высокий приоритет, чем значение в расширенных атрибутах. При использовании переменных окружения будет использоваться значение по умолчанию для данного окружения.

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

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