Configure and use the dbt CLI

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

• Безопасное хранение учетных данных на платформе dbt.
• Автоматическое использование defer для артефактов сборки из production-окружения вашего Cloud‑проекта.
• Более быстрые и экономичные сборки.
• Поддержка Mesh (cross-project ref) и многое другое.

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

• Вам необходимо настроить проект в dbt.
  • Примечание — Если вы используете Cloud CLI, вы можете подключиться к вашей платформе данных напрямую в интерфейсе dbt и вам не потребуется файл profiles.yml.
• Для этого проекта у вас должны быть настроены ваши учётные данные для персональной разработки. CLI dbt будет использовать эти учётные данные, безопасно хранящиеся в dbt, для взаимодействия с вашей платформой данных.
• Вы должны использовать dbt версии 1.5 или выше. Инструкции по обновлению см. в разделе версии dbt.

Настройка dbt CLI

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

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

2. В главном меню перейдите в раздел CLI.

3. В разделе Configure Cloud authentication нажмите Download CLI configuration file, чтобы скачать файл учётных данных dbt_cloud.yml.

   URL-адреса регионов для загрузки учётных данных

   Вы также можете скачать учётные данные по ссылкам, соответствующим вашему региону:

   • Северная Америка: https://cloud.getdbt.com/cloud-cli
   • EMEA: https://emea.dbt.com/cloud-cli
   • APAC: https://au.dbt.com/cloud-cli
   • Североамериканская ячейка 1: https:/ACCOUNT_PREFIX.us1.dbt.com/cloud-cli
   • Однопользовательский: https://YOUR_ACCESS_URL/cloud-cli

4. Сохраните файл dbt_cloud.yml в директории .dbt, в которой хранится конфигурация Cloud CLI.

   • Mac или Linux: ~/.dbt/dbt_cloud.yml
   • Windows: C:\Users\yourusername\.dbt\dbt_cloud.yml

   Файл конфигурации выглядит следующим образом:

   version: "1"
   context:
     active-project: "<project id from the list below>"
     active-host: "<active host from the list>"
     defer-env-id: "<optional defer environment id>"
   projects:
     - project-name: "<project-name>"
       project-id: "<project-id>"
       account-name: "<account-name>"
       account-id: "<account-id>"
       account-host: "<account-host>" # for example, "cloud.getdbt.com"
       token-name: "<pat-name>"
       token-value: "<pat-value>"
   
     - project-name: "<project-name>"
       project-id: "<project-id>"
       account-name: "<account-name>"
       account-id: "<account-id>"
       account-host: "<account-host>" # for example, "cloud.getdbt.com"
       token-name: "<pat-name>"
       token-value: "<pat-value>"  

   Храните файл конфигурации в безопасном месте, так как он содержит API‑ключи. Ознакомьтесь с разделом FAQs, чтобы узнать, как создать директорию .dbt и переместить файл dbt_cloud.yml. Если у вас есть несколько копий файла и его имя содержит числовое дополнение (например, dbt_cloud(2).yml), удалите лишний текст из имени файла.

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

   cd ~/dbt-projects/jaffle_shop

6. В файле dbt_project.yml убедитесь, что у вас есть (или добавлен) раздел dbt-cloud с полем project-id. Поле project-id содержит идентификатор проекта dbt, который вы хотите использовать.

   # dbt_project.yml
   name:
   version:
   # Ваши конфигурации проекта...
   
   dbt-cloud: 
       project-id: PROJECT_ID

• Чтобы найти идентификатор проекта, выберите Develop в навигационном меню dbt. Вы можете использовать URL, чтобы определить идентификатор проекта. Например, в https://YOUR_ACCESS_URL/develop/26228/projects/123456 идентификатор проекта — 123456.

7. Теперь вы должны иметь возможность использовать Cloud CLI и запускать команды dbt, такие как dbt environment show, чтобы просмотреть сведения о конфигурации вашего dbt, или dbt compile, чтобы скомпилировать модели в вашем dbt‑проекте.

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

Установка переменных окружения

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

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

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

Cloud CLI использует тот же набор dbt commands и MetricFlow commands, что и dbt Core, для выполнения переданных вами команд. Например, вы можете использовать команду dbt environment, чтобы просмотреть детали конфигурации вашего dbt. С помощью Cloud CLI вы можете:

• Запускать несколько вызовов параллельно и обеспечивать безопасный параллелизм, который в настоящее время не гарантируется в dbt-core.
• Автоматически откладывать (defer) артефакты сборки в production‑окружение вашего Cloud‑проекта.
• Использовать project dependencies, которые позволяют зависеть от другого проекта через сервис метаданных в dbt.
  • Зависимости между проектами мгновенно подключаются и ссылаются (через ref) на публичные модели, определенные в других проектах. Вам не нужно самостоятельно выполнять или анализировать эти upstream‑модели — вместо этого вы используете их как API, возвращающее набор данных.

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

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

• dbt --help: Показывает доступные команды для dbt
  
• dbt run --help: Показывает доступные флаги для команды run

Проверка SQL-файлов (linting)

Из CLI dbt вы можете вызвать SQLFluff — модульный и настраиваемый SQL-линтер, который предупреждает о сложных функциях, проблемах с синтаксисом, форматированием и ошибках компиляции. Многие из тех же флагов, которые можно передать в SQLFluff напрямую, также доступны при использовании CLI dbt.

Доступные команды SQLFluff:

• lint — Линтинг SQL файлов, передавая список файлов или из стандартного ввода (stdin).
• fix — Исправление SQL файлов.
• format — Автоформатирование SQL файлов.

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

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

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

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

Соображения

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

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

Важные моменты

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.

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

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

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

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

Create a .dbt directory

1. Клонируйте репозиторий вашего dbt‑проекта локально.

2. Используйте команду mkdir, указав имя папки, которую нужно создать.

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

   mkdir ~/.dbt # macOS
   mkdir %USERPROFILE%\.dbt # Windows

Move the dbt_cloud.yml file

Вы можете переместить файл 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, команда может выглядеть так:

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

Windows

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

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

 Как пропустить загрузку артефактов

По умолчанию все артефакты загружаются при выполнении команд dbt из Cloud CLI. Чтобы пропустить загрузку этих файлов, добавьте --download-artifacts=false к команде, которую вы запускаете. Это может помочь улучшить производительность выполнения, но может нарушить рабочие процессы, которые зависят от таких артефактов, как manifest.

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

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

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

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

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

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

Создать GitHub Issue