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

Гайд по обновлению пакетов для Fusion

Узнайте, как обновить ваши пакеты, чтобы они были совместимы с движком dbt Fusion.

Назад к гайдам
dbt Fusion engine
Advanced
Menu

    Введение​

    Спасибо, что вы являетесь частью сообщества dbt package hub и поддерживаете пакеты! Ваша работа делает экосистему dbt возможной и помогает тысячам команд повторно использовать проверенные модели и макросы для более быстрой и надёжной аналитики.

    Это руководство поможет вам обновить ваши dbt‑пакеты, чтобы они были совместимы с Fusion. Пакет, совместимый с Fusion:

    • Поддерживает версию dbt Fusion Engine 2.0.0
    • Использует конфигурацию require-dbt-version для указания совместимости в dbt package hub
    • Соответствует последней JSON‑схеме, представленной в dbt Core v1.10.0

    В этом руководстве мы рассмотрим:

    • Обновление пакета для совместимости с Fusion
    • Тестирование пакета с Fusion
    • Обновление конфигурации require-dbt-version с добавлением 2.0.0
    • Обновление README с указанием совместимости пакета с Fusion

    Для кого это руководство?​

    Это руководство предназначено для любого мейнтейнера dbt‑пакетов, например dbt-utils, который хочет обновить свой пакет для совместимости с Fusion. Обновление пакета гарантирует, что пользователи получают актуальную версию, пакет остаётся надёжным в dbt package hub, а пользователи получают доступ к новым возможностям и исправлениям ошибок.

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

    В этом руководстве предполагается, что вы используете командную строку и Git для внесения изменений в репозиторий пакета. Если вы хотите создать новый пакет с нуля, рекомендуем начать с руководства по созданию dbt‑пакетов.

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

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

    • Мейнтейнер dbt‑пакета — вы поддерживаете пакет в dbt package hub или планируете создать новый.
    • Установлен dbt-autofix — установите dbt-autofix, чтобы автоматически обновлять YAML‑файлы пакета в соответствии с последними изменениями dbt и лучшими практиками. Мы рекомендуем использовать/установить uv/uvx для запуска инструмента.
    • Доступ к репозиторию — вам понадобятся права на создание ветки и выпуск обновлений/новой версии пакета. После обеспечения совместимости с Fusion потребуется создать новый тег версии.
    • Установка или тестовое окружение Fusion — вы можете использовать Fusion локально (через бинарь dbtf) или в CI‑пайплайне для проверки совместимости.
    • Работа с CLI и Git — вы уверенно используете командную строку и Git для обновления репозитория.

    Обновите пакет​

    В этом разделе описано, как обновить пакет для совместимости с Fusion:

    Если вы готовы начать, давайте приступим!

    Запустите dbt-autofix​

    1. Перед началом убедитесь, что dbt-autofix установлен. Если нет, выполните команду uvx dbt-autofix. Дополнительные варианты установки см. в официальной документации dbt-autofix.

    2. В репозитории вашего dbt‑пакета создайте рабочую ветку. Например:

      git checkout -b fusion-compat

    3. Запустите dbt-autofix deprecations в директории пакета, чтобы автоматически обновить код пакета и переписать YAML‑файлы в соответствии с последней JSON‑схемой:

      dbt-autofix deprecations

    Протестируйте пакет с Fusion​

    Теперь, когда вы запустили dbt-autofix, протестируйте пакет с Fusion, чтобы убедиться в совместимости перед обновлением конфигурации require-dbt-version. Дополнительную информацию о возможных ограничениях см. в документации по ограничениям Fusion. Вы можете протестировать пакет двумя способами:

    Запуск ваших интеграционных тестов с Fusion​

    Если в пакете есть папка integration_tests/ (например, как в dbt-utils), выполните следующие шаги:

    1. Перейдите в папку (cd integration_tests) для запуска тестов. Если папки integration_tests/ нет, вы можете создать её или перейти в директорию с тестами.
    2. Запустите тесты с Fusion, выполнив команду dbtf build (или другой доступный в вашем окружении исполняемый файл Fusion).
    3. Если ошибок нет, ваш пакет, вероятно, поддерживает Fusion, и вы готовы обновить require-dbt-version. Если есть ошибки, их необходимо исправить перед обновлением require-dbt-version.

    Ручная валидация вашего пакета​

    Если в пакете нет интеграционных тестов, выполните следующие шаги:

    1. Создайте небольшой dbt‑проект, совместимый с Fusion, который устанавливает ваш пакет и содержит файл packages.yml или dependencies.yml.
    2. Запустите проект с Fusion, используя команду dbtf run.
    3. Убедитесь, что модели собираются успешно и нет предупреждений. При наличии ошибок или предупреждений их нужно устранить. Если проблемы сохраняются, обратитесь за помощью в канал #package-ecosystem в Slack.

    Обновление require-dbt-version​

    Обновляйте конфигурацию require-dbt-version только после тестирования и подтверждения, что пакет работает с Fusion.

    1. Обновите require-dbt-version в dbt_project.yml, добавив 2.0.0. Мы рекомендуем использовать диапазон версий для обеспечения стабильности:

      require-dbt-version: [">=1.10.0,<3.0.0"]

      Это указывает, что пакет поддерживает как dbt Core, так и Fusion. dbt Labs использует эти метаданные релиза, чтобы отметить ваш пакет бейджем совместимости с Fusion в dbt package hub. Пакеты без этих метаданных не отображают бейдж совместимости с Fusion.

    2. Закоммитьте и отправьте изменения в репозиторий.

    Публикация нового релиза​

    1. После коммита и отправки изменений опубликуйте новый релиз пакета, смёрджив ветку в main (или в основную ветку, используемую в вашем репозитории).
    2. Обновите README, указав, что пакет совместим с Fusion.
    3. (Необязательно) Анонсируйте обновление в канале #package-ecosystem в dbt Slack.
    CI Fusion testing

    По возможности добавьте шаг в CI‑пайплайн, который запускает dbtf build или эквивалент, чтобы обеспечить постоянную совместимость с Fusion.

    Теперь ваш пакет совместим с Fusion, и dbt package hub отражает эти изменения. В итоге вы:

    • Создали ветку для обеспечения совместимости с Fusion
    • Запустили dbt-autofix deprecations
    • Проверили, закоммитили и протестировали изменения
    • Обновили require-dbt-version: [">=1.10.0,<3.0.0"], включив 2.0.0
    • Опубликовали новый релиз
    • Анонсировали обновление (необязательно)
    • Отпраздновали получение бейджа совместимости с Fusion 🎉

    Финальные мысли​

    Теперь, когда вы обновили пакет для совместимости с Fusion, пользователи могут использовать его вместе с Fusion! 🎉

    Обновляясь уже сейчас, вы обеспечиваете более плавный пользовательский опыт, прокладываете путь для следующего поколения dbt‑проектов и помогаете Fusion достичь полной стабильности.

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

    И напоследок — спасибо за вклад в развитие экосистемы dbt — по одному пакету за раз 💜.

    Часто задаваемые вопросы​

    Ниже приведены ответы на часто задаваемые вопросы об обновлении пакета для совместимости с Fusion.

     Почему нужно обновлять наш пакет?

    Fusion и dbt Core v1.10+ используют один и тот же новый слой авторинга. Указание поддержки 2.0.0 в конфигурации require-dbt-version гарантирует совместимость пакета с обоими движками.

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

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

     Как тестировать Fusion в CI?

    Добавьте отдельную задачу, которая устанавливает Fusion (dbtf) и запускает dbtf build. См. этот PR в качестве рабочего примера.

    Это необходимо, чтобы любые изменения в пакете оставались совместимыми с Fusion.

     Как пользователи узнают, что мой пакет совместим с Fusion?

    Пользователи могут определить совместимость пакета с Fusion, проверив наличие версии 2.0.0 или выше в диапазоне require-dbt-version.

    Пакеты, совместимые с Fusion, также автоматически отображают соответствующий бейдж в dbt package hub на основе метаданных пакета и требований к версиям.

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

    0