Database migration fails with 'relation already exists' or the migration history is out of sync (Alembic 'DuplicateTable', Django 'table already exists'): how do I realign it safely?

Cause: The migration tool's record of what was applied (Alembic's alembic_version table, Django's django_migrations table) disagrees with the real schema. Typical reasons: tables were created by hand or by create_all()/syncdb before migrations, a migration partly ran before failing on a database without transactional DDL (MySQL), migration files were deleted or squashed, a restore brought back tables but not history, or two branches created conflicting migrations. Fix (best first, back up the database first): 1. Inspect state without changing it. Alembic: alembic current, alembic history --verbose, alembic heads. Django: python manage.py showmigrations and python manage.py sqlmigrate <app> <number> to see what SQL a migration would run. Compare with the actual tables. 2. If the schema already matches a given revision, tell the tool so without running SQL. Alembic: alembic stamp <revision> (stamp head if the whole schema is current); it only writes the version table and runs no migrations. Django: python manage.py migrate <app> <number> --fake, or --fake-initial for an initial migration whose tables already exist. The Django docs warn that --fake is for advanced use and --fake-initial only checks table names, not full schema, so confirm the schema first. 3. If the schema is partly applied, finish or undo the missing pieces by hand (or edit the migration to be conditional), then stamp/fake only that migration. 4. Multiple Alembic heads: merge them with alembic merge heads -m "merge" (check with alembic heads), do not stamp over them. 5. Prevent it: apply migrations only through the tool, run them once in deployment (not in every replica at startup), commit migration files, and do not call create_all() on databases managed by migrations. Verify: Alembic: alembic current --check-heads (Alembic 1.17.1 or newer) or alembic current shows head. Django: showmigrations shows [X] for all, and migrate reports 'No migrations to apply'. Sources: https://alembic.sqlalchemy.org/en/latest/api/commands.html https://alembic.sqlalchemy.org/en/latest/cookbook.html https://docs.djangoproject.com/en/stable/ref/django-admin/