Alembic — установка, инициализация и первые миграции (FastAPI + SQLAlchemy)

Краткое и практичное напоминание по установке Alembic, инициализации проекта, привязке к SQLAlchemy Base и работе с миграциями.
  # 1. Установка Alembic
  pip install alembic

  # (обычно SQLAlchemy уже установлен, но при необходимости)
  pip install sqlalchemy

  # 2. Инициализация Alembic в проекте
  # Выполняется в корне проекта
  alembic init alembic

  # В результате будет создано:
  # - директория alembic/
  # - файл alembic.ini

  # 3. Настройка подключения к базе данных
  # Файл: alembic.ini
  #
  # Найдите строку:
  # sqlalchemy.url = driver://user:pass@localhost/dbname
  #
  # Возможные варианты:
  # - временно указать URL напрямую
  # - либо оставить пустым и задавать URL из кода (рекомендуется)

  # 4. Привязка Alembic к SQLAlchemy Base
  # Файл: alembic/env.py

  from app.db.base import Base  # пример импорта Base
  target_metadata = Base.metadata

  # Важно:
  # - даже если в проекте используется async SQLAlchemy (FastAPI),
  #   Alembic работает синхронно
  # - используйте sync-URL:
  #   postgresql://...
  #   а не postgresql+asyncpg://...

  # 5. Генерация первой миграции
  alembic revision --autogenerate -m "init"

  # Сгенерированный файл появится в:
  # alembic/versions/

  # 6. Применение миграций
  alembic upgrade head

  # 7. Основные команды Alembic на будущее
  alembic revision -m "описание"         # пустая миграция
  alembic revision --autogenerate -m ""  # автогенерация
  alembic upgrade head                   # применить все миграции
  alembic downgrade -1                   # откатить одну миграцию
  alembic history                        # история миграций
  alembic current                        # текущая версия БД