require-dbt-version

dbt_project.yml

require-dbt-version: version-range | [version-range]

Определение

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

Когда вы устанавливаете эту конфигурацию, dbt отправляет полезное сообщение об ошибке любому пользователю, который пытается запустить проект с неподдерживаемой версией dbt. Это может быть полезно для сопровождающих пакетов (таких как dbt-utils), чтобы гарантировать, что версия dbt пользователя совместима с пакетом. Установка этой конфигурации также может помочь всей вашей команде оставаться синхронизированной на одной версии dbt для локальной разработки, чтобы избежать проблем с совместимостью из-за измененного поведения.

Если эта конфигурация не указана, проверка версии не будет выполняться.

dbt Cloud release tracks

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

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

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

Если вы устанавливаете пакеты dbt для использования в вашем проекте, будь то пакет, поддерживаемый вашими коллегами или членом сообщества с открытым исходным кодом dbt, мы рекомендуем закрепить пакет на определенной ревизии или границе version. Начиная с версии v1.7, dbt управляет этим из коробки, блокируя версию/ревизию пакетов в разработке, чтобы гарантировать предсказуемые сборки в производстве. Чтобы узнать больше, обратитесь к Предсказуемая установка пакетов.

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

Если вы поддерживаете пакеты dbt, будь то от имени ваших коллег или членов сообщества с открытым исходным кодом, мы рекомендуем писать защитный код, который проверяет наличие других необходимых пакетов и глобальных макросов. Например, если ваш пакет зависит от наличия макроса 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" # Не ставьте пробелы после знаков равенства

Примеры

Указание минимальной версии dbt

Используйте оператор >= для минимальной границы. В следующем примере этот проект будет работать с любой версией dbt, большей или равной 1.0.0.

dbt_project.yml

require-dbt-version: ">=1.0.0"

Закрепление за диапазоном

Используйте список, разделенный запятыми, для верхней и нижней границы. В следующем примере этот проект будет работать с dbt 1.x.x.

dbt_project.yml

require-dbt-version: [">=1.0.0", "<2.0.0"]

ИЛИ

dbt_project.yml

require-dbt-version: ">=1.0.0,<2.0.0"

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

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

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

Хотя вы можете ограничить ваш проект для работы только с точной версией dbt Core, мы не рекомендуем это для dbt Core 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=0.21.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: =0.21.0
    Required version of dbt for 'my_project': ['>=1.0.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=0.21.0
Found 13 models, 2 tests, 1 archives, 0 analyses, 204 macros, 2 operations....

См. глобальные конфигурации для деталей использования.

Рекомендации

• Это рекомендуемая конфигурация
• До версии v1, вы должны закрепить требуемую версию dbt за минорным выпуском. После v1, вы должны закрепить за основным выпуском (см. выше пример).