Обновление до dbt v2, часть 2: Переход на новую версию

Это руководство поможет вам выполнить обновление с последней версии dbt v1 до dbt v2 на платформе dbt без переноса в новую среду.

Назад к гайдам

dbt v2

Платформа dbt

Обновление

Средний уровень

Menu

Введение

dbt v2 — это новый этап развития трансформации данных. dbt был полностью переработан, но по сути dbt v2 — это новая версия, и переход на неё ничем не отличается от обновления между версиями dbt v1 в dbt platform. Как только ваш проект будет готов к работе с dbt v2, для перехода достаточно будет изменить несколько настроек. При этом вы можете выбрать, как именно выполнить переход, особенно в средах разработки.

После завершения миграции на dbt v2 ваша команда получит следующие преимущества:

• ⚡ Парсинг и компиляция до 30 раз быстрее
• 💰 Снижение затрат на хранилище данных на 30% и более (с dbt State)
• 🔍 Улучшенная проверка SQL и более информативные сообщения об ошибках
• 🛠️ Современные инструменты разработки

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

Перед обновлением среды разработки убедитесь, что:

• Ваш проект использует канал обновлений v1 Latest (настроено в части 1: Подготовка к обновлению)
• Ваш проект должен использовать поддерживаемый адаптер и метод аутентификации.
   BigQuery

  • Сервисный аккаунт / Токен пользователя
  • Встроенный OAuth
  • Внешний OAuth
    • Федерация удостоверений рабочих нагрузок (Microsoft Entra)
  • Необходимые разрешения
   Databricks

  • Сервисный аккаунт / Токен пользователя
  • Встроенный OAuth
   Redshift

  • Имя пользователя / Пароль
  • Профиль IAM
   Snowflake

  • Имя пользователя / Пароль
  • Встроенный OAuth
  • Внешний OAuth
  • Пара ключей с использованием современного формата PKCS#8
  • MFA
   ClickHouseЗакрытая бета-версия

  • Имя пользователя / Пароль
• У вас есть лицензия разработчика в dbt platform
• Для вашей учетной записи включен dbt v2
• У вас есть необходимые разрешения для изменения окружений (если доступ ограничен, см. Предоставление доступа к обновлению)

Обновление среды разработки

После подготовки проекта и тестирования на треке Latest вы готовы обновить среду разработки до dbt v2. dbt platform предоставляет пошаговый мастер обновления, который проведёт вас через процесс и поможет убедиться, что проект готов к dbt v2.

Когда ваш проект подготовлен и протестирован на канале обновлений v1 Latest, вы можете перейти к обновлению среды разработки до dbt v2. dbt platform предоставляет пошаговый помощник по обновлению, который проведёт вас через весь процесс и поможет проверить готовность проекта к работе с dbt v2.

Всегда сначала обновляйте среду разработки, прежде чем переходить к production. Это позволяет вам и вашей команде безопасно протестировать dbt v2 и устранить возможные проблемы до того, как они затронут production‑процессы.

:::

Назначение доступа к обновлению (необязательно)

Работа помощника по обновлению до dbt v2 регулируется двумя настройками на уровне аккаунта. Сначала администратор аккаунта должен включить функции оценки готовности, а затем при необходимости ограничить круг пользователей, которые могут выполнять обновление.

Включение функций оценки готовности к dbt v2

Помощник по обновлению и панель готовности появляются только после того, как администратор аккаунта включит эту настройку:

1. Перейдите в Account settings → Account.
2. Нажмите Edit и прокрутите страницу до раздела Settings.
3. Установите флажок рядом с Enable dbt v2 readiness & upgrade features.
4. Нажмите Save.

После включения все пользователи смогут видеть панель готовности и помощник Start dbt v2 upgrade (с учётом имеющихся у них разрешений).

Ограничение круга пользователей, которые могут выполнять обновления (необязательно, только для Enterprise)

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

1. В Account settings → Account нажмите Edit.
2. Установите флажок рядом с Enable restricted dbt v2 upgrade permissions.
3. Нажмите Save.

Когда эта настройка включена, выполнять обновления могут только пользователи с набором разрешений v2 Migration Admin. Чтобы назначить этот набор разрешений:

1. Перейдите в Account settings → Groups и выберите группу, которой нужно предоставить доступ.
2. Нажмите Edit и прокрутите страницу до раздела Access and permissions.
3. Нажмите Add permission и выберите v2 Migration Admin в раскрывающемся списке.
4. Выберите проекты, к которым пользователи должны иметь доступ.
5. Нажмите Save.

Подробнее об управлении доступом см. в разделе Предоставление доступа к обновлению.

Шаг 1: Запуск мастера обновления

Запустите процесс обновления dbt v2 из вашего проекта:

1. Войдите в dbt platform и перейдите в свой проект.
2. На главной странице проекта или на боковой панели нажмите Start dbt v2 upgrade или Get started.

Запуск обновления до dbt v2 с главной страницы проекта

Вы будете перенаправлены в Studio IDE, где в верхней части экрана будет отображаться помощник по обновлению.

Шаг 2: Проверка предупреждений о депрекейтах

Даже если вы устранили депрекейты в части 1, выполните финальную проверку, чтобы убедиться, что ничего не было пропущено:

1. В верхней части Studio IDE нажмите Check deprecation warnings (Проверить предупреждения об устаревших возможностях).

Проверка предупреждений об устаревших возможностях в вашем проекте

2. Дождитесь завершения парсинга (это может занять некоторое время в зависимости от размера проекта).
3. Ознакомьтесь с результатами:
   • No warnings found: Переходите сразу к шагу 4.
   • Warnings found: Перейдите к шагу 3 для их устранения.

Несогласованность предупреждений dbt v2 и логов dbt-autofix

Вы можете увидеть предупреждения dbt v2 о том, что некоторые пакеты несовместимы с dbt v2, в то время как dbt autofix сообщает об их совместимости. В этом случае используйте dbt autofix как источник истины, поскольку он обладает дополнительным контекстом, которого пока нет у предупреждений dbt v2. Это временное несоответствие и будет устранено после внедрения расширенной логики определения совместимости из dbt-autofix в предупреждения dbt v2.

Шаг 3: Устранение оставшихся депрекейтов

Если были найдены предупреждения, используйте инструмент autofix для их устранения:

1. В списке предупреждений нажмите Autofix warnings.
2. Ознакомьтесь с предлагаемыми изменениями в диалоге.
3. Нажмите Continue, чтобы автоматически применить исправления.
4. Дождитесь завершения работы инструмента autofix и повторного парсинга.
5. Проверьте изменённые файлы в панели Version control.
6. Если все предупреждения устранены, вы увидите сообщение об успехе.

Сообщение об успешном устранении использования устаревших возможностей

Подробную информацию о процессе автоматического исправления см. в разделе Устранение предупреждений об устаревших возможностях.

Требуются ручные исправления?

Если инструмент autofix не может автоматически устранить все депрекейты, вам потребуется исправить их вручную. Ознакомьтесь с текстом предупреждений, внесите необходимые изменения в код и снова запустите Check deprecation warnings.

Шаг 4: Включите dbt v2

После устранения всех депрекейтов обновите среду разработки:

1. Нажмите кнопку Включить dbt v2 в верхней части Studio IDE.
2. Подтвердите обновление при появлении запроса.
3. Дождитесь обновления среды (обычно это занимает всего несколько секунд).

Ваша среда разработки теперь работает на dbt v2!

Шаг 5: Перезапуск IDE

После обновления всем пользователям необходимо перезапустить IDE, чтобы подключиться к новой среде на базе dbt v2:

1. Если вы сейчас работаете в Studio IDE, обновите окно браузера.
2. Сообщите участникам вашей команды, что им также необходимо перезапустить свои IDE.

Шаг 6: Проверка обновления

Убедитесь, что среда разработки работает на dbt v2:

1. Откройте или создайте файл модели dbt в Studio IDE.
2. Обратите внимание на возможности, работающие на базе dbt v2:
   • Ускоренный разбор и компиляция
   • Улучшенная проверка SQL и более информативные сообщения об ошибках
   • Усовершенствованное автодополнение
3. Выполните простую команду для проверки работоспособности:

   dbt compile

   Сообщить об ошибке в коде
4. Убедитесь, что выполнение команды стало заметно быстрее.

Шаг 7: Тестирование рабочих процессов

Перед тем как считать обновление завершённым, протестируйте типовые сценарии разработки:

1. Внесите изменения в модель и выполните dbt compile.
2. Запустите подмножество моделей: dbt run --select model_name.
3. Выполните тесты.
4. Просмотрите результаты в встроенном инструменте запросов.
5. Убедитесь, что операции Git (commit, push, pull) работают корректно.

Обратная связь

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

А как насчёт продакшена?

Ваше окружение разработки теперь работает на dbt v2, но продакшен‑окружение и deployment jobs по‑прежнему выполняются на dbt v1. Это сделано намеренно, чтобы дать вам и вашей команде время:

• Тщательно протестировать dbt v2 в разработке.
• Укрепить уверенность в новом движке.
• Выявить и устранить любые проблемы, специфичные для проекта.
• Обучить участников команды изменениям в процессах.

Когда вы будете готовы обновить производственную среду, вам нужно будет настроить среды развертывания и задания на использование канала выпусков v2 Stable. Мы рассмотрим это в следующем разделе.

Обновите staging и промежуточные окружения

После успешного обновления и тестирования окружения разработки следующий шаг — обновление staging‑окружения или других промежуточных deployment environments. Эти окружения служат критически важным слоем валидации перед тем, как продвигать dbt v2 в продакшен: они позволяют тестировать на продакшен‑подобных данных и в продакшен‑подобных процессах, при этом ограничивая риск.

Почему сначала обновлять staging?

Staging‑окружения дают:

• Финальный слой валидации dbt v2 на данных продакшен‑масштаба
• Возможность тестировать запланированные jobs и процессы развертывания
• Возможность проверить интеграции и downstream‑зависимости
• Безопасное окружение, чтобы оценить характеристики производительности до продакшена

Что такое staging‑окружение?

Staging environment — это deployment environment, которое зеркалирует вашу продакшен‑настройку, но использует не‑продакшен данные или учётные данные с ограниченным доступом. Оно позволяет команде тестировать процессы развертывания, запланированные jobs и преобразования данных, не затрагивая продакшен‑системы.

Если у вас ещё нет staging‑окружения, подумайте о том, чтобы создать его до обновления продакшена до dbt v2. Это даст вам крайне полезный «полигон» для тестирования.

Шаг 1: Перейдите в настройки окружения

Откройте настройки для вашего staging‑окружения или промежуточного окружения:

1. Войдите в dbt platform и перейдите в ваш проект.
2. В левом сайдбаре нажмите Orchestration.
3. В выпадающем списке выберите Environments.
4. Нажмите на название staging‑окружения, чтобы открыть его настройки.
5. В правом верхнем углу нажмите кнопку Edit.

Перейдите к настройкам окружения

Шаг 2: Обновите версию dbt

Переключите staging‑окружение на release track dbt v2:

1. В настройках среды прокрутите страницу до раздела dbt version.
2. Откройте раскрывающееся меню dbt version.
3. Выберите v2 Stable из списка.
4. Прокрутите страницу вверх и нажмите Save.

Выберите v2 Stable в раскрывающемся меню dbt version

Ваше staging‑окружение теперь настроено на использование dbt v2! Все jobs, связанные с этим окружением, будут использовать dbt v2 при следующем запуске.

Шаг 3: Запустите тестовую job

Проверьте, что dbt v2 корректно работает в вашем staging‑окружении, запустив job:

1. На странице Environments нажмите на ваше staging‑окружение.
2. Выберите существующую job или нажмите Create job, чтобы создать новую.
3. Нажмите Run now, чтобы запустить job сразу.
4. Следите за выполнением job в реальном времени, открыв детали запуска.

Шаг 4: Мониторьте запланированные jobs

Если у вас в staging‑окружении есть jobs по расписанию, проследите за их следующими запланированными запусками:

1. Перейдите в Deploy → Jobs и отфильтруйте по staging‑окружению.
2. Дождитесь автоматического запуска jobs по расписанию (или запустите вручную).
3. Просмотрите историю запусков на предмет неожиданных ошибок или предупреждений.
4. Сравните время выполнения с предыдущими запусками на dbt v1. Вы должны увидеть заметные улучшения.

Шаг 5: Проверьте интеграции и зависимости

Протестируйте интеграции и зависимости, которые опираются на ваше staging‑окружение:

1. Межпроектные ссылки: если используете dbt Mesh, убедитесь, что downstream‑проекты по‑прежнему могут ссылаться на ваши staging‑модели.
2. BI‑инструменты: проверьте, что любые BI‑инструменты или дашборды, подключённые к staging, продолжают работать корректно.
3. Downstream‑потребители: уведомите команды, которые потребляют staging‑данные, чтобы они подтвердили, что их процессы по‑прежнему работают.
4. CI/CD‑процессы: запустите любые CI jobs, которые таргетят staging, чтобы убедиться, что они выполняются корректно.

Повторите для других промежуточных окружений

Нашли проблему?

Если вы столкнулись с проблемами в среде staging:

• Ознакомьтесь с ограничениями v2, чтобы проверить, не является ли проблема известной.
• Проверьте журналы заданий на наличие конкретных сообщений об ошибках.
• Протестируйте те же модели в своей среде разработки, чтобы локализовать проблему.
• Обратитесь в службу поддержки dbt или к команде, работающей с вашей учётной записью, за помощью.

На время расследования вы можете вернуть среду staging на канал выпусков v1 Latest.

Сколько времени нужно тестировать на staging?

Рекомендуемый период тестирования зависит от вашей организации:

• Минимум: хотя бы один успешный запуск всех критически важных jobs.
• Рекомендуется: мониторить jobs по расписанию 3–7 дней, чтобы отловить проблемы, зависящие от времени или данных.
• Enterprise/сложные проекты: рассмотрите 1–2 недели тестирования, особенно если у вас много downstream‑зависимостей.

Не торопитесь на этом этапе. Тщательное тестирование на staging предотвращает сбои в продакшене.

---

Обновите продакшен‑окружение

Поздравляем! Вы успешно обновили среды разработки и тестирования и теперь готовы к последнему шагу: обновлению производственной среды до dbt v2.

Важные моменты при обновлении продакшен‑окружения

Обновление производственной среды — ответственная операция. Хотя dbt v2 готов к использованию в производственной среде и прошёл тщательное тестирование в ваших средах разработки и предварительного тестирования, соблюдайте следующие рекомендации:

• Запланируйте обновление на период низкой нагрузки, чтобы свести к минимуму его влияние.
• Уведомите заинтересованные стороны об окне технического обслуживания.
• Подготовьте план отката (возврат на канал выпусков v1 Latest).
• Внимательно отслеживайте первые несколько запусков заданий после обновления.

Шаг 1: Запланируйте сервисное окно

Выберите оптимальное время для обновления продакшена:

• Просмотрите расписание jobs: определите периоды с минимальной активностью jobs.
• Проверьте downstream‑зависимости: убедитесь, что зависимые системы могут пережить короткие прерывания.
• Уведомите стейкхолдеров: сообщите пользователям BI‑инструментов, потребителям данных и участникам команды.
• Задокументируйте план: зафиксируйте, какие jobs мониторить и критерии успеха.

Шаг 2: Перейдите в настройки продакшен‑окружения

Откройте конфигурацию продакшен‑окружения:

1. Войдите в dbt platform и перейдите в ваш проект.
2. В левом сайдбаре нажмите Orchestration.
3. В выпадающем списке выберите Environments.
4. Нажмите на ваше продакшен‑окружение (обычно помечено бейджем Production).
5. В правом верхнем углу нажмите кнопку Edit.

Доступ к настройкам производственной среды

Шаг 3: Обновление до v2 Stable

Переключите продакшен‑окружение на dbt v2:

1. В настройках окружения прокрутите страницу до раздела dbt version.
2. Нажмите раскрывающееся меню dbt version.
3. Выберите v2 Stable из списка.
4. Ещё раз проверьте настройки, чтобы убедиться, что всё указано правильно.
5. Прокрутите страницу вверх и нажмите Save.

Выберите v2 Stable для производственной среды

Ваше продакшен‑окружение теперь работает на dbt v2!

Шаг 4: Запустите тестовую job сразу

Проверьте обновление, запустив job:

1. На странице Environments нажмите на ваше продакшен‑окружение.
2. Выберите критически важную job, которая покрывает хорошую часть моделей.
3. Нажмите Run now, чтобы выполнить job сразу.
4. Внимательно следите за запуском job:
   • Проверьте шаги parse и compile.
   • Убедитесь, что все модели собираются успешно.
   • Убедитесь, что тесты проходят как ожидается.
   • Просмотрите логи на предмет неожиданных предупреждений.

Если job прошла успешно — обновление продакшена выполнено!

Включите панель готовности к dbt v2

Панель готовности к dbt v2 показывает статус готовности каждого проекта к переходу и блокирующие проблемы в dbt platform. Она внедряется поэтапно — если она ещё не включена для вашей учётной записи, администратор учётной записи может включить её в разделе Account settings → Account. Инструкции по настройке см. в разделе Включение функций проверки готовности к dbt v2.

Если у вас есть доступ к dbt Wizard, используйте процесс миграции на dbt v2 с помощью dbt Wizard, чтобы исправлять ошибки совместимости непосредственно в Studio IDE с помощью dbt Wizard — без необходимости вручную анализировать журналы!

Шаг 5: Включите dbt State (необязательно, но рекомендуется)

dbt State автоматически определяет, какие модели необходимо пересобрать на основе изменений в коде или данных, что позволяет сократить затраты на хранилище данных на 30% и более. Чтобы начать работу, см. Настройка dbt State.

Оркестрация с учетом состояния теперь называется dbt State

dbt State работает со всеми движками и средами: dbt v1, dbt platform и dbt v2

Если вы использовали оркестрацию с учетом состояния до 1 июня 2026 года, вы можете продолжать ее использовать. Когда вы начнете бесплатный пробный период dbt State, он будет продлен сверх стандартных 30 дней. Если продление не применено к вашей учетной записи, обратитесь к команде по работе с вашим аккаунтом. Чтобы начать, ознакомьтесь с разделом Переход с оркестрации с учетом состояния.

Шаг 6: Мониторьте продакшен‑jobs

Внимательно следите за продакшен‑jobs в первые 24–48 часов:

• Проверьте запуски заданий по расписанию: Перейдите в Deploy → Jobs → Run history
• Отслеживайте время выполнения: Сравните его со средними значениями за прошлые периоды. Вы должны заметить значительные улучшения.
• Оцените экономию затрат: Если вы включили dbt State, откройте Cost Insights, чтобы увидеть фактическую экономию.
• Следите за предупреждениями: Проверяйте логи на наличие неожиданных сообщений.

Шаг 7: Проверьте интеграции с нижестоящими системами

Убедитесь, что все системы, зависящие от ваших продакшен‑данных, продолжают работать корректно:

1. BI‑инструменты: проверьте, что дашборды и отчёты обновляются правильно.
2. Потребители данных: подтвердите, что downstream‑команды могут получать доступ к данным и выполнять запросы.
3. API и интеграции: протестируйте любые приложения, которые потребляют результаты dbt.
4. Semantic Layer: если вы используете dbt Semantic Layer, убедитесь, что запросы метрик работают.
5. Алерты и мониторинг: проверьте, что алерты качества данных и мониторинги работают корректно.

Шаг 8: Обновите оставшиеся jobs с version overrides

Для некоторых заданий могли быть заданы переопределения версии в ходе предыдущего тестирования. Теперь, когда рабочая среда использует dbt v2, удалите эти переопределения:

1. Перейдите в Orchestration → Jobs.
2. Проверьте настройки каждой job.
3. Если у job есть version override (он отображается в разделе dbt version), нажмите Edit.
4. Удалите override, чтобы job унаследовала настройку dbt v2 от окружения.
5. Нажмите Save.

Процедура отката

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

1. Перейдите в Orchestration → Environments → Production.
2. Нажмите Edit.
3. Измените значение dbt version с v2 Stable обратно на v1 Latest.
4. Нажмите Save.
5. При следующем запуске задания будут использовать dbt v1.

Влияние отката

Откат к v1 Latest отключит функции, доступные только в dbt v2. Выполняйте откат только при возникновении проблем, критичных для работы в продакшене.

dbt lint

Теперь, когда ваш проект работает на dbt v2, вам доступна команда dbt lint. Команда lint — это высокопроизводительный SQL-линтер, встроенный в dbt v2. Он совместим с SQLFluff: читает существующий файл конфигурации .sqlfluff, использует те же коды правил (например, CP01, RF03) и учитывает комментарии -- noqa для подавления предупреждений. Совместимость не означает идентичность. Подробнее о соответствии правил см. в разделе Соответствие правил SQLFluff.

Основы использования

# Проверить все SQL-файлы в проекте
dbt lint

# Проверить конкретный файл
dbt lint models/my_model.sql

# Автоматически исправить нарушения
dbt lint --fix

# Проверить только файлы, изменённые в рабочем дереве
dbt lint --changed

Сообщить об ошибке в коде

Полный список флагов, поддерживаемых диалектов и синтаксис подавления предупреждений см. в справочнике по dbt lint.

Следующие шаги

🎉 Поздравляем!

Вы успешно обновили весь проект dbt platform до dbt v2!

Дальше можно:

• Продолжайте оптимизацию: Изучите настройки dbt State, чтобы точнее настроить интервалы обновления.
• Отслеживайте экономию: Используйте Cost Insights, чтобы отслеживать, какие модели были построены, а какие — использованы повторно.
• Обучайте команду: Расскажите команде о возможностях dbt v2 и лучших практиках их использования.
• Изучайте новые возможности: Ознакомьтесь с отслеживанием происхождения данных на уровне столбцов, предварительным просмотром CTE в реальном времени и другими возможностями на базе dbt v2.

Поделитесь успехом

Нам будет интересно узнать о вашем опыте обновления до dbt v2! Поделитесь обратной связью с вашей аккаунт‑командой или присоединяйтесь к dbt Community Slack, чтобы обсудить dbt v2 с другими пользователями.

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

Создать GitHub Issue