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

Обновление до Fusion, часть 1: Подготовка к обновлению

Это руководство поможет вам подготовиться к обновлению «на месте» с dbt Core на движок dbt Fusion в платформе dbt.

Назад к гайдам
dbt Fusion engine
dbt platform
Upgrade
Intermediate
Menu

    Введение​

    private preview

    dbt Fusion Engine доступен в рамках закрытого превью для всех тарифных планов аккаунтов dbt platform. Компания dbt Labs включает Fusion только для аккаунтов, в которых есть проекты, соответствующие требованиям. Выполнение шагов, описанных в этом руководстве, не гарантирует, что вы получите доступ к Fusion.

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

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

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

    Это руководство описывает подготовку к обновлению до dbt Fusion Engine и предназначено для клиентов, которые уже используют dbt platform с версией dbt Core. Если вы только начинаете работать с dbt, ознакомьтесь с нашими руководствами для быстрого старта.

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

    • Вы используете аккаунт dbt platform на любом тарифе.
    • У вас есть лицензия разработчика.
    • У вас есть необходимые права доступа для редактирования проектов.
    • Ваш проект использует адаптер, поддерживаемый Fusion:
       BigQuery
       Databricks
      • Служебная учетная запись / токен пользователя
      • Нативный OAuth
       Redshift
      • Имя пользователя / пароль
      • Профиль IAM
       Snowflake
      • Имя пользователя / пароль
      • Нативный OAuth
      • Внешний OAuth
      • Пара ключей с использованием современного метода PKCS#8
      • MFA
    Обновление первого проекта

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

    Обновление до последней версии dbt Core​

    Перед обновлением до Fusion вам необходимо перевести все окружения на трек релизов Latest для dbt Core. Трек Latest включает все функции и инструменты, необходимые для подготовки к Fusion. Он обеспечивает наиболее плавный процесс обновления, проверяя, что ваш проект не зависит от устаревшего поведения.

    Тестируйте перед деплоем

    Всегда тестируйте обновления версий сначала в разработке. Используйте функцию Override dbt version, чтобы безопасно попробовать трек Latest, не затрагивая команду или продакшн-запуски.

    Шаг 1: Тестирование в разработке (с использованием override)​

    Протестируйте трек релизов Latest для своего аккаунта, не меняя окружение для всей команды:

    1. Нажмите на имя своего аккаунта в левом сайдбаре и выберите Account settings.
    2. В сайдбаре выберите Credentials и выберите проект.
    3. В боковой панели нажмите Edit и прокрутите до User development settings.
    4. В выпадающем списке dbt version выберите Latest и нажмите Save.
    Переопределение версии dbt в настройках аккаунтаПереопределение версии dbt в настройках аккаунта
    1. Запустите Studio IDE или Cloud CLI и протестируйте свои обычные процессы разработки.
    2. Убедитесь, что override активен, выполнив любую команду dbt и проверив System Logs. В первой строке должно быть указано Running with dbt= и выбранная версия. Если номер версии v1.11 или выше, вы на верном пути к готовности к Fusion.

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

    Шаг 2: Обновление окружения разработки​

    После успешного тестирования индивидуального окружения разработки с override обновите окружение разработки для всего проекта (обязательно предупредите команду):

    1. Перейдите в раздел Environments в настройках проекта.
    2. Выберите окружение Development и нажмите Edit.
    3. В выпадающем списке dbt version выберите Latest.
    4. Нажмите Save, чтобы применить изменения.
    Обновление окружения разработки до трека Latest dbt CoreОбновление окружения разработки до трека Latest dbt Core
    Удалите персональный override

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

    Шаг 3: Обновление staging и pre-production​

    Если в вашей организации есть окружения staging или pre-production, обновите их перед продакшном:

    1. Перейдите в Environments и выберите окружение staging/pre-production.
    2. Нажмите Edit и выберите Latest в выпадающем списке dbt version.
    3. Нажмите Save.
    4. Запускайте джобы в этом окружении в течение нескольких дней, чтобы убедиться, что всё работает корректно.

    Это добавляет финальный уровень проверки перед обновлением продакшн-окружений.

    Шаг 4: Обновление продакшн-окружения​

    После проверки в staging (или в development, если staging отсутствует) обновите продакшн-окружение:

    1. Перейдите в Environments и выберите окружение Production.
    2. Нажмите Edit и выберите Latest в выпадающем списке dbt version.
    3. Нажмите Save, чтобы применить изменения.
    4. Отслеживайте первые несколько продакшн-запусков, чтобы убедиться, что всё выполняется успешно.

    Шаг 5: Обновление jobs​

    Хотя в большинстве случаев версия dbt определяется окружениями, некоторые старые конфигурации jobs могут содержать override версии. Просмотрите ваши jobs и обновите те, в которых явно указана версия dbt, чтобы они использовали трек Latest, заданный в окружении.

    Устранение всех предупреждений об устаревании​

    Fusion применяет строгую валидацию и не принимает устаревший код, который в dbt Core сейчас лишь вызывает предупреждения. Перед обновлением до Fusion необходимо устранить все такие предупреждения. К счастью, инструмент autofix в Studio IDE может автоматически исправить большинство распространённых устареваний.

    Расширение VS Code

    В этом руководстве описаны шаги по устранению предупреждений об устаревании, не покидая dbt platform. Если вы предпочитаете работать локально в VS Code или Cursor, вы можете запустить autofix с помощью нашего расширения dbt для VS Code. Подробнее см. руководство по установке.

    Что обрабатывает инструмент autofix​

    Инструмент autofix может автоматически исправлять многие устаревания, включая:

    • Перенос пользовательских конфигураций в словарь meta
    • Исправление дублирующихся ключей YAML
    • Коррекцию нераспознанных свойств ресурсов
    • Обновление устаревших конфигурационных паттернов

    Полный список поддерживаемых устареваний см. в autofix readme.

    Совместимость пакетов с Fusion

    Помимо устареваний, инструмент autofix пытается обновить пакеты до минимальной версии, совместимой с Fusion. Подробнее см. в разделе поддержка пакетов.

    Шаг 1: Создание новой ветки​

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

    1. Перейдите в Studio IDE, нажав Studio в левом меню.
    2. Откройте панель Version control (иконка git-ветки) в левом сайдбаре.
    3. Нажмите Create branch и задайте описательное имя, например fusion-deprecation-fixes.
    4. Нажмите Create, чтобы переключиться на новую ветку.
    Сохраните изменения перед autofix

    Инструмент autofix изменяет файлы проекта. Убедитесь, что все текущие изменения закоммичены или сохранены, чтобы избежать потери данных.

    Шаг 2: Запуск инструмента autofix​

    Теперь вы готовы просканировать проект и автоматически исправить предупреждения об устаревании:

    1. Нажмите на меню с тремя точками в правом нижнем углу Studio IDE.
    2. Выберите Check & fix deprecations.
    Доступ к меню опций Studio IDEДоступ к меню опций Studio IDE

    Инструмент запускает dbt parse --show-all-deprecations --no-partial-parse для выявления всех устареваний в проекте. В зависимости от размера проекта это может занять некоторое время.

    1. После завершения парсинга просмотрите результаты в панели Command history в левом нижнем углу.
    Просмотр истории команд и результатов устареванийПросмотр истории команд и результатов устареваний

    Шаг 3: Просмотр и применение autofix​

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

    1. В панели Command history просмотрите список предупреждений об устаревании.
    2. Нажмите кнопку Autofix warnings.
    Запуск Autofix warnings для автоматического устранения устареванийЗапуск Autofix warnings для автоматического устранения устареваний
    1. В диалоге Proceed with autofix ознакомьтесь с предупреждением и нажмите Continue.
    Подтверждение операции autofixПодтверждение операции autofix

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

    1. После завершения появится сообщение об успехе. Нажмите Review changes.
    Autofix завершёнAutofix завершён

    Шаг 4: Проверка изменений​

    Проверьте изменения, внесённые инструментом autofix, чтобы убедиться в их корректности:

    1. Откройте панель Version control, чтобы увидеть все изменённые файлы.
    2. Откройте отдельные файлы для просмотра конкретных изменений.
    3. Обратите внимание на файлы с перенесёнными конфигурациями, исправленными свойствами или обновлённым синтаксисом.
    4. При необходимости внесите дополнительные ручные правки.

    Шаг 5: Коммит изменений​

    Когда вы убедитесь, что изменения корректны, закоммитьте их в ветку:

    1. В панели Version control добавьте понятное сообщение коммита, например: "Fix deprecation warnings for Fusion upgrade".
    2. Нажмите Commit and sync, чтобы сохранить изменения.

    Шаг 6: Устранение оставшихся устареваний​

    Если инструмент autofix сообщает о предупреждениях, которые не удалось исправить автоматически:

    1. Просмотрите сообщения в панели Command history. В каждом предупреждении указан путь к файлу и номер строки.
    2. Внесите изменения вручную в соответствии с рекомендациями:
      • Пользовательские параметры следует перенести в конфигурацию meta.
      • Устаревшие свойства необходимо заменить на актуальные аналоги.
      • Используйте соответствующие руководства по обновлению версий для детальных инструкций.
    3. После ручных правок снова запустите Check & fix deprecations, чтобы убедиться, что все предупреждения устранены.
    4. Закоммитьте изменения.

    Шаг 7: Слияние с основной веткой​

    После устранения всех устареваний:

    1. Создайте pull request в вашем git-провайдере для слияния изменений.
    2. Проведите командный код-ревью.
    3. Смерджите PR в основную ветку разработки.
    4. Убедитесь, что изменения задеплоены во все окружения перед обновлением до Fusion.

    Проверка и обновление dbt-пакетов​

    Сначала запустите autofix

    Этот раздел содержит инструкции по ручному обновлению пакетов. Мы рекомендуем сначала использовать инструмент autofix.

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

    Пакеты dbt расширяют функциональность проекта, но они должны быть совместимы с Fusion. Большинство популярных пакетов от dbt Labs (таких как dbt_utils и dbt_project_evaluator), а также многие пакеты сообщества уже поддерживают Fusion. Перед обновлением убедитесь в совместимости пакетов и обновите их до последних версий. Обращайте внимание на пакеты, поддерживающие версию 2.0.0, или уточняйте у мейнтейнеров при сомнениях.

    Что делать, если пакет не совместим?

    Если критически важный пакет пока не поддерживает Fusion:

    • Уточните у мейнтейнера планы по поддержке.
    • Создайте issue с запросом поддержки Fusion.
    • Рассмотрите возможность внести изменения самостоятельно.
    • Попробуйте использовать пакет — возможно, несовместимая часть не влияет на ваш проект.

    Сообщения о совместимости пакетов​

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

    Предупреждения Fusion и логи dbt-autofix могут содержать разные сообщения о совместимости пакетов.

    Если вы используете dbt-autofix при обновлении до Fusion в Studio IDE или в расширении dbt для VS Code, вы можете увидеть различающиеся сообщения о совместимости пакетов между dbt-autofix и предупреждениями Fusion.

    Вот почему это происходит:

    • Предупреждения Fusion формируются на основе параметра пакета require-dbt-version и того, содержит ли require-dbt-version версию 2.0.0.
    • Некоторые пакеты уже совместимы с Fusion, даже если их мейнтейнеры ещё не обновили значение require-dbt-version.
    • dbt-autofix знает о таких совместимых пакетах и не пытается обновлять пакет, если он уже считается совместимым.

    Это означает, что даже если вы видите предупреждение Fusion для пакета, который dbt-autofix определяет как совместимый, вам не нужно менять этот пакет.

    Расхождение в сообщениях является временным и будет устранено по мере внедрения и распространения улучшенного механизма определения совместимости из dbt-autofix в предупреждениях Fusion.

    Ниже приведён пример предупреждения Fusion в Studio IDE, которое сообщает, что пакет не совместим с Fusion, тогда как dbt-autofix указывает, что он совместим:

    dbt1065: Package 'dbt_utils' requires dbt version [>=1.30,<2.0.0], but current version is 2.0.0-preview.72. This package may not be compatible with your dbt version. dbt(1065) [Ln 1, Col 1]

    Шаг 1: Просмотр текущих пакетов​

    Определите, какие пакеты используются в проекте:

    1. В Studio IDE откройте корневую директорию проекта.
    2. Найдите файл packages.yml или dependencies.yml.
    3. Просмотрите список пакетов и их текущие версии.

    Пример содержимого файла:

    packages:
      - package: dbt-labs/dbt_utils
        version: 1.0.0
      - package: dbt-labs/codegen
        version: 0.9.0

    Шаг 2: Проверка совместимости и поиск последних версий пакетов​

    Используйте dbt package hub, чтобы найти проверенные пакеты, совместимые с Fusion, убедившись, что параметр require-dbt-version включает 2.0.0 или выше. Дополнительную информацию см. в разделе поддержка пакетов.

    Для пакетов, не совместимых с Fusion:

    • Перейдите в GitHub-репозиторий пакета.
    • Проверьте README или последние релизы на предмет совместимости с Fusion.
    • Изучите issues и обсуждения, связанные с поддержкой Fusion.

    Для каждого пакета определите последнюю доступную версию:

    • Посетите dbt Hub для пакетов, размещённых там.
    • Для пакетов с GitHub проверьте страницу релизов репозитория.
    • Зафиксируйте номер последней версии для каждого пакета.

    Для пакетов из Hub можно использовать диапазоны версий, чтобы оставаться актуальными:

    packages:
      - package: dbt-labs/dbt_utils
        version: [">=1.0.0", "<3.0.0"]  # Получает последнюю версию 1.x или 2.x

    Шаг 3: Обновление версий пакетов​

    Обновите файл packages.yml или dependencies.yml, указав последние совместимые версии:

    1. В Studio IDE откройте packages.yml или dependencies.yml.

    2. Обновите версии каждого пакета до последних совместимых.

    3. Сохраните файл.

      До обновления:

      packages:
      - package: dbt-labs/dbt_utils
         version: 0.9.6
      - package: dbt-labs/codegen
         version: 0.9.0

      После обновления:

      packages:
      - package: dbt-labs/dbt_utils
         version: [">=1.0.0", "<2.0.0"]
      - package: dbt-labs/codegen
         version: [">=0.12.0", "<1.0.0"]

    Шаг 4: Установка обновлённых пакетов​

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

    1. В командной строке Studio IDE выполните: 
      dbt deps --upgrade

    Флаг --upgrade гарантирует установку последних версий в рамках указанных диапазонов и обновляет файл package-lock.yml.

    1. Проверьте вывод команды и убедитесь, что все пакеты установлены успешно.
    2. Убедитесь, что файл package-lock.yml обновился и содержит новые версии пакетов.
    О файле package-lock.yml

    Файл package-lock.yml фиксирует версии пакетов для воспроизводимых сборок. Мы рекомендуем коммитить этот файл в систему контроля версий, чтобы вся команда использовала одинаковые версии пакетов.

    Шаг 5: Тестирование проекта с обновлёнными пакетами​

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

    1. Запустите часть моделей для базовой проверки:

      dbt run --select tag:daily

    2. Запустите тесты, чтобы выявить возможные изменения поведения:

      dbt test

    3. При возникновении проблем:

      • Изучите changelog пакета на предмет breaking changes
      • Адаптируйте код под новое поведение пакета
      • При необходимости временно зафиксируйте более старую совместимую версию

    Шаг 6: Коммит обновлений пакетов​

    После успешной проверки обновлённых пакетов:

    1. В панели Version control добавьте в staging:

      • packages.yml или dependencies.yml
      • package-lock.yml

    2. Добавьте сообщение коммита, например "Upgrade dbt packages for Fusion compatibility".

    3. Нажмите Commit and sync.

    Проверка известных ограничений Fusion​

    Хотя Fusion поддерживает большую часть возможностей dbt Core, некоторые функции имеют ограниченную поддержку или всё ещё находятся в разработке. Перед обновлением важно проанализировать проект и выявить такие особенности, чтобы заранее спланировать действия — будь то временный отказ от некритичных функций, использование обходных решений или ожидание появления нужных возможностей.

    Fusion активно развивается

    Многие ограничения устраняются по мере приближения Fusion к General Availability. Вы можете отслеживать прогресс по функциям через GitHub milestones dbt-fusion и следить за обновлениями в Fusion Diaries.

    Шаг 1: Ознакомьтесь с таблицей ограничений​

    Начните с понимания того, какие функции имеют ограниченную или отсутствующую поддержку в Fusion:

    Перейдите на страницу поддерживаемых возможностей Fusion и изучите таблицу ограничений.

    Распространённые ограничения включают:

    • Python-модели: пока не поддерживаются (Fusion не может парсить Python для извлечения зависимостей)
    • Microbatch incremental strategy: пока недоступна
    • Уведомления на уровне моделей: работают уведомления на уровне jobs, но не моделей
    • Разработка Semantic Layer: активная разработка должна оставаться на dbt Core
    • SQLFluff linting: пока не интегрирован (линтинг будет встроен напрямую в Fusion)

    Шаг 2: Поиск ограниченных функций в проекте​

    Проверьте, использует ли ваш проект функции с ограниченной поддержкой. Например:

    1. Проверка Python-моделей:

      • В Studio IDE просмотрите директорию models/
      • Найдите файлы с расширением .py
      • При их наличии потребуется либо удалить их, либо оставить эти модели на dbt Core

    2. Просмотрите dbt_project.yml:

      • Найдите настройки store_failures
      • Проверьте пользовательские материализации, отличные от view, table и incremental
      • Изучите конфигурации warn-error и warn-error-options

    3. Проверьте конфигурации jobs:

      • Найдите jobs с флагом --fail-fast
      • Определите jobs с --store-failures
      • Обратите внимание на Advanced CI workflows с "compare changes"

    4. Проверьте настройки governance моделей:

      • Найдите модели с заданным deprecation_date
      • Учтите, что они могут пока не генерировать предупреждения в Fusion

    Шаг 3: Оценка влияния​

    Для каждого ограничения определите его критичность:

    • Критичные функции: без них проект не может работать:

      • Если Python-модели необходимы, возможно, стоит подождать или переписать их на SQL
      • При активной разработке Semantic Layer продолжайте использовать dbt Core

    • Желательные функции: улучшают процессы, но не блокируют работу:

      • Уведомления на уровне моделей можно временно заменить уведомлениями на уровне jobs
      • SQLFluff можно продолжать запускать в CI с dbt Core

    • Минимальное влияние: функции, для которых легко найти обход:

      • Флаг --fail-fast можно временно убрать
      • --store-failures можно временно отключить

    Шаг 4: Формирование плана действий​

    На основе оценки решите, как поступать с каждым ограничением:

    • Удалить некритичные функции:

      Временно отключите функции, без которых можно обойтись:

      До (в конфигурации модели):

      {{ config(
        materialized='incremental',
        store_failures=true
      ) }}

      После:

      {{ config(
        materialized='incremental'
      ) }}

    • Реализовать обходные решения для функций с низким влиянием:

      • Использовать уведомления на уровне jobs вместо модельных
      • Запускать SQLFluff отдельно в CI с dbt Core
      • Использовать стандартный state selection вместо более гранулярных подвыборок

    Шаг 5: Документирование результатов​

    Зафиксируйте ограничения, влияющие на ваш проект:

    1. В Studio IDE создайте документ (например, FUSION_MIGRATION.md) со списком:

      • Функций проекта, которые Fusion пока не полностью поддерживает
      • Затронутых моделей или jobs
      • Стратегии обхода для каждого ограничения
      • Ссылок на GitHub issues для отслеживания статуса функций

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

    Шаг 6: Отслеживание прогресса функций​

    Оставайтесь в курсе появления необходимых возможностей:

    1. Подпишитесь на соответствующие GitHub issues для нужных функций (ссылки есть в таблице ограничений).
    2. Следите за обновлениями в Fusion Diaries.
    3. Проверяйте milestones dbt-fusion, чтобы понимать сроки релизов.

    Что дальше?​

    После выявления и учёта ограничений вы завершили все подготовительные шаги. Ваш проект готов к обновлению до Fusion!

    Переходите к Части 2: Переход на Fusion

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

    0