Задания непрерывной интеграции в dbt Cloud

Вы можете настроить непрерывную интеграцию (CI) для запуска, когда кто-то открывает новый pull request (PR) в вашем Git-репозитории dbt. Запуская и тестируя только измененные модели, dbt Cloud обеспечивает максимальную эффективность и экономию ресурсов на вашей платформе данных.

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

• У вас есть аккаунт dbt Cloud.
• Функции CI:
  • Для использования функций параллельных проверок CI и умной отмены устаревших сборок ваш аккаунт dbt Cloud должен быть на Team или Enterprise плане.
  • SQL linting доступен на релизных треках dbt Cloud и для аккаунтов dbt Cloud Team или Enterprise. Вы должны иметь настроенный SQLFluff в вашем проекте.
• Расширенные функции CI:
  • Для использования функции сравнения изменений ваш аккаунт dbt Cloud должен быть на Enterprise плане и иметь включенные расширенные функции CI. Попросите вашего администратора dbt Cloud включить эту функцию для вас. После включения опция dbt compare станет доступной в настройках CI задания.
• Настройте подключение с вашим Git-провайдером. Эта интеграция позволяет dbt Cloud запускать задания от вашего имени для их триггера.
  • Если вы используете нативную интеграцию с GitLab, вам нужен платный или самохостинг аккаунт, который поддерживает вебхуки GitLab и токены доступа к проекту. Если вы используете GitLab Free, запросы на слияние будут запускать задания CI, но обновления статуса задания CI (успех или неудача задания) не будут отправляться обратно в GitLab.

Настройка CI заданий

dbt Labs рекомендует создавать CI задания в отдельной среде развертывания dbt Cloud, которая подключена к промежуточной базе данных. Наличие отдельной среды, посвященной CI, обеспечит лучшую изоляцию между временными сборками схем CI и вашими производственными сборками данных. Кроме того, иногда командам нужно, чтобы их CI задания запускались, когда PR создается в ветке, отличной от основной. Если ваша команда поддерживает промежуточную ветку как часть процесса выпуска, наличие отдельной среды позволит вам установить пользовательскую ветку, и, соответственно, CI задание в этой выделенной среде будет запускаться только при создании PR в указанную пользовательскую ветку. Чтобы узнать больше, обратитесь к Начало работы с тестами CI.

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

1. На странице вашей среды развертывания нажмите Создать задание > Задание непрерывной интеграции, чтобы создать новое CI задание.

2. Параметры в разделе Настройки задания:

   • Имя задания — Укажите имя для этого CI задания.
   • Описание — Предоставьте описание CI задания.
   • Среда — По умолчанию будет установлена среда, из которой вы создали CI задание. Используйте выпадающий список, чтобы изменить настройку по умолчанию.

3. Параметры в разделе Git триггер:

   • Запускается pull запросами — По умолчанию включено. Каждый раз, когда разработчик открывает pull запрос или отправляет коммит в существующий pull запрос, это задание будет запускаться.
     • Запуск на черновом pull запросе — Включите эту опцию, если вы хотите также запускать задание каждый раз, когда разработчик открывает черновой pull запрос или отправляет коммит в этот черновой pull запрос.

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

   • Команды — По умолчанию включает команду dbt build --select state:modified+. Это информирует dbt Cloud о необходимости строить только новые или измененные модели и их зависимые элементы. Важно, что сравнение состояния может происходить только при выборе отложенной среды для сравнения состояния. Нажмите Добавить команду, чтобы добавить больше команд, которые вы хотите вызвать при запуске этого задания.

   • Linting — Включите эту опцию, чтобы dbt проверил SQL файлы в вашем проекте как первый шаг в dbt run. Если эта проверка столкнется с ошибкой, dbt может либо Остановить выполнение при ошибке, либо Продолжить выполнение при ошибке.

   • dbt compareenterprise — Включите эту опцию, чтобы сравнить последнее примененное состояние производственной среды (если оно существует) с последними изменениями из pull запроса и определить, в чем заключаются эти различия. Чтобы включить сравнение на уровне записей и анализ первичного ключа, вы должны добавить ограничение первичного ключа или тест уникальности. В противном случае вы получите сообщение об ошибке "Отсутствует первичный ключ" в dbt Cloud.

     Чтобы просмотреть отчет о сравнении, перейдите на вкладку Сравнение в деталях выполнения задания. Краткое содержание отчета также доступно из pull запроса в вашем Git провайдере (см. пример отчета CI).

     Совет по оптимизации

     Когда вы включаете флажок dbt compare, вы можете настроить команду сравнения для оптимизации вашего CI задания. Например, если у вас есть большие модели, которые занимают много времени для сравнения, вы можете исключить их, чтобы ускорить процесс, используя флаг --exclude. Обратитесь к пользовательским командам сравнения изменений для получения более подробной информации.

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

   • Сравнение изменений с окружением (Отложение) — По умолчанию установлено на Производственное окружение, если вы его создали. Эта опция позволяет dbt Cloud проверять состояние кода в PR по сравнению с кодом, работающим в отложенной среде, чтобы проверять только измененный код, вместо того чтобы строить полную таблицу или весь DAG.

     к сведению

     Более старые версии dbt Cloud позволяют откладывать только на конкретное задание, а не на окружение. Отложение на задание сравнивает состояние с кодом проекта, который был выполнен в последнем успешном запуске отложенного задания. Отложение на окружение более эффективно, так как dbt Cloud будет сравнивать с представлением проекта (которое хранится в manifest.json) последнего успешного выполнения задания развертывания, выполненного в отложенной среде. Учитывая все задания развертывания, которые выполняются в отложенной среде, dbt Cloud получит более точное, актуальное состояние представления проекта.

   • Тайм-аут выполнения — Отмените CI задание, если время выполнения превышает значение тайм-аута. Вы можете использовать эту опцию, чтобы гарантировать, что проверка CI не потребляет слишком много ресурсов вашего хранилища. Если вы включите опцию dbt compare, значение тайм-аута по умолчанию будет 3600 (один час), чтобы предотвратить длительные сравнения.

5. (необязательно) Параметры в разделе Расширенные настройки:

   • Переменные окружения — Определите переменные окружения, чтобы настроить поведение вашего проекта при запуске этого CI задания. Вы можете указать, что CI задание выполняется в Промежуточной или CI среде, установив переменную окружения и изменив код вашего проекта для различного поведения в зависимости от контекста. Обычно команды обрабатывают только подмножество данных для CI запусков, используя переменные окружения для ветвления логики в своем коде проекта dbt.
   • Имя цели — Определите имя цели. Подобно Переменным окружения, эта опция позволяет настроить поведение проекта. Вы можете использовать эту опцию, чтобы указать, что CI задание выполняется в Промежуточной или CI среде, установив имя цели и изменив код вашего проекта для различного поведения в зависимости от контекста.
   • Версия dbt — По умолчанию установлено наследование версии dbt из окружения. dbt Labs настоятельно рекомендует не изменять настройку по умолчанию. Эта опция изменения версии на уровне задания полезна только при обновлении проекта до следующей версии dbt; в противном случае несоответствие версий между окружением и заданием может привести к запутанному поведению.
   • Потоки — По умолчанию установлено 4 потока. Увеличьте количество потоков, чтобы увеличить параллелизм выполнения моделей.
   • Генерация документации при запуске — Включите это, если вы хотите генерировать документацию проекта при запуске этого задания. Это отключено по умолчанию, так как тестирование генерации документации при каждом проверке CI не является рекомендуемой практикой.
   • Запуск свежести источников — Включите эту опцию, чтобы вызвать команду dbt source freshness перед запуском этого CI задания. Обратитесь к Свежесть источников для получения более подробной информации.
   Пример страницы CI задания в интерфейсе dbt Cloud

Пример проверки CI в pull запросе

Ниже приведен пример проверки CI в pull запросе GitHub. Зеленая галочка означает, что сборка и тесты dbt прошли успешно. Нажатие на раздел dbt Cloud перенаправит вас на соответствующий запуск CI в dbt Cloud.

Пример проверки CI в pull запросе GitHub

Пример отчета CI в pull запросе preview

Ниже приведен пример отчета CI в pull запросе GitHub, который отображается, когда для CI задания включена опция dbt compare. Он показывает краткое содержание моделей, измененных в pull запросе.

Пример комментария отчета CI в pull запросе GitHub

Запуск CI задания с помощью API

Если вы не используете нативную Git интеграцию dbt Cloud с GitHub, GitLab или Azure DevOps, вы можете использовать Административный API для запуска CI задания. Однако dbt Cloud не будет автоматически удалять временную схему за вас. Это связано с тем, что автоматическое удаление зависит от входящих вебхуков от Git провайдеров, которые доступны только через нативные интеграции.

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

• У вас есть аккаунт dbt Cloud.
• Для функций Параллельных проверок CI и Умной отмены устаревших сборок ваш аккаунт dbt Cloud должен быть на Team или Enterprise плане.

1. Настройте CI задание с помощью Create Job API endpoint, используя "job_type": ci или из интерфейса dbt Cloud.
2. Вызовите Trigger Job Run API endpoint, чтобы запустить CI задание. Вы должны включить оба этих поля в полезную нагрузку:

   • Укажите ID pull запроса (PR), используя одно из этих полей:

     • github_pull_request_id
     • gitlab_merge_request_id
     • azure_devops_pull_request_id
     • non_native_pull_request_id (например, BitBucket)

   • Укажите git_sha или git_branch, чтобы нацелиться на правильный коммит или ветку для запуска задания.

Семантические проверки в CI teamenterprise

Автоматически тестируйте ваши семантические узлы (метрики, семантические модели и сохраненные запросы) во время обзоров кода, добавляя проверки валидации хранилища в ваше CI задание, гарантируя, что любые изменения кода в dbt моделях не нарушают эти метрики.

Для этого добавьте команду dbt sl validate --select state:modified+ в CI задание. Это обеспечивает валидацию измененных семантических узлов и их зависимостей.

Семантические проверки в рабочем процессе CI

Преимущества

• Тестирование семантических узлов в CI задании поддерживает отложение и выбор семантических узлов.
• Это позволяет выявлять проблемы на ранних этапах процесса разработки и предоставлять высококачественные данные вашим конечным пользователям.
• Семантическая валидация выполняет объяснительный запрос в хранилище данных для семантических узлов, чтобы убедиться, что сгенерированный SQL будет выполнен.
• Для семантических узлов и моделей, которые не являются зависимыми от измененных моделей, dbt Cloud откладывает на производственные модели.

Настройка семантических проверок в вашем CI задании

Чтобы узнать, как это настроить, обратитесь к следующим шагам:

1. Перейдите на страницу Настройки задания и нажмите Редактировать.
2. Добавьте команду dbt sl validate --select state:modified+ в раздел Команды в Настройках выполнения. Команда использует выбор состояния и отложение для выполнения валидации на любых семантических узлах, зависимых от изменений модели. Чтобы сократить время выполнения задания, мы рекомендуем запускать CI только на измененных семантических моделях.
3. Нажмите Сохранить, чтобы сохранить изменения.

Существуют дополнительные команды и варианты использования, описанные в следующем разделе, такие как валидация всех семантических узлов, валидация конкретных семантических узлов и так далее.

Проверка семантических узлов, зависимых от изменений модели, в вашем CI задании.

Варианты использования

Используйте или комбинируйте различные селекторы или команды для проверки семантических узлов в вашем CI задании. Семантические проверки в CI поддерживают следующие варианты использования:

 Семантические узлы, зависимые от изменений модели (рекомендуется)

Чтобы проверить семантические узлы, которые зависят от изменения модели, добавьте две команды в раздел Настройки выполнения вашего задания:

dbt build --select state:modified+
dbt sl validate --select state:modified+

• Первая команда строит измененные модели.
• Вторая команда проверяет семантические узлы, зависимые от измененных моделей.

Перед выполнением семантических проверок dbt Cloud должен построить измененные модели. Этот процесс гарантирует, что зависимые семантические узлы проверяются с использованием схемы CI через API dbt Semantic Layer.

Для семантических узлов и моделей, которые не являются зависимыми от измененных моделей, dbt Cloud откладывает на производственные модели.

Проверка семантических узлов, зависимых от изменений модели, в вашем CI задании.

 Семантические узлы, которые изменены или затронуты зависимыми измененными узлами.

Чтобы проверить только измененные семантические узлы, используйте следующую команду (с выбором состояния):

dbt sl validate --select state:modified+

Используйте выбор состояния для проверки измененных моделей определения метрик в вашем CI задании.

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

 Выбор конкретных семантических узлов

Используйте синтаксис селектора, чтобы выбрать конкретный семантический узел(ы), который вы хотите проверить:

dbt sl validate --select metric:revenue

Используйте выбор состояния для проверки измененных моделей определения метрик в вашем CI задании.

В этом примере CI задание проверит выбранный семантический узел metric:revenue. Чтобы выбрать несколько семантических узлов, используйте синтаксис селектора: dbt sl validate --select metric:revenue metric:customers.

Если вы не укажете селектор, dbt Cloud проверит все семантические узлы в вашем проекте.

 Выбор всех семантических узлов

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

dbt sl validate

Проверка всех семантических узлов в вашем CI задании, добавив команду: 'dbt sl validate' в настройки выполнения вашего задания.

Устранение неполадок

Невозможно запустить задачу CI с GitLab

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

Если вы не можете запустить задачу CI, это обычно указывает на то, что регистрация вебхука отсутствует или неверна.

Чтобы решить эту проблему, перейдите в настройки репозитория в GitLab и просмотрите регистрации вебхуков, перейдя в GitLab --> Settings --> Webhooks.

Некоторые моменты, которые стоит проверить:

• Регистрация вебхука включена в GitLab.
• Регистрация вебхука настроена с правильным URL и секретом.

Если проблема все еще сохраняется, свяжитесь с нашей службой поддержки по адресу support@getdbt.com, и мы будем рады помочь!

 CI-задания иногда не запускаются при открытии PR с использованием интеграции Azure DevOps (ADO)

dbt Cloud не запускает выполнение CI-задания, если последний коммит в pull или merge запросе уже инициировал выполнение этого задания. Однако некоторые провайдеры (например, GitHub) будут учитывать результат существующего выполнения для нескольких pull/merge запросов.

Сценарии, в которых dbt Cloud не запускает CI-задание с Azure DevOps:

1. Повторное использование ветки в новом PR

   • Если вы отменяете предыдущий PR (PR 1), который запустил CI-задание для той же ветки (feature-123), слияние которой предполагалось в main, и затем открываете новый PR (PR 2) с той же веткой, сливаемой в main — dbt Cloud не запустит новое CI-задание для PR 2.

2. Повторное использование одного и того же коммита

   • Если вы создаёте новый PR (PR 2) с тем же коммитом (#4818ceb), что и предыдущий PR (PR 1), который инициировал CI-задание — dbt Cloud не запустит новое CI-задание для PR 2.

 Временные схемы не удаляются

Если ваши временные схемы не удаляются после слияния или закрытия PR, это обычно указывает на одну из следующих проблем:

• Вы переопределили макрос generate_schema_name, и он не использует dbt_cloud_pr_ в качестве префикса.

Чтобы решить эту проблему, измените ваш макрос так, чтобы имя временной схемы PR содержало требуемый префикс. Например:

• ✅ Имя временной схемы PR содержит префикс dbt_cloud_pr_ (например, dbt_cloud_pr_123_456_marketing).
• ❌ Имя временной схемы PR не содержит префикс dbt_cloud_pr_ (например, marketing).

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

 Сообщения об ошибках, ссылающиеся на схемы из предыдущих PR

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

Чтобы исправить эту проблему, выберите производственное задание для отложения вместо self.

 Производственные задания не выполняются на этапе 'Клонирование Git репозитория'

dbt Cloud может проверять только коммиты, принадлежащие оригинальному репозиторию. dbt Cloud не может проверять коммиты, принадлежащие форку этого репозитория.

Если вы получаете следующее сообщение об ошибке на этапе Клонирование Git репозитория вашего задания:

Сообщение об ошибке:
Клонирование в '/tmp/jobs/123456/target'...
Репозиторий успешно клонирован.
Переход на e845be54e6dc72342d5a8f814c8b3316ee220312...>
Не удалось перейти на указанную ревизию.
git checkout e845be54e6dc72342d5a8f814c8b3316ee220312
fatal: reference is not a tree: e845be54e6dc72342d5a8f814c8b3316ee220312

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

 CI задание не запускается для пользователей Virtual Private dbt

Чтобы запускать задания в dbt Cloud с использованием API, ваш Git провайдер должен подключиться к вашему аккаунту dbt Cloud.

Если вы находитесь на плане Virtual Private dbt Enterprise, используя функции безопасности, такие как ingress PrivateLink или IP Allowlisting, регистрация CI хуков может быть недоступна и может привести к тихому сбою задания.

 Статус PR для CI задания остается 'в ожидании' в Azure DevOps после завершения выполнения задания

Когда вы запускаете CI задание, статус pull запроса должен отображаться как в ожидании, пока он ждет обновления от dbt. После завершения CI задания dbt отправляет статус в Azure DevOps (ADO), и статус изменится на успешно или неудачно.

Если статус не обновляется после выполнения задания, проверьте, есть ли какие-либо политики веток git, блокирующие ADO от получения этих обновлений.

Одной из возможных проблем является Сброс условий в разделе Проверки статуса в политике ветки репозитория ADO. Если вы включите флажок Сбрасывать статус при наличии новых изменений (в разделе Сброс условий), это может помешать dbt обновлять ADO о статусе выполнения вашего CI задания. Вы можете найти соответствующую информацию здесь:

• Azure DevOps Services Status checks
• Azure DevOps Services Pull Request Stuck Waiting on Status Update
• Pull request status