Alembic + SQLAlchemy + PostgreSQL (Docker) | Ошибки | Мини‑курс [4]

Autogenerate создает пустую миграцию (ничего не меняет)

Симптом: вы делаете alembic revision --autogenerate, а в миграции почти нет операций.
Причина №1: Alembic не видит модели, потому что вы не импортировали их в alembic/env.py.
Решение: убедитесь, что в alembic/env.py есть:

from app.db import Base
import app.models

target_metadata = Base.metadata

Важно: import app.models нужен даже если IDE подчеркивает “неиспользуемый импорт”. Это “импорт ради регистрации моделей”.

Ошибка подключения к БД (Connection refused / could not translate host name)

Проверьте последовательно:

Контейнер запущен:
```
docker ps
```
Bash
Порт проброшен: в docker-compose.yml есть "5432:5432"

DSN в alembic.ini корректный:

sqlalchemy.url = postgresql+psycopg2://app_user:app_password@localhost:5432/app_db

Подсказка: если вы запускаете Alembic не на хосте, а из другого контейнера, тогда localhost будет ссылаться на тот контейнер. В этом курсе Alembic запускается на хосте, поэтому localhost — правильно.

Что такое base и head в Alembic

Alembic хранит миграции как цепочку “ревизий” (revision). У каждой миграции есть: revision (ID текущей) и down_revision (ID предыдущей).

Термин	Что означает	Где используется
`base`	“Нулевое” состояние — до первой миграции. То есть в БД еще не применено ни одного шага из папки `versions`.	`alembic downgrade base`
`head`	Актуальная “голова” — последняя миграция в вашей цепочке. Если миграции не ветвятся, head — просто последняя по порядку.	`alembic upgrade head`

Запомнить просто: upgrade head = “дойти до самого свежего состояния проекта”. downgrade base = “откатить всё в ноль”.

Чем отличается downgrade -1 от downgrade <revision>

Оба варианта делают откат (выполняют downgrade()), но выбирают “куда откатываться” по-разному.

Вариант A: `alembic downgrade -1`

Смысл: откатить ровно один шаг назад от текущего состояния.

Если вы на второй миграции — вернетесь на первую.
Если вы на первой — вернетесь на base.

alembic downgrade -1

Вариант B: `alembic downgrade <revision>`

Смысл: откатиться до конкретной ревизии по её ID.

Alembic сам выполнит столько downgrade(), сколько нужно, чтобы дойти до указанной ревизии.
Удобно, когда нужно откатиться не на один шаг, а сразу на несколько.

Посмотреть IDs миграций:

alembic history

Откатиться до конкретной миграции (пример):

alembic downgrade 7f3b9b1e0f2a

Важно: ID (7f3b9b1e0f2a) — пример. Используйте ваш ID из alembic history.

Практическое правило: для “откатить последнюю миграцию” используйте -1. Для “откатить до известной точки” используйте <revision>.

В БД нет таблицы alembic_version — это нормально?

Да. Таблица alembic_version появляется при первом alembic upgrade ....

Правильное поведение: до применения миграций её нет, после — появляется автоматически.

Как понять, какая миграция применена?

Команда:

alembic current

Также можно смотреть таблицу alembic_version в БД через psql.

Можно ли править файл миграции руками?

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

Что делать, если миграция упала посередине?

Чаще всего:

смотрите текст ошибки (какой SQL/операция упали)
проверяйте текущее состояние alembic current
при необходимости фиксируйте вручную БД и повторяйте миграцию

На практике: в продакшене миграции должны быть протестированы на копии данных и быть максимально безопасными.

Ссылки по теме

Конспект:

Вторник, 06 января 2026

Добавить комментарий