Continuous integration jobs в dbt

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

Запуск CI-задач в монорепозиториях

Если у вас монорепозиторий с несколькими dbt‑проектами, открытие одного pull request в одном из проектов приведёт к запуску заданий для всех проектов, подключённых к этому монорепозиторию. Чтобы избежать этого, вы можете использовать отдельные целевые ветки для каждого проекта (например, main-project-a, main-project-b), чтобы разделить триггеры CI.

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

• У вас есть аккаунт dbt.
• Возможности CI:
  • Для функций параллельных CI‑проверок и умной отмены устаревших сборок ваш аккаунт dbt должен быть на тарифе Starter, Enterprise или Enterprise+.
  • SQL‑линтинг доступен на release tracks dbt и для аккаунтов dbt на тарифах Starter, Enterprise или Enterprise+. В вашем проекте должен быть настроен SQLFluff.
• Возможности Advanced CI:
  • Для функции compare changes ваш аккаунт dbt должен быть на тарифе уровня Enterprise и иметь включённые функции Advanced CI. Пожалуйста, попросите администратора dbt включить эту возможность. После включения в настройках CI‑задания станет доступна опция dbt compare.
• Настройте подключение к вашему провайдеру Git. Эта интеграция позволяет dbt запускать задания от вашего имени при срабатывании триггеров.
  • Если вы используете нативную интеграцию с GitLab, вам потребуется платный или self‑hosted аккаунт, который поддерживает GitLab webhooks и project access tokens. Если вы используете GitLab Free, merge request’ы будут запускать CI‑задания, но статус выполнения CI (успех или ошибка задания) не будет передаваться обратно в GitLab.

Доступность функций в зависимости от Git‑провайдера

• Если ваш git‑провайдер имеет нативную интеграцию с dbt, вы можете без лишних усилий настраивать задания continuous integration (CI) прямо в dbt.

• Для провайдеров без нативной интеграции вы всё равно можете использовать метод Git clone, чтобы импортировать git URL, и задействовать Administrative API dbt для запуска CI‑заданий.

В следующей таблице приведены доступные варианты интеграции и соответствующие им возможности.

Git‑провайдер	Нативная интеграция с dbt	Автоматизированное CI‑задание	Git clone	Информация	Поддерживаемые планы
Azure DevOps	✅	✅	✅	Организации на планах Starter и Developer могут подключаться к Azure DevOps с использованием deploy key. Обратите внимание: вы не сможете настраивать автоматизированные CI‑задания, но при этом сможете вести разработку.	Enterprise, Enterprise+
GitHub	✅	✅			Все планы dbt
GitLab	✅	✅	✅		Все планы dbt
Все остальные git‑провайдеры при использовании Git clone (BitBucket, AWS CodeCommit и другие)	❌	❌	✅	См. руководство Customizing CI/CD with custom pipelines для настройки continuous integration и continuous deployment (CI/CD).

Loading table...

Настройка CI-задач

dbt Labs рекомендует создавать CI‑задания в отдельной deployment environment dbt, подключённой к staging‑базе данных. Наличие отдельного окружения, выделенного специально для CI, обеспечивает лучшую изоляцию между временными схемами, создаваемыми в CI, и вашими production‑сборками данных.

Кроме того, иногда командам требуется, чтобы CI‑задания запускались при создании PR не только в ветку main. Если в рамках процесса релизов ваша команда поддерживает staging‑ветку, отдельное окружение позволит задать пользовательскую ветку. Соответственно, CI‑задание в этом выделенном окружении будет запускаться только при создании PR в указанную пользовательскую ветку. Подробнее см. в разделе Get started with CI tests.

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

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

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

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

3. Опции в разделе Git trigger:

   • Triggered by pull requests — По умолчанию эта опция включена. Каждый раз, когда разработчик открывает pull request или отправляет коммит в уже существующий pull request, эта задача будет автоматически запускаться.
     • Run on draft pull request — Включите эту опцию, если вы хотите, чтобы задача также запускалась каждый раз, когда разработчик открывает черновик pull request (draft pull request) или отправляет коммит в этот черновик.

4. Опции в разделе Execution settings:

   • Commands — По умолчанию здесь указан командный вызов dbt build --select state:modified+. Он сообщает dbt, что нужно собирать только новые или изменённые модели и все зависящие от них downstream‑модели. Важно отметить, что сравнение состояния (state comparison) возможно только в том случае, если выбрано отложенное окружение (deferred environment), с которым будет выполняться сравнение. Нажмите Add command, чтобы добавить дополнительные commands, которые должны выполняться при запуске этой задачи.

   • Linting — Включите эту опцию, чтобы dbt выполнил linting SQL‑файлов в вашем проекте в качестве первого шага dbt run. Если в ходе этой проверки возникает ошибка, dbt может либо Stop running on error, либо Continue running on error.

   • dbt compareEnterpriseEnterprise + — Включите эту опцию, чтобы сравнить последнее применённое состояние production‑окружения (если оно существует) с последними изменениями из pull request и определить, в чём заключаются различия. Чтобы включить сравнение на уровне записей и анализ по первичному ключу, необходимо добавить primary key constraint или uniqueness test. В противном случае в dbt вы получите сообщение об ошибке «Primary key missing».

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

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

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

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

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

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

  к сведению

  В более ранних версиях dbt была доступна возможность отложенного выполнения только относительно конкретного job, а не окружения. При deferral к job состояние сравнивается с кодом проекта из последнего успешного запуска этого job. Deferral к окружению более эффективен, поскольку dbt сравнивает код с представлением проекта (которое хранится в manifest.json) из последнего успешного deploy job, выполненного в этом окружении. Учитывая все deploy jobs, которые выполняются в отложенном окружении, dbt получает более точное и актуальное представление состояния проекта.

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

1. (необязательно) Параметры в разделе Advanced settings:

   • Environment variables — Определите переменные окружения, чтобы настроить поведение проекта при выполнении этого CI‑задания. Вы можете указать, что CI‑задание запускается в окружении Staging или CI, задав переменную окружения и изменив код проекта так, чтобы он вел себя по‑разному в зависимости от контекста. Для команд распространена практика обрабатывать в CI только подмножество данных, используя переменные окружения для ветвления логики в коде dbt‑проекта.
   • Target name — Определите target name. Аналогично Environment Variables, этот параметр позволяет настраивать поведение проекта. Его можно использовать, чтобы указать, что CI‑задание выполняется в окружении Staging или CI, задав имя таргета и изменив код проекта так, чтобы он вел себя по‑разному в зависимости от контекста.
   • dbt version — По умолчанию используется версия dbt, унаследованная от окружения. dbt Labs настоятельно рекомендует не менять значение по умолчанию. Возможность переопределить версию на уровне задания полезна только при обновлении проекта на следующую версию dbt; в остальных случаях несоответствие версий между окружением и заданием может привести к запутанному поведению.
   • Threads — По умолчанию установлено значение 4 threads. Увеличьте количество потоков, чтобы повысить параллельность выполнения моделей.
   • Generate docs on run — Включите этот параметр, если хотите генерировать документацию проекта при выполнении этого задания. По умолчанию он отключён, поскольку проверка генерации документации при каждом CI‑прогоне не является рекомендуемой практикой.
   • Run source freshness — Включите этот параметр, чтобы перед запуском CI‑задания выполнить команду dbt source freshness. Подробнее см. в разделе Source freshness.
   Пример страницы CI Job в интерфейсе dbt

Пример CI-проверки в pull request

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

Пример CI-проверки в pull request на GitHub

Пример CI-отчета в pull request Preview

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

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

Триггер CI job через API EnterpriseEnterprise +

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

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

• У вас есть учетная запись dbt.
• У вас тариф dbt Enterprise или Enterprise+. Доступ также сохраняется у legacy Team планов.
  • Для возможностей Concurrent CI checks и Smart cancellation of stale builds ваш аккаунт dbt должен быть на тарифе Enterprise или Enterprise+ (а также у legacy Team планов). Starter планы не имеют доступа к этим возможностям при триггере CI job через API.

1. Настройте CI job через API endpoint Create Job, указав "job_type": ci, или через UI dbt.
2. Вызовите API endpoint Trigger Job Run, чтобы запустить CI job. В payload нужно обязательно передать оба поля:

   • Укажите ID pull request (PR) в одном из следующих полей:

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

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

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

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

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

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

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

• Тестирование семантических узлов в CI-задаче поддерживает deferral и selection для семантических узлов.
• Это позволяет выявлять проблемы на ранних этапах разработки и предоставлять конечным пользователям данные высокого качества.
• Семантическая валидация выполняет explain-запрос в хранилище данных для семантических узлов, чтобы убедиться, что сгенерированный SQL будет корректно выполняться.
• Для семантических узлов и моделей, которые не находятся ниже по графу зависимостей от изменённых моделей, dbt выполняет deferral к продакшн‑моделям.

Настройка семантических проверок в вашем 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 должен собрать изменённые модели. Этот процесс гарантирует, что нижележащие (downstream) семантические узлы будут валидироваться с использованием CI‑схемы через API семантического слоя dbt.

Для семантических узлов и моделей, которые не находятся ниже по графу от изменённых моделей, dbt использует (defer) продакшн‑модели.

Validate semantic nodes downstream of model changes in your CI job.

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

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

dbt sl validate --select state:modified+

Используйте state selection, чтобы валидировать изменённые модели определения метрик в вашем CI‑джобе.

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

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

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

dbt sl validate --select metric:revenue

Используйте выбор по состоянию (state selection) для валидации изменённых моделей определений метрик в вашем CI‑задании.

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

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

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

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

dbt sl validate

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   • Если вы создаёте новый PR (PR 2) на том же самом коммите (#4818ceb), что и предыдущий PR (PR 1), который уже запускал CI-задачу, — dbt не запустит новую 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 не удаляет временные схемы, в которые не было выполнено записи в результате запуска модели dbt.

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

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

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

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

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

Если при выполнении вашего job run на шаге Clone Git Repository вы получаете следующее сообщение об ошибке:

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

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

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

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

Если вы находитесь на плане 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
• Запрос на слияние Azure DevOps Services застрял в ожидании обновления статуса
• Статус pull request

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

Создать GitHub Issue