Обновление версии dbt в Cloud

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

Окружения

Перейдите на страницу настроек окружения, затем нажмите Edit. Нажмите на выпадающее меню dbt version и выберите нужную версию. Вы можете выбрать трассу релизов для получения постоянных обновлений (рекомендуется) или устаревшую версию dbt Core. Обязательно сохраните изменения перед тем, как покинуть страницу.

Пример настроек окружения в dbt Cloud

Трассы релизов

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

Трасса Latest гарантирует, что у вас будет актуальная функциональность dbt Cloud и ранний доступ к новым функциям фреймворка dbt. Трассы Compatible и Extended предназначены для клиентов, которым требуется менее частая периодичность релизов, возможность тестировать новые релизы dbt перед их запуском в производственной среде и/или постоянная совместимость с последними версиями dbt Core с открытым исходным кодом.

Как лучшую практику, dbt Labs рекомендует сначала протестировать обновление в среде разработки; используйте настройку Override dbt version, чтобы протестировать ваш проект на последней версии dbt перед обновлением ваших окружений развертывания и стандартной среды разработки для всех ваших коллег.

Чтобы обновить окружение в dbt Cloud Admin API или Terraform, установите dbt_version в имя вашей трассы релизов:

• latest (ранее называлась versionless; старое название все еще поддерживается)
• compatible (доступно для Team + Enterprise)
• extended (доступно для Enterprise)

Переопределение версии dbt

Настройте ваш проект на использование другой версии dbt Core, чем та, что настроена в вашей среде разработки. Это переопределение влияет только на вашу учетную запись пользователя, а не на других. Используйте это, чтобы безопасно тестировать новые функции dbt перед обновлением версии dbt для ваших проектов.

1. Нажмите на имя вашей учетной записи в левой панели и выберите Account settings.
2. Выберите Credentials в боковой панели и выберите проект. Это откроет боковую панель.
3. В боковой панели нажмите Edit и прокрутите до раздела User development settings. Выберите версию из выпадающего меню dbt version и нажмите Save.

Пример переопределения настроенной версии на 1.7 для выбранного проекта:

Пример переопределения версии dbt в вашей учетной записи

1. (Опционально) Убедитесь, что dbt Cloud будет использовать ваше переопределение для сборки проекта. Вызовите dbt build в командной строке IDE. Разверните раздел System Logs и найдите первую строку вывода. Она должна начинаться с Running with dbt= и указывать версию, которую использует dbt Cloud.

Пример вывода успешного выполнения dbt build:

Пример вывода, показывающий использование версии 1.7, а не 1.5

Задания

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

Настройки задания в dbt Cloud

Пример задания, показанный на скриншоте выше, принадлежит окружению "Prod". Оно наследует версию dbt из своего окружения, как показано в выборе Inherited from ENVIRONMENT_NAME (DBT_VERSION). Вы также можете вручную переопределить версию dbt для конкретного задания, выбрав другую опцию из выпадающего меню.

Поддерживаемые версии

dbt Labs всегда поощрял пользователей обновлять версии dbt Core, когда выходит новая минорная версия. Мы выпустили нашу первую мажорную версию dbt - dbt 1.0 - в декабре 2021 года. Вместе с этим выпуском мы обновили нашу политику относительно версий dbt Core, которые мы будем поддерживать в dbt Cloud.

Начиная с v1.0, все последующие минорные версии доступны в dbt Cloud. Версии активно поддерживаются, с патчами и исправлениями ошибок, в течение 1 года после их первоначального выпуска. В конце этого 1-летнего периода мы рекомендуем всем пользователям обновиться до более новой версии для лучшего постоянного обслуживания и поддержки.

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

• Active — Мы будем исправлять регрессии, новые ошибки и включать исправления для старых ошибок / улучшения качества жизни. Мы внедряем эти изменения, когда уверены, что они имеют узкую направленность и не вызовут непреднамеренных побочных эффектов.
• Critical — Более новые минорные версии переводят предыдущую минорную версию в "Критическую поддержку" с ограниченными "безопасными" релизами для критических исправлений безопасности и установки.
• End of Life — Минорные версии, достигшие конца срока службы (EOL), больше не получают новых патчей.
• Устаревшие — Версии dbt Core старше v1.0 больше не поддерживаются dbt Labs и не поддерживаются в dbt Cloud.

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

Последние выпуски

dbt Core	Первоначальный выпуск	Уровень поддержки и дата окончания
v1.9	9 дек, 2024	Активная поддержка — 8 дек, 2025
v1.8	9 мая, 2024	Активная поддержка — 8 мая, 2025
v1.7	2 ноя, 2023	Клиенты dbt Core и dbt Cloud Developer & Team: Конец поддержки Клиенты dbt Cloud Enterprise: Критическая поддержка до дальнейшего уведомления 1
v1.6	31 июл, 2023	Конец поддержки ⚠️
v1.5	27 апр, 2023	Конец поддержки ⚠️
v1.4	25 янв, 2023	Конец поддержки ⚠️
v1.3	12 окт, 2022	Конец поддержки ⚠️
v1.2	26 июл, 2022	Конец поддержки ⚠️
v1.1	28 апр, 2022	Конец поддержки ⚠️
v1.0	3 дек, 2021	Конец поддержки ⚠️
v0.X ⛔️	(Разные даты)	Устарело ⛔️

Вся функциональность dbt Core, начиная с выпуска v1.7, доступна в выпускных треках dbt Cloud, которые обеспечивают автоматические обновления с частотой, подходящей для вашей команды.

¹ Выпускные треки обязательны для планов Developer и Teams в dbt Cloud. Аккаунты, использующие более старые версии dbt, будут переведены на трек "Latest".

Для клиентов dbt Cloud Enterprise, dbt v1.7 будет продолжать быть доступным в качестве опции до тех пор, пока dbt Labs не объявит, что треки "Compatible" и "Extended" стали общедоступными, что планируется на март 2025 года. (В настоящее время они доступны всем подходящим аккаунтам в режиме Preview.) В это время dbt Labs настоятельно рекомендует мигрировать любые среды, которые все еще работают на более старых неподдерживаемых версиях, на выпускные треки или dbt v1.7.

Начиная с v1.0, dbt Cloud будет гарантировать, что вы всегда используете последнюю совместимую патч-версию dbt-core и плагинов, включая все последние исправления. Вы также можете выбрать попробовать предварительные релизы этих патчей до их общего доступа.

Для получения дополнительной информации о поддержке версий и будущих релизах, см. Понимание версий dbt Core.

Нужна помощь с обновлением?

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

Обновление устаревших версий до 1.0

Вы можете использовать следующие разделы, чтобы успешно обновить вашу версию dbt Core в dbt Cloud. Мы рекомендуем всем обновиться до самой последней версии dbt Core, так как новые версии содержат улучшения, исправления ошибок и обновленные функции безопасности. Мы документируем, какие версии dbt Core в настоящее время поддерживаются.

Между минорными версиями нет многих критических изменений, и может оказаться, что вам не нужно менять код для обновления до более новой версии dbt в dbt Cloud. Критические изменения есть только между минорными версиями dbt до dbt 1.0. Минорные релизы, начиная с dbt 1.0, не имеют критических изменений в коде. Если изменения в коде не требуются, все, что вам нужно сделать, это изменить настройки в вашем окружении или задании, чтобы использовать более новую версию dbt.

Изменения между минорными версиями dbt, которые повлияют на ваш проект

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

Важное замечание о пакетах

Если вы используете какие-либо пакеты из dbt Hub, убедитесь, что вы также обновили версию пакета, которая поддерживает версию dbt, на которую вы собираетесь обновиться. Вы можете увидеть, какие версии dbt поддерживает пакет, проверив require-dbt-version: в файле dbt_project.yml пакета на GitHub.

Например, версия dbt-utils 0.7.6 поддерживает dbt v0.20, v0.21 и v1.0, как описано в его dbt_project.yml.

После того как вы изменили версию пакета в вашем файле packages.yml, обязательно выполните dbt deps в IDE, чтобы установить обновленную версию.

Обновление до v1.0.latest с v0.21

Универсальное изменение

Некоторые конфигурации в dbt_project.yml были переименованы

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

dbt_project.yml

model-paths: ["models"] # ранее называлось "source-paths"
seed-paths: ["data"]    # ранее называлось "data-paths"
clean-targets:
  - "target"
  - "dbt_packages"      # ранее называлось "dbt_modules"

• Вы выбираете тесты, используя старые названия типов тестов? (test_type:schema, test_type:data, --schema, --data)
• У вас есть пользовательский макрос, который вызывает (недокументированные) глобальные макросы column_list, column_list_for_create_table, incremental_upsert?
• У вас есть пользовательские скрипты, которые парсят артефакты dbt ?
• (Только BigQuery) Вы используете устаревшие возможности dbt для таблиц с разделением по времени загрузки?

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

Обновление до v0.21.latest с v0.20

• Вы выбираете конкретные источники для проверки свежести (dbt snapshot-freshness --select <source_name>)?
• У вас есть пользовательские скрипты, которые парсят артефакты dbt JSON?
• (Только Snowflake) У вас есть пользовательские макросы или материализации, которые зависят от использования транзакций, таких как блоки операторов с auto_begin=True?

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

Обновление до v0.20.latest с v0.19

• Ваш проект определяет какие-либо пользовательские тесты схемы?
• Ваш проект использует adapter.dispatch или пакет spark_utils?
• У вас есть пользовательские скрипты, которые парсят артефакты dbt JSON?

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

Обновление до v0.19.latest с v0.18

• У вас есть пользовательские скрипты, которые парсят артефакты dbt JSON?
• У вас есть какие-либо пользовательские материализации?

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

Обновление до v0.18.latest с v0.17

• Вы напрямую вызываете adapter_macro?

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

Обновление до v0.17.latest с v0.16

Универсальное изменение

Вы должны добавить config-version: 2 в ваш файл dbt_project.yml.

dbt_project.yml

name: my_project
version: 1.0.0

config-version: 2

vars:
  my_var: 1
  another_var: true

models:
  ...

Универсальное изменение

vars: теперь определяются не в вашем models:, а являются отдельным разделом в файле dbt_project.yml.

dbt_project.yml

name: my_project
version: 1.0.0

config-version: 2

vars:
  my_var: 1
  another_var: true

models:
  ...

• У вас есть конфигурации словарей в вашем dbt_project.yml, такие как partition_by или persist_docs? Если да, вам нужно добавить перед ними +.

dbt_project.yml

models:
  my_project:
    reporting:
      +partition_by:
        field: date_day
        data_type: timestamp

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

Обновление до v0.16.latest с v0.15

• Вы используете пользовательский макрос generate_schema_name?
• Вы используете конфигурацию partition_by для моделей BigQuery?

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

Обновление до v0.15.latest с v0.14

• У вас есть пользовательская материализация?
• У вас есть макрос, который напрямую обращается к Relations?

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

Обновление до v0.14.latest с v0.13

• Вы все еще используете Archives?
• Вы используете пользовательский макрос generate_schema_name?
• Вы используете флаг —non-destructive?

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

Тестирование ваших изменений перед обновлением

Как только вы узнаете, какие изменения в коде вам нужно будет сделать, вы можете начать их внедрять. Мы рекомендуем создать отдельный проект dbt, Upgrade Project, чтобы протестировать ваши изменения перед их внедрением в ваш основной проект dbt. В вашем Upgrade Project подключитесь к тому же репозиторию, который вы используете для вашего производственного проекта. На этот раз настройте настройки среды разработки на использование последней версии dbt Core. Затем создайте ветку dbt-version-upgrade, внесите соответствующие обновления в ваш проект и убедитесь, что ваш проект dbt компилируется и запускается с новой версией в IDE. Если обновление напрямую до последней версии вызывает слишком много проблем, попробуйте протестировать ваш проект итеративно на последовательных минорных версиях. Между далекими версиями dbt Core (например, 0.14 --> 1.0) прошло много лет разработки и несколько критических изменений. Вероятность возникновения проблем при обновлении между последовательными минорными версиями значительно ниже, поэтому регулярное обновление рекомендуется.

Как только ваш проект будет компилироваться и запускаться на последней версии dbt в среде разработки для вашей ветки dbt-version-upgrade, попробуйте воспроизвести одно из ваших производственных заданий, чтобы оно работало с кодом вашей ветки. Вы можете сделать это, создав новую среду развертывания для тестирования, установив пользовательскую ветку в 'ON' и ссылаясь на вашу ветку dbt-version-upgrade. Вам также нужно будет установить версию dbt в этой среде на последнюю версию dbt Core.

Настройка вашей тестовой среды

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