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

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 приведёт к ошибке.
  • Она помогает разработчикам пакетов (например, dbt-utils) убедиться, что версия dbt у пользователей совместима с пакетом.
  • Она указывает на совместимость с dbt v2 (2.0.0 и выше).
  • Она также может помочь всей вашей команде использовать одну и ту же версию dbt для локальной разработки, чтобы избежать проблем совместимости из-за изменений в поведении.

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

Каналы выпуска dbt

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

dbt Labs стремится не допускать изменений, нарушающих совместимость кода в проектах dbt, при регулярном выпуске новых версий dbt. Мы также рекомендуем следующие практики:

 Установка пакетов 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 выпустит новую мажорную версию.

Совместимость с dbt v2​

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

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

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

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

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

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

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

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

Примеры​

Следующие примеры показывают, как использовать 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 dbt v2 (v2.0.0 and higher).

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

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

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

Чтобы обозначить совместимость с dbt v2, включите 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), dbt v2 сейчас покажет предупреждение, а в будущих релизах это станет ошибкой. Вы можете обойти проверки версии, используя флаг --no-version-check.

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

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

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

Хотя вы можете ограничить запуск проекта только определённой версией dbt, мы не рекомендуем делать это для dbt v1.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