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

require-dbt-version

dbt_project.yml
require-dbt-version: version-range | [version-range]

Определение​

Вы можете использовать require-dbt-version, чтобы ограничить работу проекта только определённым диапазоном версий dbt.

При установке этой конфигурации:

  • Если у вас установлены пакеты из dbt Packages hub, которые указывают require_dbt_version, не совпадающий с вашей версией, выполнение команд dbt приведёт к ошибке.
  • Это помогает мейнтейнерам пакетов (например, dbt-utils) гарантировать, что версия dbt пользователя совместима с пакетом.
  • Это сигнализирует о совместимости с dbt Fusion Engine (2.0.0 и выше).
  • Это также может помочь всей команде оставаться синхронизированной на одной версии dbt при локальной разработке, чтобы избежать проблем совместимости из‑за изменённого поведения.

Рекомендуется фиксировать основную (major) версию. Подробнее см. pin to a range. Если эта конфигурация не указана, проверка версии выполняться не будет.

dbt release tracks

Начиная с 2024 года, когда вы выбираете release track в dbt, чтобы получать регулярные обновления версии dbt, dbt будет игнорировать конфигурацию require-dbt-version.

dbt Labs придерживается принципа нулевых «ломающих» изменений для кода в dbt‑проектах — при регулярных релизах в dbt и выходе новых версий dbt Core. Мы также рекомендуем следующие best practices:

 Установка dbt‑пакетов

Если вы устанавливаете dbt‑пакеты для использования в проекте — независимо от того, поддерживается ли пакет вашими коллегами или участником open source‑сообщества dbt — мы рекомендуем закреплять пакет на конкретной ревизии или границе version. dbt управляет этим «из коробки», фиксируя версию/ревизию пакетов в разработке, чтобы гарантировать предсказуемые сборки в продакшене. Подробнее см. Predictable package installs.

 Поддержка dbt‑пакетов

Если вы поддерживаете dbt‑пакеты — будь то для коллег или для участников open source‑сообщества — мы рекомендуем писать защитный код, который проверяет наличие других необходимых пакетов и глобальных макросов. Например, если ваш пакет зависит от наличия макроса date_spine в глобальном пространстве имён dbt, вы можете написать:

models/some_days.sql
{% macro a_few_days_in_september() %}

    {% if not dbt.get('date_spine') %}
      {{ exceptions.raise_compiler_error("Expected to find the dbt.date_spine macro, but it could not be found") }}
    {% endif %}

    {{ date_spine("day", "cast('2020-01-01' as date)", "cast('2030-12-31' as date)") }}

{% endmacro %}

Кавычки в YAML​

Эта конфигурация должна быть интерполирована YAML-парсером как строка. Поэтому вы должны заключить значение конфигурации в кавычки, избегая пробелов. Например:

# ✅ Эти варианты будут работать
require-dbt-version: ">=1.0.0" # Двойные кавычки допустимы
require-dbt-version: '>=1.0.0' # Также допустимы одинарные кавычки

# ❌ Эти варианты не будут работать
require-dbt-version: >=1.0.0 # Без кавычек? Не годится
require-dbt-version: ">= 1.0.0" # Не ставьте пробелы после знаков равенства

Избегайте неограниченных верхних границ​

Мы рекомендуем задавать как нижнюю, так и верхнюю границу версии, например ">=1.0.0,<3.0.0", чтобы обеспечить стабильность при выходе новых релизов. Мы не рекомендуем использовать неограниченное значение require-dbt-version (например, ">=1.0.0"). Без верхнего ограничения проект может сломаться, когда dbt выпустит новую мажорную версию.

Совместимость с Fusion​

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

  • Если диапазон версий исключает 2.0.0, Fusion сегодня выдаст предупреждение, а в будущем релизе — ошибку, аналогично поведению dbt Core.
  • Вы можете обойти проверки версий, используя флаг --no-version-check.

Подробнее о том, как задавать диапазон версий, см. раздел pin to a range.

 Используйте dbt-autofix для обновления dbt‑проектов и пакетов

Инструмент dbt-autofix автоматически сканирует ваш dbt‑проект на наличие устаревших конфигураций и обновляет их в соответствии с последними лучшими практиками, а также подготавливает проект к миграции на Fusion.

Во время работы dbt-autofix:

  • Проверяет ваш packages.yml, чтобы определить, какие пакеты можно автоматически обновить.
  • Ищет пакеты, в которых указано require-dbt-version: 2.0.0 или выше (что указывает на поддержку Fusion).
  • Обновляет такие пакеты до минимальной версии, которая поддерживает Fusion.

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

Примеры​

Следующие примеры показывают, как использовать require-dbt-version:

Указать минимальную версию dbt​

Используйте оператор >=, чтобы задать нижнюю границу версии. Например:

dbt_project.yml
require-dbt-version: ">=1.9.0" # project will only work with versions 1.9 and higher.
require-dbt-version: ">=2.0.0" # project will only work with the dbt Fusion engine (v2.0.0 and higher).

Помните, что наличие неограниченного верхнего предела не рекомендуется. Вместо этого ознакомьтесь с примером pin to a range, чтобы определить диапазон с нижней и верхней границей и тем самым обеспечить стабильность между релизами.

Закрепить диапазон​

Используйте список, разделённый запятыми, чтобы задать верхнюю и нижнюю границы. Диапазон версий можно определить либо в виде YAML‑списка (с использованием квадратных скобок), либо в виде строки с разделителями-запятыми — оба варианта валидны и работают.

Чтобы указать совместимость с dbt Fusion Engine, включите 2.0.0 или более высокую версию в ваш диапазон версий. Оба следующих формата являются допустимыми:

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

# or

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

Если ваш диапазон версий исключает 2.0.0 (например, >=1.6.0,<2.0.0), Fusion сейчас покажет предупреждение, а в будущих релизах это станет ошибкой. Вы можете обойти проверки версии, используя флаг --no-version-check.

Требование к конкретной версии dbt​

Не рекомендуется

Закрепление за конкретной версией dbt не рекомендуется, так как это ограничивает гибкость проекта и может вызвать проблемы с совместимостью, особенно с пакетами dbt. Рекомендуется закреплять за основным выпуском, используя диапазон версий (например, ">=1.0.0", "<2.0.0") для более широкой совместимости и получения обновлений.

Хотя вы можете ограничить запуск своего проекта только с конкретной версией dbt Core, мы не рекомендуем делать это для dbt Core версии 1.0.0 и выше.

В следующем примере проект будет работать только с dbt v1.5:

dbt_project.yml
require-dbt-version: "1.5.0"

Недопустимые версии dbt​

Если версия dbt, используемая для вызова проекта, не соответствует указанной require-dbt-version в проекте или любом из включенных пакетов, dbt немедленно завершится с ошибкой:

$ dbt compile
Running with dbt=1.5.0
Encountered an error while reading the project:
Runtime Error
  This version of dbt is not supported with the 'my_project' package.
    Installed version of dbt: =1.5.0
    Required version of dbt for 'my_project': ['>=1.6.0', '<2.0.0']
  Check the requirements for the 'my_project' package, or run dbt again with --no-version-check

Отключение проверки версий​

Чтобы подавить ошибки из-за несовместимых версий dbt, используйте флаг --no-version-check при запуске dbt run.

$ dbt run --no-version-check
Running with dbt=1.5.0
Found 13 models, 2 tests, 1 archives, 0 analyses, 204 macros, 2 operations....

Подробности использования см. в разделе global configs.

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

0
Loading