airflow db migrate: Миграция схемы БД после обновления Airflow
Миграция схемы БД после обновления Airflow
Базовый синтаксис
Команда airflow db migrate применяет изменения схемы базы данных Apache Airflow к её текущему состоянию. Это необходимо после обновления версии Airflow, когда в новой версии появляются изменения в моделях данных.
Самый простой вызов:
airflow db migrate
Команда подключается к базе данных, указанной в AIRFLOW__DATABASE__SQL_ALCHEMY_CONN, сравнивает текущую схему с актуальной, определённой в коде Airflow, и выполняет необходимые SQL-запросы (ALTER TABLE, CREATE INDEX и т.д.). Все действия выполняются в рамках одной транзакции.
Полезные флаги
--show-sql-only — ключ для проверки. Команда не вносит изменений, а только выводит SQL-запросы, которые будут выполнены. Незаменим для превью и составления плана работ.
Пример перед обновлением на продакшене:
airflow db migrate --show-sql-only
Вы увидите список всех ALTER TABLE, что позволяет оценить сложность миграции и запланировать даунтайм.
--from-version — принудительно задаёт версию, с которой начинается миграция. Используется в нестандартных ситуациях, например, при восстановлении из бэкапа, где метаданные Alembic (инструмент для миграций внутри Airflow) могли потеряться.
Пример:
airflow db migrate --from-version 2.4.0
Это заставит Airflow провести миграции, начиная с указанной версии, игнорируя собственную таблицу alembic_version.
Типичные сценарии
Сценарий 1: Штатное обновление минорной версии Airflow. Допустим, обновляемся с 2.7.1 на 2.7.3. После установки нового пакета и до запуска шедулера и веб-сервера выполняем:
airflow db migrate
Это гарантирует, что новые поля в таблице DAG Run или индексы появятся до начала работы обновлённых компонентов.
Сценарий 2: Отладка неудачной миграции. Если миграция упала на полпути (например, из-за таймаута БД), и таблица alembic_version указывает на промежуточную ревизию, можно принудительно откатиться на предыдущую стабильную версию через airflow db downgrade, а затем снова запустить airflow db migrate, предварительно устранив причину сбоя.
Частые ошибки
Ошибка 1: Запуск команды на работающем Airflow. Выполнение миграции на запущенных шедулере и веб-сервере может привести к неопределённому поведению и ошибкам типа “Table already exists”. Всегда останавливайте сервисы Airflow перед миграцией.
Ошибка 2: Недостаточно прав у пользователя БД. Пользователь Airflow должен иметь права на выполнение DDL-операций (CREATE, ALTER, DROP) в схеме базы данных. Иначе команда завершится с ошибкой sqlalchemy.exc.ProgrammingError. Проверяйте права заранее, используя флаг --show-sql-only для генерации скрипта, который затем можно выполнить под привилегированным пользователем.