require-dbt-version
require-dbt-version: version-range | [version-range]
Определение
Вы можете использовать require-dbt-version, чтобы ограничить работу проекта только определённым диапазоном версий dbt.
При задании этой конфигурации:
- Если вы установили пакеты из dbt Packages hub, в которых указано требование
require_dbt_version, не соответствующее вашей версии dbt, выполнение команд dbt приведёт к ошибке. - Она помогает разработчикам пакетов (например, dbt-utils) убедиться, что версия dbt у пользователей совместима с пакетом.
- Она указывает на совместимость с dbt v2 (
2.0.0и выше). - Она также может помочь всей вашей команде использовать одну и ту же версию dbt для локальной разработки, чтобы избежать проблем совместимости из-за изменений в поведении.
Рекомендуется фиксировать основную (major) версию. Подробнее см. pin to a range. Если эта конфигурация не указана, проверка версии выполняться не будет.
Если вы выбираете канал релизов в dbt, чтобы регулярно получать обновления версии dbt, dbt будет игнорировать настройку require-dbt-version.
dbt Labs стремится не допускать изменений, нарушающих совместимость кода в проектах dbt, при регулярном выпуске новых версий dbt. Мы также рекомендуем следующие практики:
Кавычки в 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 выпустит новую мажорную версию.
Совместимость с dbt v2
Параметр require-dbt-version также указывает, поддерживает ли проект или пакет dbt v2 (версии 2.0.0 и выше).
- Если диапазон версий исключает
2.0.0, dbt v2 сегодня выдаст предупреждение, а в будущем релизе — ошибку, аналогично поведению dbt v1. - Вы можете обойти проверки версий, используя флаг
--no-version-check.
Подробнее о том, как задавать диапазон версий, см. раздел pin to a range.
Примеры
Следующие примеры показывают, как использовать require-dbt-version:
- Укажите минимальную версию dbt — Используйте оператор
>=, чтобы задать минимальную версию. - Задайте диапазон версий — Используйте список значений, разделённых запятой, чтобы задать верхнюю и нижнюю границы.
- Укажите конкретную требуемую версию dbt — Ограничьте запуск проекта одной конкретной версией dbt.
Указать минимальную версию dbt
Используйте оператор >=, чтобы задать нижнюю границу версии. Например:
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 dbt v2 (v2.0.0 and higher).
Помните, что наличие неограниченного верхнего предела не рекомендуется. Вместо этого ознакомьтесь с примером pin to a range, чтобы определить диапазон с нижней и верхней границей и тем самым обеспечить стабильность между релизами.
Закрепить диапазон
Используйте список, разделённый запятыми, чтобы задать верхнюю и нижнюю границы. Диапазон версий можно определить либо в виде YAML‑списка (с использованием квадратных скобок), либо в виде строки с разделителями-запятыми — оба варианта валидны и работают.
Чтобы обозначить совместимость с dbt v2, включите 2.0.0 или более позднюю версию в диапазон поддерживаемых версий. Оба следующих формата допустимы:
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), dbt v2 сейчас покажет предупреждение, а в будущих релизах это станет ошибкой. Вы можете обойти проверки версии, используя флаг --no-version-check.
Требование к конкретной версии dbt
Закрепление за конкретной версией dbt не рекомендуется, так как это ограничивает гибкость проекта и может вызвать проблемы с совместимостью, особенно с пакетами dbt. Рекомендуется закреплять за основным выпуском, используя диапазон версий (например, ">=1.0.0", "<2.0.0") для более широкой совместимости и получения обновлений.
Хотя вы можете ограничить запуск проекта только определённой версией dbt, мы не рекомендуем делать это для dbt v1.0.0 и выше.
В следующем примере проект будет работать только с dbt v1.5:
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.