# О файле profiles.yml

Локальная разработка

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

Учетные записи платформы dbt

Для проектов dbt platform файл profiles.yml не требуется, если только вы не ведете разработку на локальном компьютере вместо облачного интерфейса.

## О файле profiles.yml

Файл `profiles.yml` хранит учетные данные для подключения к базе данных и настройки проектов dbt, в том числе:

* **Параметры подключения** — Идентификаторы учетных записей, хосты, порты и учетные данные для аутентификации.
* **Определения целевых окружений** — Позволяют задать разные окружения (dev, staging, prod) в одном профиле.
* **Целевое окружение по умолчанию** — Позволяет указать, какое окружение использовать по умолчанию.
* **Параметры выполнения** — Количество потоков, тайм-ауты и настройки повторных попыток.
* **Отдельное хранение учетных данных** — Позволяет хранить конфиденциальную информацию вне системы контроля версий.

Поле `profile` в [`dbt_project.yml`](https://docs.getdbt.tech/reference/dbt_project.yml.md) указывает имя профиля, заданное в `profiles.yml`.

## Расположение profiles.yml

Одного файла `profiles.yml` достаточно для работы с несколькими проектами и подключениями.

### dbt v2

dbt v2 ищет каталог с файлом `profiles.yml` в следующем порядке и использует первый найденный:

1. Флаг `--profiles-dir` — явно задаёт каталог, например для CI/CD или тестирования.
2. Корневой каталог проекта — для учётных данных конкретного проекта.
3. Каталог `~/.dbt/` (рекомендуемое расположение) — общий для всех проектов.

### dbt v1

dbt v1 ищет каталог с файлом `profiles.yml` в следующем порядке и использует первый найденный:

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

1. Флаг `--profiles-dir`
2. Переменная окружения `DBT_ENGINE_PROFILES_DIR`
3. Переменная окружения `DBT_PROFILES_DIR` (устарела, но поддерживается для обратной совместимости)
4. Текущий рабочий каталог
5. Каталог `~/.dbt/` (рекомендуемое расположение)

**Примечание.** dbt v1 отдаёт приоритет переменной `DBT_ENGINE_PROFILES_DIR` для каталога профилей. В v1.11 она соответствует схеме именования `DBT_ENGINE_*`. Используйте её в новых настройках. Переменная `DBT_PROFILES_DIR` по-прежнему поддерживается для совместимости.

dbt v1 поддерживает переменную окружения (Версии dbt: v1.11 и новее) `DBT_ENGINE_PROFILES_DIR` и поиск файла `profiles.yml` в текущем рабочем каталоге. В dbt v2 эти варианты пока недоступны.

Файл рекомендуется хранить в `~/.dbt/profiles.yml` по следующим причинам:

* **Безопасность** — учётные данные хранятся за пределами каталогов проектов и системы контроля версий.
* **Повторное использование** — один файл подходит для всех проектов dbt на компьютере.
* **Раздельное хранение** — параметры подключения хранятся отдельно от кода проекта.

#### Когда использовать корневой каталог проекта?

Храните файл `profiles.yml` в корневом каталоге проекта в следующих случаях:

* Самодостаточные демонстрационные или учебные проекты.
* Контейнеры Docker со встроенными учётными данными.
* Конвейеры CI/CD с конфигурацией для конкретного окружения.

## Создание и настройка файла `profiles.yml`

После установки dbt проще всего создать и настроить файл `profiles.yml` командой `dbt init`. Она проведёт вас через настройку адаптера и сохранит файл в рекомендуемом каталоге `~/.dbt/`.

Если в проекте уже есть файл `profiles.yml`, команда `dbt init` предложит изменить или перезаписать его. При выборе уже настроенного адаптера dbt автоматически подставит текущие значения.

Файл также можно создать вручную. Скопируйте поля из инструкции по настройке адаптера для [dbt v1](https://docs.getdbt.tech/docs/local/connect-data-platform/about-dbt-connections.md) или [dbt v2](https://docs.getdbt.tech/docs/local/profiles.yml.md), заполните их и сохраните файл в нужном каталоге.

### Пример конфигурации

Скопируйте в `profiles.yml` пример профиля для своего хранилища и настройте его следующим образом:

* Имя профиля. Задайте понятное имя, например название организации. Оно должно совпадать со значением `profile` в файле `dbt_project.yml`.

* `target`. Целевое окружение, которое проект использует по умолчанию. Оно должно быть задано в профиле. Обычно это `dev`.

* Поля в разделе `outputs`:

  * `type`. Тип хранилища данных, к которому подключается dbt.
  * Учётные данные хранилища. При необходимости запросите их у администратора базы данных. Храните их конфиденциально. К ним могут относиться поля `account`, `username` и `password`.
  * `schema`. Схема, в которой dbt по умолчанию создаёт объекты.
  * `threads`. Число потоков для выполнения проекта dbt.

В примере ниже показана структура файла `profiles.yml`. Многие параметры и их синтаксис зависят от адаптера.

\~/.dbt/profiles.yml

```yml
my_project_profile:  # Имя профиля (соответствует dbt_project.yml)
  target: dev  # Целевая среда по умолчанию
  outputs:
    dev: # Среда разработки
      type: adapter_type # Обязательно: snowflake, bigquery, databricks, redshift, postgres и т. д.
      # Идентификаторы подключения (примеры-заполнители; поддерживаемые настройки см. на страницах соответствующих адаптеров)
      account: abc123  
      database: docs_team 
      schema: dev_schema       
      # Аутентификация (зависит от адаптера)
      auth_method: username_password  
      username: username
      password_credentials: password
      # Настройки выполнения (общие для всех адаптеров)
      threads: 4   # Количество параллельных потоков

# Multiple profiles (for multiple projects)
my_second_project_profile:
  target: dev
  outputs:
    dev:
      type: snowflake  # Example adapter
      account: account
      user: user
      password: password
      database: database
      schema: schema
      warehouse: warehouse
      threads: 4
```

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

Используйте переменные окружения, чтобы не хранить конфиденциальные учетные данные в файле `profiles.yml`. Дополнительную информацию см. в справочнике по [env\_var](https://docs.getdbt.tech/reference/dbt-jinja-functions/env_var.md).

Пример:

\~/.dbt/profiles.yml

```yml
my_profile:
  target: dev
  outputs:
    dev:
      type: ADAPTER_NAME
      account: "{{ env_var('ADAPTER_ACCOUNT') }}"
      user: "{{ env_var('ADAPTER_USER') }}"
      password: "{{ env_var('ADAPTER_PASSWORD') }}"
      database: "{{ env_var('ADAPTER_DATABASE') }}"
      schema: "{{ env_var('ADAPTER_SCHEMA') }}"
      warehouse: "{{ env_var('ADAPTER_WAREHOUSE') }}"
      role: "{{ env_var('ADAPTER_ROLE') }}"
      threads: 4
```

При локальном использовании dbt вы также можете хранить переменные окружения в файле `.env` в корневом каталоге проекта вместо того, чтобы задавать их непосредственно в командной оболочке. dbt, расширение dbt для VS Code и dbt v1.12+ автоматически загружают файл `.env` из текущего рабочего каталога. Переменные окружения, заданные в командной оболочке, имеют приоритет над значениями из файла `.env`. Дополнительную информацию см. в разделе [О функции env\_var](https://docs.getdbt.tech/reference/dbt-jinja-functions/env_var.md#using-the-env-file).

Чтобы учетные данные не попадали в систему контроля версий, добавьте `.env` в файл `.gitignore` — в новых проектах, созданных с помощью `dbt init` в версии v1.12 и выше, эта запись включена по умолчанию.

## Пользовательская конфигурация

Вы можете задать значения глобальных настроек по умолчанию для всех проектов, которые запускаете на локальном компьютере. Подробнее см. в разделе [О глобальных настройках](https://docs.getdbt.tech/reference/global-configs/about-global-configs.md).

## Целевые окружения в профилях

dbt поддерживает несколько целевых окружений в одном профиле, чтобы способствовать использованию отдельных сред разработки и промышленной эксплуатации, как описано в разделе [Окружения dbt](https://docs.getdbt.tech/docs/local/dbt-environments.md).

Типичный профиль аналитика, использующего dbt локально, содержит целевое окружение с именем `dev`, которое выбрано по умолчанию.

В вашем профиле также может быть целевое окружение `prod`, в котором объекты создаются в промышленной схеме. Однако, поскольку промышленные запуски часто требуется выполнять по расписанию, мы рекомендуем развертывать проект dbt на отдельном компьютере, а не на локальном. У большинства пользователей dbt в профиле на локальном компьютере есть только целевое окружение `dev`.

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

Например, чтобы выполнить запуск в целевом окружении `prod` вместо используемого по умолчанию `dev`:

```bash
dbt run --target prod
```

Флаг `--target` можно использовать с любой командой dbt, например:

```bash
dbt build --target prod
dbt test --target dev
dbt compile --target qa
```

### Переопределение профилей и целевых окружений

При выполнении команд dbt вы можете указать используемые профиль и целевое окружение через CLI с помощью [флагов](https://docs.getdbt.tech/reference/global-configs/about-global-configs.md#available-flags) `--profile` и `--target`. Эти флаги переопределяют настройки из `dbt_project.yml`, при условии что указанные профиль и целевое окружение уже определены в файле `profiles.yml`.

Чтобы запустить проект dbt с профилем или целевым окружением, отличным от выбранных по умолчанию, используйте следующие флаги CLI:

* Флаг `--profile` — переопределяет профиль, заданный в `dbt_project.yml`, указывая на другой профиль, определенный в `profiles.yml`.
* Флаг `--target` — указывает целевое окружение внутри этого профиля (как определено в `profiles.yml`).

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

```bash
dbt run --profile my-profile-name --target dev
```

В этом примере команда `dbt run` будет использовать профиль `my-profile-name` и целевое окружение `dev`.

## Учетные данные хранилища данных

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

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

* Читать исходные данные
* Создавать схемы¹
* Читать системные таблицы

Запуск dbt без привилегии на создание схем

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

## Целевые схемы

Целевая схема — это схема по умолчанию, в которой dbt создает объекты. Она часто используется для разграничения отдельных окружений внутри хранилища данных.

Схемы в BigQuery

Для единообразия dbt использует термин «схема» в целевом окружении для всех поддерживаемых хранилищ данных. Обратите внимание: в BigQuery схема фактически представляет собой набор данных (dataset).

Схему, используемую в промышленном окружении, следует называть так, чтобы было понятно: она готова к использованию конечными пользователями для анализа — мы часто называем ее `analytics`.

Для разработки хорошо зарекомендовал себя подход, при котором схема в целевом окружении `dev` называется `dbt_<username>`. Добавление имени пользователя в качестве суффикса к имени схемы позволяет нескольким пользователям вести разработку в dbt: у каждого будет собственная отдельная схема для разработки, поэтому пользователи не будут перезаписывать объекты друг друга, а владельцы объектов и права доступа будут согласованы в пределах всей схемы.

Обратите внимание, что создавать целевую схему заранее не нужно — при запуске dbt проверит, существует ли она, и создаст ее при необходимости.

Хотя целевая схема представляет собой схему, которую dbt использует по умолчанию, иногда имеет смысл распределить модели по отдельным схемам. Это можно сделать с помощью [пользовательских схем](https://docs.getdbt.tech/docs/build/custom-schemas.md).

## Потоки выполнения

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

Дополнительную информацию см. в разделе [Использование потоков](https://docs.getdbt.tech/docs/running-a-dbt-project/using-threads.md).

## Связанные документы

* [Установка dbt](https://docs.getdbt.tech/docs/local/install-dbt.md)
* [Профили подключения](https://docs.getdbt.tech/docs/local/connection-profiles.md)