# Установка CLI платформы dbt

Платформа dbt

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

Совместимость CLI

dbt platform CLI — это инструмент dbt platform, доступный пользователям на любом [тарифном плане](https://www.getdbt.com/pricing). Он предназначен исключительно для работы с dbt platform и может конфликтовать с локальными установками CLI dbt v1 или dbt v2. Подробнее см. в разделе [FAQs](#faqs).

Команды dbt выполняются в инфраструктуре платформы, что обеспечивает следующие преимущества:

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

[![Схема взаимодействия CLI платформы dbt с инфраструктурой dbt для выполнения команд dbt из локальной командной строки.](/img/docs/dbt-platform/dbt-cli-overview.png?v=2 "Схема взаимодействия CLI платформы dbt с инфраструктурой dbt для выполнения команд dbt из локальной командной строки.")](#)Схема взаимодействия CLI платформы dbt с инфраструктурой dbt для выполнения команд dbt из локальной командной строки.

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

dbt platform CLI доступен во всех [регионах развертывания](https://docs.getdbt.tech/docs/platform/about-platform/access-regions-ip-addresses.md) как для мультитенантных, так и для однотенантных учетных записей.

* Если вы установили CLI dbt v1 в виртуальной среде, деактивируйте ее или создайте псевдоним для CLI платформы, прежде чем выполнять команды CLI платформы.
* Если вы установили dbt локально, создайте псевдоним для CLI платформы, прежде чем выполнять команды CLI платформы.

Подробнее об управлении несколькими инструментами dbt platform CLI и создании псевдонима см. в разделе [FAQs](#faqs).

Используете CLI dbt platform для гибридной разработки с dbt v2?

См. руководство [Гибридная разработка с dbt platform и dbt v2](https://docs.getdbt.tech/guides/dbt-platform-local-workflow.md), чтобы синхронизировать учетные данные, переменные окружения и версии dbt v2 между локальным CLI и dbt platform.

## Установка CLI платформы dbt

Вы можете установить dbt platform CLI через командную строку одним из следующих способов:

### macOS (brew)

Перед началом убедитесь, что [Homebrew установлен](http://brew.sh/) и доступен в вашем редакторе кода или терминале командной строки. Если в вашей операционной системе возникают конфликты путей, см. раздел [FAQs](#faqs).

1. Убедитесь, что dbt еще не установлен, выполнив следующую команду:

```bash
which dbt
```

Если выводится `dbt not found`, это подтверждает, что он не установлен.

Выполните `pip uninstall dbt`, чтобы удалить dbt v1

Если вы установили dbt v1 глобально каким-либо другим способом, удалите его, прежде чем продолжить:

```bash
pip uninstall dbt
```

2. Установите dbt platform CLI с помощью Homebrew:

   * Сначала удалите из Homebrew tap `dbt-labs` — отдельный репозиторий пакетов. Это предотвратит установку пакетов из этого репозитория через Homebrew:

     ```bash
     brew untap dbt-labs/dbt
     ```

   * Затем добавьте и установите dbt platform CLI как пакет:

     ```bash
     brew tap dbt-labs/dbt-cli
     brew install dbt
     ```

     Если у вас подключено несколько tap-репозиториев, используйте `brew install dbt-labs/dbt-cli/dbt`.

3. Проверьте установку, выполнив `dbt --help` в командной строке. Если вы видите следующий вывод, установка выполнена правильно:

   ```bash
   The dbt CLI - an ELT tool for running SQL transformations and data models in dbt...
   ```

   Если вы не видите этот вывод, убедитесь, что вы деактивировали pyenv или venv и что у вас нет глобально установленной версии dbt.

   * Обратите внимание: при запуске среды больше не нужно выполнять команду `dbt deps`. Раньше этот шаг требовался для инициализации. Однако при любых изменениях в файле `packages.yml` по-прежнему необходимо выполнять `dbt deps`.

4. Клонируйте репозиторий на локальный компьютер с помощью `git clone`. Например, чтобы клонировать репозиторий GitHub по HTTPS, выполните `git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY`.

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

### Windows (нативный исполняемый файл)

Если в вашей операционной системе возникают конфликты путей, см. раздел [FAQs](#faqs).

1. Загрузите последнюю версию для Windows, соответствующую вашей платформе, с [GitHub](https://github.com/dbt-labs/dbt-cli/releases).

2. Извлеките исполняемый файл `dbt.exe` в ту же папку, где находится ваш проект dbt.

к сведению

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

1. Поместите исполняемый файл (`.exe`) в папку "Program Files"
2. [Добавьте его в переменную окружения PATH в Windows](https://medium.com/@kevinmarkvi/how-to-add-executables-to-your-path-in-windows-5ffa4ce61a53)
3. Сохраните его там, где необходимо

Обратите внимание: если вы используете VS Code, его необходимо перезапустить, чтобы изменения переменных окружения вступили в силу.

4. Проверьте установку, выполнив `./dbt --help` в командной строке. Если вы видите следующий вывод, установка выполнена правильно:

   ```bash
   The dbt CLI - an ELT tool for running SQL transformations and data models in dbt...
   ```

   Если вы не видите этот вывод, убедитесь, что вы деактивировали pyenv или venv и что у вас нет глобально установленной версии dbt.

   * Обратите внимание: при запуске среды больше не нужно выполнять команду `dbt deps`. Раньше этот шаг требовался для инициализации. Однако при любых изменениях в файле `packages.yml` по-прежнему необходимо выполнять `dbt deps`.

5. Клонируйте репозиторий на локальный компьютер с помощью `git clone`. Например, чтобы клонировать репозиторий GitHub по HTTPS, выполните `git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY`.

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

### Linux (нативный исполняемый файл)

Если в вашей операционной системе возникают конфликты путей, см. раздел [FAQs](#faqs).

1. Загрузите последнюю версию для Linux, соответствующую вашей платформе, с [GitHub](https://github.com/dbt-labs/dbt-cli/releases). (Выберите файл в соответствии с архитектурой процессора)

2. Извлеките бинарный файл `dbt-cli` в ту же папку, где находится ваш проект dbt.

```bash
tar -xf dbt_0.29.9_linux_amd64.tar.gz
./dbt --version
```

к сведению

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

3. Проверьте установку, выполнив `./dbt --help` в командной строке. Если вы видите следующий вывод, установка выполнена правильно:

   ```bash
   The dbt CLI - an ELT tool for running SQL transformations and data models in dbt...
   ```

   Если вы не видите этот вывод, убедитесь, что вы деактивировали pyenv или venv и что у вас нет глобально установленной версии dbt.

   * Обратите внимание: при запуске среды больше не нужно выполнять команду `dbt deps`. Раньше этот шаг требовался для инициализации. Однако при любых изменениях в файле `packages.yml` по-прежнему необходимо выполнять `dbt deps`.

4. Клонируйте репозиторий на локальный компьютер с помощью `git clone`. Например, чтобы клонировать репозиторий GitHub по HTTPS, выполните `git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY`.

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

## Обновление CLI платформы dbt

Ниже приведены инструкции по обновлению dbt platform CLI до последней версии в зависимости от вашей операционной системы.

### macOS (brew)

Чтобы обновить dbt platform CLI, выполните `brew update`, а затем `brew upgrade dbt`.

### Windows (исполняемый файл)

Для обновления следуйте [инструкциям по установке для Windows](https://docs.getdbt.tech/docs/platform/dbt-cli-installation.md?install=windows#install-dbt-cloud-cli) и замените существующий исполняемый файл `dbt.exe` новым.

### Linux (исполняемый файл)

Для обновления следуйте [инструкциям по установке для Linux](https://docs.getdbt.tech/docs/platform/dbt-cli-installation.md?install=linux#install-dbt-cloud-cli) и замените существующий исполняемый файл `dbt` новым.

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

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

## FAQs

 В чем разница между CLI платформы dbt и dbt?

dbt platform CLI и [dbt](https://github.com/dbt-labs/dbt), проект с открытым исходным кодом, — это инструменты командной строки, позволяющие выполнять команды dbt.

Ключевое отличие заключается в том, что dbt platform CLI разработан специально для инфраструктуры dbt platform и интегрирован со всеми ее [возможностями](https://docs.getdbt.com/docs/platform/about-platform/dbt-platform-features).

 Как использовать и CLI платформы dbt, и dbt?

Для совместимости и dbt platform CLI, и dbt запускаются командой `dbt`. Это может приводить к конфликтам путей, если операционная система выбирает один из инструментов на основе настроек переменной окружения $PATH.

Если у вас локально установлен dbt, выберите один из вариантов:

1. Выполните нативную установку, предварительно деактивировав виртуальную среду с dbt v1 или создав псевдоним для dbt platform CLI.
2. (Для опытных пользователей) Выполните нативную установку, но измените переменную окружения $PATH так, чтобы она корректно указывала на бинарный файл dbt platform CLI и позволяла использовать dbt platform CLI и dbt вместе.

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

 Как создать псевдоним?

Чтобы создать псевдоним для dbt platform CLI:<br />

1. Откройте файл конфигурации профиля вашей командной оболочки. В зависимости от оболочки и системы это может быть `~/.bashrc`, `~/.bash_profile`, `~/.zshrc` или другой файл.<br />

2. Добавьте псевдоним, указывающий на бинарный файл dbt platform CLI. Например: `alias dbt-cli="path_to_dbt_cli_binary"`

   Замените `path_to_dbt_cli_binary` фактическим путем к бинарному файлу dbt platform CLI — `/opt/homebrew/bin/dbt`. С этим псевдонимом вы сможете использовать команду `dbt-cli` для запуска dbt platform CLI.<br />

3. Сохраните файл, а затем перезапустите командную оболочку или выполните `source` для файла профиля, чтобы применить изменения. Например, в bash нужно выполнить: `source ~/.bashrc`<br />

4. Проверьте псевдоним и используйте его для выполнения команд:<br />

   * Для запуска dbt platform CLI используйте команду `dbt-cli`: `dbt-cli command_name`. Замените 'command\_name' конкретной командой dbt, которую хотите выполнить.
     <br />
   * Для запуска dbt используйте команду `dbt`: `dbt command_name`. Замените 'command\_name' конкретной командой dbt, которую хотите выполнить.
     <br />

После этого вы сможете использовать команду `dbt-cli` для запуска dbt platform CLI, сохраняя нативную установку dbt.

 Почему при попытке выполнить новую команду возникает ошибка \`Stuck session\`?

dbt platform CLI позволяет одновременно выполнять только одну команду, записывающую данные в хранилище данных. Если вы попытаетесь одновременно выполнить несколько команд записи (например, `dbt run` и `dbt build`), возникнет ошибка `stuck session`. Чтобы устранить ее, отмените конкретный запуск, передав его идентификатор команде отмены. Подробнее см. в разделе [Параллельное выполнение](https://docs.getdbt.tech/reference/dbt-commands.md#parallel-execution).

 Что делать, если в CLI платформы dbt возникает ошибка \`Session occupied\`?

Если вы получаете ошибку `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` и выбрать отмену вызова.