# О функции env\_var

Функция `env_var` может использоваться для подключения переменных окружения из системы к вашему проекту dbt. Вы можете использовать функцию `env_var` в файле `profiles.yml`, в файле `dbt_project.yml`, в файле `sources.yml`, в файлах `schema.yml`, а также в `.sql`‑файлах моделей. По сути, `env_var` доступна везде, где dbt обрабатывает Jinja‑код.

При использовании в файле `profiles.yml` (чтобы избежать хранения учетных данных на сервере) это может выглядеть следующим образом:

profiles.yml

```yaml
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` при локальном запуске или в [профилях подключения](https://docs.getdbt.tech/docs/platform/about-profiles.md), если у вас есть проект в dbt platform. Если ваш проект ссылается на переменные окружения, которые не заданы, dbt выдаст ошибку компиляции.

(Версии dbt: v1.12 и новее)

### Использование файла `.env`

При локальном запуске dbt через [CLI](https://docs.getdbt.tech/docs/local/install-dbt.md), расширение для VS Code или в версии dbt v1.12 переменные автоматически загружаются из файла `.env` в текущем рабочем каталоге. Переменные окружения оболочки имеют приоритет над значениями в файле.

Создайте файл `.env`, обычно в корне проекта dbt, и задайте переменные в формате `KEY=value`. Например:

.env

```bash
DBT_USER=user
DBT_PASSWORD=password
DBT_SCHEMA=dbt_schema
```

Сошлитесь на них в `profiles.yml` через `env_var()`:

\~/.dbt/profiles.yml

```yaml
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`](https://docs.getdbt.tech/reference/dbt-jinja-functions/as_number.md), чтобы избежать ошибок вида `'1' is not of type 'integer'`. Например, `"{{ env_var('DBT_THREADS') | int }}"` или `"{{ env_var('DB_PORT') | as_number }}"`.

* **Логические значения** — явно преобразуйте строку фильтром [`as_bool`](https://docs.getdbt.tech/reference/dbt-jinja-functions/as_bool.md). Например, `"{{ env_var('DBT_PERSIST_DOCS_RELATION', False) | as_bool }}"`.

В качестве логических значений по умолчанию используйте `True` или `False` с заглавной буквы. Варианты `true` и `false` будут обработаны как строки и могут дать неожиданный результат.

Например, чтобы отключить [`persist_docs`](https://docs.getdbt.tech/reference/resource-configs/persist_docs.md) через переменные окружения:

dbt\_project.yml

```yml
+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.

### Значения по умолчанию

Вы также можете указать значение по умолчанию в качестве второго аргумента:

dbt\_project.yml

```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 для [частных пакетов](https://docs.getdbt.tech/docs/build/packages.md#private-packages).

**Примечание:** Когда dbt загружает учетные данные профиля и конфигурацию пакета, секретные переменные окружения будут заменены строковым значением переменной окружения. Вы не можете изменять секреты с помощью фильтров Jinja, включая фильтры приведения типов, такие как [`as_number`](https://docs.getdbt.tech/reference/dbt-jinja-functions/as_number.md) или [`as_bool`](https://docs.getdbt.tech/reference/dbt-jinja-functions/as_bool.md), или передавать их в качестве аргументов в другие макросы Jinja. Вы можете использовать *один секрет* на конфигурацию:

```yml
# работает
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](https://docs.getdbt.tech/reference/artifacts/dbt-artifacts.md#common-metadata): `metadata` -> `env`
* [События и структурированные логи](https://docs.getdbt.tech/reference/events-logging.md#structured-logging): `info` -> `extra`

Словарь этих переменных окружения с префиксом также будет доступен в контекстной переменной `dbt_metadata_envs`:

```sql
-- {{ dbt_metadata_envs }}

select 1 as id
```

```shell
$ DBT_ENV_CUSTOM_ENV_MY_FAVORITE_COLOR=indigo DBT_ENV_CUSTOM_ENV_MY_FAVORITE_NUMBER=6 dbt compile
```

Компилируется в:

```sql
-- {'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.
