# require-dbt-version

dbt\_project.yml

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

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

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

При задании этой конфигурации:

* Если вы установили пакеты из [dbt Packages hub](https://hub.getdbt.com/), в которых указано требование `require_dbt_version`, не соответствующее вашей версии dbt, выполнение команд dbt приведёт к ошибке.
* Она помогает разработчикам пакетов (например, [dbt-utils](https://github.com/dbt-labs/dbt-utils)) убедиться, что версия dbt у пользователей совместима с пакетом.
* Она указывает на [совместимость с dbt v2](#dbt-v2-compatibility) (`2.0.0` и выше).
* Она также может помочь всей вашей команде использовать одну и ту же версию dbt для локальной разработки, чтобы избежать проблем совместимости из-за изменений в поведении.

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

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

Если вы выбираете [канал релизов в dbt](https://docs.getdbt.tech/docs/dbt-versions/dbt-release-tracks.md), чтобы регулярно получать обновления версии dbt, dbt будет игнорировать настройку `require-dbt-version`.

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

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

Если вы устанавливаете dbt‑пакеты для использования в проекте — независимо от того, поддерживается ли пакет вашими коллегами или участником open source‑сообщества dbt — мы рекомендуем закреплять пакет на конкретной ревизии или границе `version`. dbt управляет этим «из коробки», *фиксируя* версию/ревизию пакетов в разработке, чтобы гарантировать предсказуемые сборки в продакшене. Подробнее см. [Predictable package installs](https://docs.getdbt.tech/reference/commands/deps.md#predictable-package-installs).

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

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

models/some\_days.sql

```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-парсером как строка. Поэтому вы должны заключить значение конфигурации в кавычки, избегая пробелов. Например:

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

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

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

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

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

Параметр `require-dbt-version` также указывает, поддерживает ли проект или пакет [dbt v2](https://docs.getdbt.tech/docs/introduction.md) (версии `2.0.0` и выше).

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

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

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

[Инструмент `dbt-autofix`](https://github.com/dbt-labs/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](#specify-a-minimum-dbt-version) — Используйте оператор `>=`, чтобы задать минимальную версию.
* [Задайте диапазон версий](#pin-to-a-range) — Используйте список значений, разделённых запятой, чтобы задать верхнюю и нижнюю границы.
* [Укажите конкретную требуемую версию dbt](#require-a-specific-dbt-version) — Ограничьте запуск проекта одной конкретной версией dbt.

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

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

dbt\_project.yml

```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](#pin-to-a-range), чтобы определить диапазон с нижней и верхней границей и тем самым обеспечить стабильность между релизами.

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

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

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

dbt\_project.yml

```yaml
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 сейчас покажет предупреждение, а в будущих релизах это станет ошибкой. Вы можете [обойти проверки версии](#disabling-version-checks), используя флаг `--no-version-check`.

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

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

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

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

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

dbt\_project.yml

```yml
require-dbt-version: "1.5.0"
```

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

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

```text
$ 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`.

```text
$ 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](https://docs.getdbt.tech/reference/global-configs/version-compatibility.md).
