Установка dbt CLI

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

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

• Безопасное хранение учетных данных на платформе dbt
• Автоматическое отложенное использование (deferral) артефактов сборки из продакшн‑среды вашего Cloud‑проекта
• Более быстрые и менее затратные сборки
• Поддержка dbt Mesh (межпроектный ref)
• Существенные улучшения платформы, которые будут выпускаться в ближайшие месяцы

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

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

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

Установка dbt CLI

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

Посмотреть видеоурок с пошаговым руководством по установке.

macOS (brew)

Прежде чем начать, убедитесь, что у вас установлен Homebrew в вашем редакторе кода или терминале командной строки. Обратитесь к Часто задаваемым вопросам, если ваша операционная система сталкивается с конфликтами путей.

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

which dbt

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

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

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

pip uninstall dbt

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

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

     brew untap dbt-labs/dbt

• Затем добавьте и установите пакет Cloud CLI:

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

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

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

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

   • Обратите внимание, что вам больше не нужно выполнять команду dbt deps при запуске вашей среды. Этот шаг ранее требовался во время инициализации. Однако вы все равно должны выполнять dbt deps, если вносите изменения в ваш файл packages.yml.

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

5. После клонирования вашего репозитория настройте Cloud CLI для вашего проекта dbt. Это позволит вам запускать команды dbt, такие как dbt environment show для просмотра конфигурации dbt или dbt compile — для компиляции проекта и проверки моделей и тестов. Также вы сможете добавлять, редактировать и синхронизировать файлы с вашим репозиторием.

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

Обратитесь к Часто задаваемым вопросам, если ваша операционная система сталкивается с конфликтами путей.

1. Скачайте последнюю версию для Windows для вашей платформы с GitHub.

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

к сведению

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

1. Поместите исполняемый файл (.exe) в папку "Program Files"
2. Добавьте его в переменную среды PATH Windows
3. Сохраните его там, где это необходимо

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

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

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

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

   • Обратите внимание, что вам больше не нужно выполнять команду dbt deps при запуске вашей среды. Этот шаг ранее требовался во время инициализации. Однако вы все равно должны выполнять dbt deps, если вносите изменения в ваш файл packages.yml.

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

6. После клонирования репозитория настройте Cloud CLI для вашего проекта dbt. Это позволит запускать команды dbt, такие как dbt environment show, чтобы просматривать конфигурацию dbt, или dbt compile, чтобы скомпилировать проект и проверить модели и тесты. Вы также сможете добавлять, редактировать и синхронизировать файлы с вашим репозиторием.

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

Обратитесь к Часто задаваемым вопросам, если ваша операционная система сталкивается с конфликтами путей.

1. Скачайте последнюю версию для Linux для вашей платформы с GitHub. (Выберите файл в зависимости от архитектуры вашего процессора)

2. Извлеките бинарный файл dbt-cloud-cli в ту же папку, что и ваш проект dbt.

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

к сведению

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

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

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

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

   • Обратите внимание, что вам больше не нужно выполнять команду dbt deps при запуске вашей среды. Этот шаг ранее требовался во время инициализации. Однако вы все равно должны выполнять dbt deps, если вносите изменения в ваш файл packages.yml.

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

5. После клонирования вашего репозитория настройте Cloud CLI для вашего проекта dbt. Это позволит вам выполнять команды dbt, такие как dbt environment show, чтобы просматривать конфигурацию dbt, или dbt compile, чтобы скомпилировать проект и проверить модели и тесты. Вы также сможете добавлять, редактировать и синхронизировать файлы с вашим репозиторием.

Существующие пользователи dbt Core (pip)

Если у вас уже установлен dbt Core, Cloud CLI может конфликтовать с ним. Ниже приведены некоторые рекомендации:

• Предотвращение конфликтов
  Используйте и Cloud CLI, и dbt Core через pip, создав новое виртуальное окружение.
  
  
• Использование Cloud CLI и dbt Core с Homebrew или нативной установкой
  Если вы используете Homebrew, рассмотрите возможность задать алиас для Cloud CLI как dbt-cloud, чтобы избежать конфликтов. Подробнее см. в разделе FAQs, если в вашей операционной системе возникают конфликты путей.
  
  
• Возврат к dbt Core с Cloud CLI
  Если вы уже установили Cloud CLI и вам нужно вернуться к dbt Core:
  
  • Удалите Cloud CLI с помощью команды: pip uninstall dbt
  • Переустановите dbt Core с помощью следующей команды, заменив adapter_name на соответствующее имя адаптера:

    python -m pip install dbt-adapter_name --force-reinstall
    Например, если я использовал Snowflake в качестве адаптера, я бы выполнил: python -m pip install dbt-snowflake --force-reinstall

---

Перед установкой Cloud CLI убедитесь, что у вас установлен Python, а также настроено виртуальное окружение venv или pyenv. Если у вас уже есть сконфигурированное Python‑окружение, вы можете сразу перейти к шагу установки через pip.

Установка виртуальной среды

Мы рекомендуем использовать виртуальные среды (venv) для изоляции cloud-cli.

1. Создайте новую виртуальную среду с именем "dbt-cloud" с помощью этой команды:

   python3 -m venv dbt-cloud

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

   • Для Mac и Linux используйте: source dbt-cloud/bin/activate
     
   • Для Windows используйте: dbt-env\Scripts\activate

3. (Только для Mac и Linux) Создайте псевдоним для активации вашей среды dbt с каждым новым окном или сеансом оболочки. Вы можете добавить следующее в файл конфигурации вашей оболочки (например, $HOME/.bashrc, $HOME/.zshrc), заменив <PATH_TO_VIRTUAL_ENV_CONFIG> на путь к вашей конфигурации виртуальной среды:

   alias env_dbt='source <PATH_TO_VIRTUAL_ENV_CONFIG>/bin/activate'

Установка dbt CLI через pip

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

dbt --version

2. Убедитесь, что вы находитесь в своём виртуальном окружении, и выполните следующую команду, чтобы установить CLI dbt:

pip install dbt --no-cache-dir

Если возникают проблемы с установкой, выполнение команды с аргументом --force-reinstall может помочь:

pip install dbt --no-cache-dir --force-reinstall

3. (Необязательно) Чтобы вернуться к dbt Core, сначала удалите и dbt CLI, и dbt Core. Затем переустановите dbt Core.

pip uninstall dbt-core dbt
pip install dbt-adapter_name --force-reinstall

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

5. После клонирования вашего репозитория настройте Cloud CLI для вашего проекта dbt. Это позволит вам запускать команды dbt, такие как dbt environment show, чтобы просматривать конфигурацию dbt, или dbt compile, чтобы скомпилировать проект и проверить модели и тесты. Вы также можете добавлять, редактировать и синхронизировать файлы с вашим репозиторием.

Обновление dbt CLI

Следующие инструкции объясняют, как обновить Cloud CLI до последней версии в зависимости от вашей операционной системы.

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

macOS (brew)

Чтобы обновить Cloud CLI, выполните команду brew update, а затем brew upgrade dbt.

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

Чтобы обновить, следуйте тому же процессу, описанному в Windows, и замените существующий исполняемый файл dbt.exe на новый.

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

Чтобы обновить, следуйте тому же процессу, описанному в Linux, и замените существующий исполняемый файл dbt на новый.

Существующие пользователи dbt Core (pip)

Чтобы обновить:

• Убедитесь, что вы находитесь в вашей виртуальной среде
• Выполните python -m pip install --upgrade dbt.

К рассмотрению

Cloud CLI в настоящее время не поддерживает относительные пути в файле packages.yml. Вместо этого используйте Studio IDE, который поддерживает относительные пути в этом сценарии.

Ниже приведён пример конфигурации локального пакета в packages.yml, которая не будет работать с Cloud CLI:

# 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, который полностью поддерживает относительные пути в packages.yml.

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

 В чем разница между dbt CLI и dbt Core?

Cloud CLI и dbt Core, проект с открытым исходным кодом, — это оба инструмента командной строки, которые позволяют выполнять команды dbt.

Ключевое отличие заключается в том, что Cloud CLI адаптирован под инфраструктуру dbt и интегрирован со всеми его возможностями.

 Как использовать одновременно dbt CLI и dbt Core?

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

Если у вас локально установлен dbt Core, вы можете сделать одно из следующих действий:

1. Установить с помощью команды pip3 install dbt pip.
2. Установить нативно, убедившись, что вы либо деактивировали виртуальное окружение, содержащее dbt Core, либо создали алиас для Cloud CLI.
3. (Для опытных пользователей) Установить нативно, но изменить переменную окружения $PATH так, чтобы она корректно указывала на бинарный файл Cloud CLI, и тем самым использовать Cloud CLI и dbt Core одновременно.

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

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

Чтобы создать псевдоним для Cloud CLI:

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

2. Добавьте алиас, который указывает на бинарный файл Cloud CLI. Например:
   alias dbt-cloud="path_to_dbt_cloud_cli_binary

   Замените path_to_dbt_cloud_cli_binary на фактический путь к бинарному файлу Cloud CLI, который равен /opt/homebrew/bin/dbt.
   С этим алиасом вы сможете использовать команду dbt-cloud для вызова Cloud CLI.
   

3. Сохраните файл, а затем либо перезапустите вашу оболочку, либо выполните source на файле профиля, чтобы применить изменения. Как пример, в bash вы бы выполнили: source ~/.bashrc
   

4. Проверьте и используйте алиас для запуска команд:
   

   • Чтобы запустить Cloud CLI, используйте команду dbt-cloud: dbt-cloud command_name. Замените command_name на конкретную команду dbt, которую вы хотите выполнить.
     
   • Чтобы запустить dbt Core, используйте команду dbt: dbt command_name. Замените command_name на конкретную команду dbt, которую вы хотите выполнить.
     

Этот алиас позволит вам использовать команду dbt-cloud для вызова Cloud CLI, при этом dbt Core будет установлен нативно.

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

Cloud CLI позволяет выполнять только одну команду, которая записывает данные в хранилище данных, в каждый момент времени. Если вы попытаетесь запустить несколько команд записи одновременно (например, dbt run и dbt build), вы столкнётесь с ошибкой stuck session. Чтобы решить эту проблему, отмените конкретный запуск, передав его ID в команду отмены. Подробнее см. в разделе parallel execution.

Я получаю ошибку «Session occupied» в dbt CLI

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

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

Подробнее о команде dbt invocation см. в справочнике команд dbt invocation.

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

Нашли ошибку?

Создать GitHub Issue