Manages Alembic database migrations for x0tta6bl4. Detects schema drift, generates migrations, runs them safely with rollback support. Use when user asks to: run migration, create migration, upgrade database, check schema drift, apply alembic, migrate database, добавь колонку в БД, создай миграцию, запусти alembic, обнови схему базы данных, откат миграции, rollback migration.
Safe Alembic migration workflow for x0tta6bl4 (PostgreSQL via SQLAlchemy).
# Check what migrations have been applied
alembic current
# Check what's pending
alembic history --verbose | head -20
# Check schema vs models drift (custom script)
python3 check_actual_schema.py
Expected output: list of tables and columns. Compare with src/database/__init__.py models.
# Auto-generate migration from model changes
alembic revision --autogenerate -m "describe_the_change"
The generated file appears in alembic/versions/. Review it carefully:
upgrade() adds exactly the expected columns/tablesdowngrade()Common autogenerate issues to fix:
# Check SQL without applying
alembic upgrade head --sql > /tmp/migration_preview.sql
cat /tmp/migration_preview.sql
Checklist before applying:
DROP TABLE or DROP COLUMN without explicit intent# Apply all pending migrations
alembic upgrade head
# Apply one step at a time
alembic upgrade +1
# Apply to specific revision
alembic upgrade <revision_id>
Verify after applying:
alembic current
python3 check_actual_schema.py
python3 -m pytest tests/unit/api/ tests/api/ --no-cov -q -x
# Rollback one step
alembic downgrade -1
# Rollback to specific revision
alembic downgrade <revision_id>
# Full rollback (DANGEROUS — drops all data)
alembic downgrade base
Error: target database is not up to date
alembic stamp head # mark current state as up-to-date (use only if DB matches models)
Error: Can't locate revision
Check alembic/versions/ for the file, ensure it's committed and alembic_version table is correct.
Error: column already exists
Migration was partially applied. Check alembic_version table and manually fix state:
UPDATE alembic_version SET version_num = '<previous_revision>';
references/migration-checklist.md — full safety checklist