Обновление проекта

В данном разделе представлена информация по обновлению программного обеспечения, используемого в проекте.

Процесс обновления dbt Core

В мире данных инструменты развиваются стремительно. Команда dbt Labs регулярно выпускает минорные обновления своего программного обеспечения (например, 1.10, 1.11, 1.12), в которых добавляются новые макросы, оптимизация парсинга, расширенные возможности тестирования и многое другое.

Обновление dbt Core - это не просто запуск одной команды в терминале, а все-таки полноценный инженерный процесс, который затрагивает окружение, зависимости проекта и конфигурационные файлы.

Архитектура dbt (начиная с версии 1.8) полностью разделена на два независимых слоя:

1. Ядро (dbt-core) - транслятор Jinja/SQL и строитель графа зависимостей (DAG).

2. Адаптер БД (например, dbt-postgres) - драйвер, переводящий макросы dbt в диалект СУБД.

Поскольку ядро и адаптеры теперь полностью изолированы друг от друга, они живут в собственных релизных циклах. Ситуация, когда минорные версии движка и плагина не совпадают (например, core имеет версию 1.11.x, а адаптер — 1.10.x), является абсолютно нормальной и официально поддерживаемой.

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

Шаг 1. Аудит текущего состояния окружения

Перед началом любых манипуляций необходимо зафиксировать текущую конфигурацию. Активируйте виртуальное окружение python (venv) в терминале и выполните команду:

dbt --version

После выполнения указанной команды будет выведена версия ядра и адаптера (плагина). Но не всегда всё идёт гладко. Рассмотрим пример вывода, требующий внимания:

Core:
  - installed: 1.11.2

  The latest version of dbt-core could not be determined!
  Make sure that the following URL is accessible:
  https://pypi.org/pypi/dbt-core/json

Plugins:
  - postgres: 1.10.0 - Could not determine latest version

В этом логе видна не только информация по версиям, но и проблема, вызванная сетевой ошибкой PyPI. Система не смогла проверить актуальные версии из-за сетевых ограничений. В качестве решения перед обновлением убедитесь, что ваша машина имеет доступ к интернету (при необходимости включите VPN или настройте прокси-сервер).

Шаг 2. Изменение версии dbt в Python-окружении (pip)

В зависимости от задач инфраструктуры вашего проекта, выберите один из трех универсальных сценариев управления пакетным менеджером.

Сценарий А. Жесткая фиксация (Pinning Upgrade)

Используется, если вам необходимо перевести проект строго на определенные релизы ядра и адаптера (например, протестированные вашей командой):

# Явно указываем целевые версии для обоих независимых пакетов
pip install --upgrade dbt-core==<версия_ядра> dbt-<имя_адаптера>==<версия_адаптера>

Пример для PostgreSQL:

pip install --upgrade dbt-core==1.10.2 dbt-postgres==1.10.2

Сценарий Б. Плавающее обновление (Floating Upgrade)

Используется, если вы хотите получить самые свежие стабильные возможности движка (core), не дожидаясь, пока разработчики адаптера базы данных выпустят обновление с аналогичным номером версии:

# Пакетный менеджер заберет самые актуальные стабильные версии из PyPI
pip install --upgrade dbt-core dbt-<имя_адаптера>

Пример для PostgreSQL:

pip install --upgrade dbt-core dbt-postgres

Сценарий В. Безопасный откат (Clean Downgrade)

Простая установка старых версий поверх новых (например, при обнаружении багов в свежем релизе) может оставить в окружении "хвосты" конфликтующих python-зависимостей. Откат всегда должен производиться через пересоздание среды:

Удалите текущую папку виртуального окружения:

rm -rf venv

Создайте и активируйте чистую среду:

python -m venv venv
source venv/bin/activate  # Для macOS/Linux
# ИЛИ
.\venv\Scripts\activate   # Для Windows

С нуля установите ядро и адаптер требуемых версий:

pip install dbt-core==<целевая_версия> dbt-<имя_адаптера>==<целевая_версия>

Пример для PostgreSQL:

pip install --upgrade dbt-core==1.11.2 dbt-postgres==1.10.0

Шаг 3. Защита конфигурации проекта

Чтобы изменения не остались только на вашем локальном компьютере, и вся команда (больше подходит для продуктивного решения, а не учебного проекта) работали в идентичных условиях, зафиксируйте требования к среде в коде. Для этого используется параметр require-dbt-version, который является предохранителем в конфигурационном файле dbt_project.yml. Он принудительно останавливает работу dbt, если аналитик или сервер автоматизации (CI/CD) пытается запустить проект на несовместимой версии dbt-core. С помощью этого инструмента решается проблема конфликта версий.

Итак, откройте файл dbt_project.yml и обновите блок валидации:

name: 'carsharing'
version: '1.0.0'

# Ограничиваем проект рамками проверенной минорной ветки ядра
require-dbt-version: [">=X.Y.0", "<X.Z.0"]

Например, если ли на шаге 2 вы обновили ядро до версии 1.11.2, укажите диапазон [">=1.11.0", "<1.12.0"]. Это защитит проект от случайных несовместимых мажорных апгрейдов у других разработчиков команды.

Шаг 4. Пересборка внешних пакетов

Внешние библиотеки (например, dbt-utils), подключенные к вашему проекту, содержат макросы, жестко привязанные к логике ядра dbt. При любом обновлении или откате среды их кэш необходимо сбросить.

# Удаляем скомпилированные артефакты прошлых запусков и старые папки пакетов
dbt clean

# Скачиваем совместимые с текущим ядром версии библиотек заново
dbt deps

Шаг 5. Валидация и холостой прогон (Dry Run)

Завершающий этап - проверка работоспособности обновленного проекта без лишних затрат времени инженера и ресурсов базы данных.

Синтаксический аудит:

dbt parse

Данная команда компилирует код моделей и YAML-конфигурации, выстраивая направленный граф (DAG) в памяти, но не отправляет запросы в СУБД. Если парсер завершил работу без ошибок, значит синтаксис Jinja и связи моделей валидны.

Холостой прогон:

dbt build --empty

Флаг --empty является одним из важнейших инструментов оптимизации бюджетов на разработку. С этим флагом dbt Core выполняет сборку проекта, временно подставляя в SQL-запросы конструкцию LIMIT 0 (или WHERE false). База данных мгновенно создаст целевую структуру таблиц и представлений, позволяя физически убедиться в совместимости типов данных и DDL-кода с обновленной версией адаптера без траты времени на обработку реальных строк данных.

Шаг 6. Сохранение проекта

Если сборка в режиме --empty завершилась успешно, зафиксируйте изменения (git commit) и отправьте их в репозиторий (git push).

Инженерная шпаргалка по управлению версиями: