# Настройка и использование dbt platform CLI

Платформа dbt

Узнайте, как настроить dbt platform CLI для вашего проекта dbt, чтобы выполнять команды dbt, например `dbt environment show` для просмотра конфигурации dbt или `dbt compile` для компиляции проекта и проверки моделей и тестов. Вы также получите следующие преимущества:

* Безопасное хранение учетных данных в dbt platform.
* [Автоматическое перенаправление ссылок](https://docs.getdbt.tech/docs/platform/about-defer.md) с использованием артефактов сборки из производственной среды вашего проекта.
* Более быстрые сборки с меньшими затратами.
* Поддержка Mesh ([межпроектные ссылки ref](https://docs.getdbt.tech/docs/mesh/govern/project-dependencies.md)) и другие возможности.

## Предварительные требования

* Необходимо настроить проект в dbt.
  * **Примечание** — Если вы используете dbt platform CLI, вы можете подключиться к своей [платформе данных](https://docs.getdbt.tech/docs/platform/connect-data-platform/about-connections.md) непосредственно в интерфейсе dbt platform; файл [`profiles.yml`](https://docs.getdbt.tech/docs/local/profiles.yml.md) при этом не требуется.
* В разделе **Account settings** необходимо настроить [личные учетные данные пользователя](https://docs.getdbt.tech/docs/dbt-platform-environments.md#set-developer-credentials) для этого проекта. dbt platform CLI будет использовать эти учетные данные, безопасно хранящиеся в dbt, для взаимодействия с вашей платформой данных.
* Необходимо использовать dbt версии 1.5 или выше. Инструкции по обновлению см. в разделе [Версии dbt](https://docs.getdbt.tech/docs/dbt-versions/upgrade-dbt-platform-version.md).

## Настройка dbt platform CLI

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

1. В dbt выберите проект, для которого вы хотите настроить dbt platform CLI. В проекте уже должна быть настроена [среда разработки](https://docs.getdbt.tech/docs/dbt-platform-environments.md#create-a-development-environment).

2. Скачайте файл учетных данных `dbt_cloud.yml` и сохраните его в каталоге `.dbt` (`~/.dbt/dbt_cloud.yml` в macOS/Linux, `C:\Users\yourusername\.dbt\dbt_cloud.yml` в Windows). Инструкции по скачиванию, полную структуру файла и справочник полей см. в разделе [`dbt_cloud.yml`](https://docs.getdbt.tech/reference/dbt_cloud.yml.md).

3. После скачивания файла конфигурации и создания каталога перейдите в каталог проекта в терминале:

   ```bash
   cd ~/dbt-projects/jaffle_shop
   ```

4. Убедитесь, что в файле `dbt_project.yml` есть [блок `dbt-cloud`](https://docs.getdbt.tech/reference/dbt_cloud.yml.md#the-dbt-cloud-block-in-dbt_projectyml) с полем `project-id`, указывающим на ваш проект dbt, или добавьте его.

   ```yaml
   # dbt_project.yml
   dbt-cloud:
       project-id: PROJECT_ID
   ```

5. Теперь вы можете [использовать dbt platform CLI](#use-the-dbt-cli) и выполнять [команды dbt](https://docs.getdbt.tech/reference/dbt-commands.md), например [`dbt environment show`](https://docs.getdbt.tech/reference/commands/dbt-environment.md?version=2.0) для просмотра подробной информации о конфигурации dbt или `dbt compile` для компиляции моделей в вашем проекте dbt.

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

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

Чтобы настроить переменные окружения в dbt platform CLI для вашего проекта dbt:

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

## Использование dbt platform CLI

dbt platform CLI использует тот же набор [команд dbt](https://docs.getdbt.tech/reference/dbt-commands.md) и [команд MetricFlow](https://docs.getdbt.tech/docs/build/metricflow-commands.md), что и dbt v1, для выполнения указанных вами команд. Например, используйте команду [`dbt environment`](https://docs.getdbt.tech/reference/commands/dbt-environment.md?version=2.0), чтобы просмотреть подробную информацию о конфигурации dbt. С помощью dbt platform CLI вы можете:

* Выполнять [несколько вызовов параллельно](https://docs.getdbt.tech/reference/dbt-commands.md), обеспечивая [безопасное параллельное выполнение](https://docs.getdbt.tech/reference/dbt-commands.md#parallel-execution).
* Автоматически перенаправлять ссылки, используя артефакты сборки из производственной среды вашего проекта.
* Использовать [зависимости между проектами](https://docs.getdbt.tech/docs/mesh/govern/project-dependencies.md), которые позволяют вашему проекту зависеть от другого проекта с помощью сервиса метаданных в dbt.
  * Зависимости между проектами позволяют сразу подключаться к публичным моделям, определенным в других проектах, и ссылаться на них (с помощью `ref`). Вам не нужно самостоятельно выполнять или анализировать эти вышестоящие модели. Вместо этого вы работаете с ними как с API, возвращающим набор данных.

Используйте флаг `--help`

Полезный совет: большинство инструментов командной строки поддерживают флаг `--help` для просмотра доступных команд и аргументов. Используйте флаг `--help` с dbt двумя способами:

* `dbt --help`: выводит список доступных команд dbt
  <br />
* `dbt run --help`: выводит список флагов, доступных для команды `run`

## Проверка SQL-файлов линтером

Из dbt platform CLI можно вызывать [SQLFluff](https://sqlfluff.com/) — модульный настраиваемый SQL-линтер, который предупреждает о сложных функциях, ошибках синтаксиса, форматирования и компиляции. Многие флаги, которые можно передавать SQLFluff, также доступны в dbt platform CLI.

Доступны следующие команды SQLFluff:

* `lint` — Проверяет SQL-файлы линтером, принимая список файлов или данные из стандартного ввода (stdin).
* `fix` — Исправляет SQL-файлы.
* `format` — Автоматически форматирует SQL-файлы.

Чтобы проверить SQL-файлы линтером, выполните следующую команду:

```text
dbt sqlfluff lint [PATHS]... [flags]
```

Если путь не указан, dbt проверяет все SQL-файлы в текущем проекте. Чтобы проверить определенный SQL-файл или каталог, укажите в `PATHS` путь к SQL-файлу (или файлам) либо к каталогу с файлами. Чтобы проверить несколько файлов или каталогов, передайте несколько значений `PATHS`.

Чтобы просмотреть подробную информацию обо всех командах и флагах, поддерживаемых dbt, выполните команду `dbt sqlfluff -h`.

#### Особенности использования

При выполнении `dbt sqlfluff` из dbt platform CLI важно учитывать следующие особенности поведения:

* dbt считывает пользовательские настройки из файла `.sqlfluff`, если он существует.
* Для рабочих процессов непрерывной интеграции и непрерывной разработки (CI/CD) в проекте должен быть файл `dbt_cloud.yml`, а команды из каталога этого проекта dbt должны быть успешно выполнены хотя бы один раз.
* Команда SQLFluff возвращает код завершения 0, даже если при ее выполнении обнаружены нарушения в файлах. Это поведение dbt отличается от поведения SQLFluff, где нарушение, обнаруженное линтером, приводит к ненулевому коду завершения. dbt Labs планирует исправить это в одном из будущих выпусков.

## Особенности использования

dbt platform CLI в настоящее время не поддерживает относительные пути в [файле `packages.yml`](https://docs.getdbt.tech/docs/build/packages.md). Вместо этого используйте [Studio IDE](https://docs.getdbt.tech/docs/platform/studio-ide/develop-in-studio.md), который поддерживает относительные пути в этом случае.

Ниже приведён пример конфигурации [локального пакета](https://docs.getdbt.tech/docs/build/packages.md#local-packages) в файле `packages.yml`, которая не будет работать с dbt platform CLI:

```yaml
# repository_root/my_dbt_project_in_a_subdirectory/packages.yml

packages:
  - local: ../shared_macros
```

В этом примере `../shared_macros` — это относительный путь, который указывает dbt:

* `..` — перейти на один уровень вверх (в `repository_root`);
* `/shared_macros` — найти папку `shared_macros` в корневом каталоге.

Чтобы обойти это ограничение, используйте [Studio IDE](https://docs.getdbt.tech/docs/platform/studio-ide/develop-in-studio.md), который полностью поддерживает относительные пути в `packages.yml`.

## Часто задаваемые вопросы

 Как создать каталог .dbt и переместить в него файл

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

* Директория `.dbt` — это скрытая папка в корне вашей файловой системы. Она используется для хранения конфигурационных файлов dbt. Префикс `.` делает папку скрытой, поэтому по умолчанию она не отображается в Finder или File Explorer.
* Чтобы увидеть скрытые файлы и папки, нажмите Command + Shift + G на macOS или Ctrl + Shift + G на Windows. Это откроет диалог «Go to Folder», в котором можно перейти к директории `.dbt`.

### Создать каталог .dbt

1. Клонируйте репозиторий вашего проекта dbt на локальный компьютер.
2. Используйте команду `mkdir`, указав после неё имя папки, которую хотите создать.

* Если вы используете macOS, добавьте префикс `~`, чтобы создать папку `.dbt` в корне вашей файловой системы:

  * macOS: `mkdir ~/.dbt`
  * Windows: `mkdir %USERPROFILE%\.dbt`

### Переместить файл dbt\_cloud.yml

Вы можете переместить файл `dbt_cloud.yml` в директорию `.dbt`, используя команду `mv`, либо просто перетащить файл мышью в папку `.dbt`, открыв папку Downloads через диалог «Go to Folder» и воспользовавшись drag-and-drop в интерфейсе.

Чтобы переместить файл с помощью терминала, используйте команду `mv` (или `move` в Windows). Эта команда перемещает `dbt_cloud.yml` из папки `Downloads` в папку `.dbt`. Если файл `dbt_cloud.yml` находится в другом месте, скорректируйте путь соответствующим образом.

#### Mac или Linux

В командной строке используйте команду `mv`, чтобы переместить файл `dbt_cloud.yml` в директорию `.dbt`. Если вы только что скачали файл `dbt_cloud.yml` и он находится в папке Downloads, команда может выглядеть так:

```bash
mv ~/Downloads/dbt_cloud.yml ~/.dbt/dbt_cloud.yml
```

#### Windows

В командной строке используйте команду `move`. Если предположить, что файл находится в папке Downloads, команда может выглядеть следующим образом:

```bash
move %USERPROFILE%\Downloads\dbt_cloud.yml %USERPROFILE%\.dbt\dbt_cloud.yml
```

 Как отключить скачивание артефактов

По умолчанию dbt platform CLI скачивает [все артефакты](https://docs.getdbt.tech/reference/artifacts/dbt-artifacts.md) при выполнении команд dbt. Чтобы отключить скачивание этих файлов, добавьте `--download-artifacts=false` к команде, которую хотите выполнить. Это может ускорить выполнение, но способно нарушить рабочие процессы, зависящие от таких ресурсов, как [manifest](https://docs.getdbt.tech/reference/artifacts/manifest-json.md).

 Что делать при ошибке \`Session occupied\` в dbt platform CLI?

Если вы получаете ошибку `Session occupied` в dbt platform CLI или сеанс выполняется слишком долго, вы можете использовать команду `dbt invocation list` в отдельном окне терминала, чтобы просмотреть состояние активного сеанса. Это поможет разобраться в проблеме и определить аргументы, из-за которых сеанс выполняется слишком долго.

Чтобы отменить активный сеанс, используйте сочетание клавиш `Ctrl + Z`.

Подробнее о команде `dbt invocation` см. в [справочнике по команде dbt invocation](https://docs.getdbt.tech/reference/commands/invocation.md?version=2.0).

Вы также можете повторно подключиться к существующему сеансу с помощью `dbt reattach`, затем нажать `Control-C` и выбрать отмену вызова.