Alembic: Multiple head revisions после слияния веток

Два разработчика независимо добавили изменения в базу. Один сделал таблицу уведомлений, второй — поле часового пояса. В Git конфликтов нет: миграции лежат в разных файлах. Но после слияния Alembic отказывается выполнять upgrade head и сообщает о нескольких вершинах.

Это конфликт истории миграций, а не обязательно конфликт SQL. Обе новые ревизии ссылаются на одного предка, поэтому единственной следующей вершины больше нет.

Сначала посмотрите граф

В каталоге проекта с настроенным alembic.ini выполните команды чтения:

alembic heads
alembic history --verbose
alembic current

heads показывает вершины файлов миграций, current — состояние выбранной базы. Эти ответы могут различаться: файлы уже приехали в репозиторий, а база ещё не обновлялась.

Предположим, heads вывел a12b и c34d. Не удаляйте одну миграцию только ради исчезновения сообщения: её изменение может уже использовать приложение, а сама ревизия могла попасть в другую среду.

Объединяем две совместимые ветки

alembic merge -m "merge notification and timezone changes" a12b c34d

Вместо a12b и c34d подставьте идентификаторы из своего heads. Команда создаёт новую ревизию, у которой down_revision содержит обоих родителей. Если изменения независимы, upgrade и downgrade объединяющей ревизии могут остаться пустыми: задача этого файла — соединить граф.

После просмотра файла проверьте обновление на отдельной тестовой базе: alembic upgrade head. Ещё раз выполните heads и current. В обычной линейке приложения вы ожидаете одну объединённую вершину.

Пустой merge не исправит противоречащий SQL

Если обе ветки переименовали одну колонку по-разному, сначала нужно согласовать итоговую схему и преобразование данных. Один файл merge не способен сделать несовместимые операции совместимыми. Здесь важно прочитать обе родительские миграции, а не только сгенерированный файл.

Полезная проверка состоит из трёх запусков на временных базах: обновление от общего предка, от первой ветки и от второй. Так вы увидите, что путь работает не только на машине автора merge. На каждом пути проверьте данные, которые должны пережить изменение.

Команда stamp лишь меняет отметку версии. Использовать её вместо применения потерянной миграции опасно: Alembic начнёт считать схему обновлённой, хотя таблицы останутся прежними. Если проблема возникла после автоматической генерации файла, начните с проверки переименования колонок.

Собрать следующий этап проекта

Хотите собрать API целиком, а не останавливаться на отдельном обработчике? На бесплатном курсе FastAPI вы сделаете сервис с базой, регистрацией, проверкой прав и тестами. Это проект, который можно развивать дальше и показывать вместе с исходниками.

Посмотреть программу: FastAPI для начинающих: API с базой данных и тестами

Проверить детали: Alembic: ветвление и merge revisions.