agent session restarted between steps and it re-ran alembic upgrade head - how to know which revisions already applied

TL;DR: Ask alembic, not your memory: alembic current shows the revisions the database has applied, and alembic history shows the full chain. Re-running alembic upgrade head after a restart is safe - it starts from the current version and applies only what is pending. The new session's first migration step should always be reading current state, never assuming it.

agent session restarted between steps and it re-ran alembic upgrade head - how to know which revisions already applied

1. Read the current version: run alembic current.

Expected: output names the revision (or revisions, for branched histories) the database is at - for example a single revision id on one line.

1. See the full picture: run alembic history (add --verbose for the down revisions and dates).

Expected: the revision chain with the current one marked, so you can see what is behind and what is ahead.

1. Compare with the revision files on disk: everything after the current revision in the history is pending.

Expected: an exact list of revisions the re-run will apply - often empty, meaning nothing is left to do.

1. Re-run alembic upgrade head - it is idempotent with respect to applied revisions.

Expected: if the database is already at head, output says so and changes nothing; otherwise it applies only the pending revisions.

1. Write the outcome into the session handoff: current revision before and after, and the command output.

Expected: the next restarted session can read the handoff instead of guessing.

Use this when

• an agent session restarted between migration steps
• a new session re-runs alembic upgrade head and needs to verify what applied
• control of a migration passes from one agent instance to another

Not for this skill when

• the database connection is down - alembic current cannot answer without it
• revisions were edited after being applied - the version id matches but the content does not (a different problem)
• you need to know what a revision DOES - read the revision file, not the version table

Variant phrasings

• alembic which revisions are applied after restart
• re-run alembic upgrade head safely after session restart
• how to check alembic current version

Why it happens

Alembic records the applied revision id in the alembic_version table as part of each upgrade transaction. alembic current simply reads that table, and upgrade head computes the path from the current revision to head - applying nothing that is already recorded. A restarted session that re-runs upgrade head without checking first is not doing anything dangerous; the risk is only in the agent's planning (assuming work is done that is not, or redoing work out of uncertainty). Reading current state first turns the restart into a non-event.

Edge cases

• Multiple heads (branched revisions) show multiple current versions - merge the branches before upgrading to a single head.
• If alembic current errors on connection, fix connectivity first - do not guess the version from logs.
• A revision file deleted after being applied leaves the version table pointing at a revision with no file - upgrade head will complain; restore or stub the file.
• The handoff note is the real fix for repeat restarts - without it, every new session pays the discovery cost again.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_I1gpLGy3Lwnw5kcdhoqSHA