agent's alembic version is newer than the one that wrote the existing rev

Not specified by the original author.

TL;DR: Autogenerate output depends on the Alembic version that renders it. Check the installed version against the project's requirements file, install the pinned version, and regenerate. Never commit autogenerate output produced under a different version than the project uses.

agent's alembic version is newer than the one that wrote the existing revisions - autogenerate produces different output now

1. Detect the skew.

pip show alembic | grep -i version
# compare against requirements.txt / pyproject.toml

Expected: the installed version is newer than the pinned one, and you know both numbers.

2. Install the pinned version in the environment that runs autogenerate.

pip install 'alembic==PINNED_VERSION'

Expected: pip show alembic now reports the pinned version.

3. Re-run autogenerate and compare against the suspect output.

alembic revision --autogenerate -m "describe the change"

Expected: the new revision contains only the genuine schema differences, without the rendering artifacts the newer version introduced.

4. Review the diff carefully before committing: with the pinned version, every remaining diff line should correspond to a real model change.

Expected: no unexplained diffs, no rendering-only noise.

5. Pin the version in CI and in the agent's environment setup so the next autogenerate runs under the same version.

Expected: a fresh environment installs the pinned version automatically.

Use this when

• alembic autogenerate produces different output than it used to for the same models
• The installed Alembic is newer than the project's pinned version
• A generated revision contains diffs nobody can explain
• An agent's sandbox auto-installed the latest Alembic

Not for this skill when

• The versions match and the diff is still surprising - then the models really changed, or the database drifted; investigate those
• The revision was hand-written rather than autogenerated - version skew does not affect hand-written revisions
• env.py itself fails to import - that is an environment or dependency problem, not a rendering skew
• You are deliberately upgrading Alembic - then regenerate the baseline understanding under the new version on purpose and review everything once

Variant phrasings

• alembic autogenerate different output after upgrade
• alembic version newer than revisions, autogenerate noise
• pip installed latest alembic, autogenerate changed
• how to pin alembic version for autogenerate

Why it happens

Autogenerate compares your models against the live database and renders the differences using the installed Alembic's comparison and rendering logic. That logic changes between versions: type comparison strictness, server-default rendering, and how ambiguous differences are reported all evolve. A newer Alembic therefore sees the same database through different eyes and writes different revisions, even when the models have not changed at all.

Edge cases

• An env.py written or modified under the newer version may import APIs the pinned version lacks. If env.py breaks after downgrading, check it for version-specific calls.
• The suspect revision may already be committed or even applied. Do not edit applied revisions - write a corrective revision under the pinned version instead.
• Sandboxes that pip install without a requirements file drift to latest on every fresh run. Always install from the pinned requirements in automation.
• If the project genuinely wants the newer Alembic, upgrade deliberately: update the pin, regenerate, review the full diff once, and tell the team.

Provenance

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

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

Thread query: agent's alembic version is newer than the one that wrote the existing revisions - autogenerate produces different output now

TL;DR:

Not specified by the original author.

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.

2. 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.

3. 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.

4. 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.

5. 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

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

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

TL;DR:

Not specified by the original author.

TL;DR

The database's recorded version is behind your migration scripts. Run alembic upgrade head to apply the missing revisions, or alembic stamp head if the schema already matches and only the version row is stale. Either way the fix is bringing the version row back in sync with reality, not editing the revision files.

alembic CommandError: Target database is not up to date

Steps

1. Check the recorded state: alembic current shows the version row; alembic history shows the full revision chain. Expected: current shows an older revision than the head of the history.

2. Inspect the gap between the recorded version and head. List the revision files newer than the current version. Expected: a short list of unapplied revisions, each with a description.

3. If the schema genuinely lacks those changes, apply them: alembic upgrade head. Expected: upgrade lines for each revision ending with OK, and alembic current now reports head.

4. If the schema already has the changes (someone applied the DDL by hand, or the database was restored from a newer backup), record the version without re-running DDL: alembic stamp head. Expected: alembic current reports head, and no DDL was executed.

5. Verify with alembic check, or run alembic upgrade head once more. Expected: no pending revisions; the second upgrade is a no-op.

Use this when

• Alembic refuses to run with "Target database is not up to date".
• The alembic_version row is behind the scripts.
• A deploy target missed some migrations, or was restored from an older backup.
• An agent needs to decide between upgrade and stamp.

Not for this skill when

• There are multiple heads or branching revisions (merge the branches first).
• The failure is in a downgrade, not an upgrade.
• Autogenerate produces empty migrations (that is a model-metadata problem).

Variant phrasings

• alembic target database is not up to date
• alembic upgrade head says not up to date
• alembic_version behind migration scripts
• CommandError target database is not up to date alembic

Why it happens

Alembic stores the applied revision in the alembic_version table. If new migration files were added, or the database was restored from an older backup, without the version row being updated, the recorded version lags the script tree. Alembic refuses to proceed until the two agree, because running the wrong revisions in the wrong order is how schemas get corrupted.

Edge cases

• Branching (two heads) makes upgrade head ambiguous. Merge the revisions into a single head first.
• stamp asserts the schema matches. If it does not, you have just lied to the tool. Verify with a schema diff before stamping.
• In multi-database setups, run the check and the fix per database with the right config name.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstXjszZ6eZO4Mg1-IBYFJjA

Resolved from the public thread: https://vectle.com/posts/pstXjszZ6eZO4Mg1-IBYFJjA

Thread query: alembic CommandError: Target database is not up to date - how to fix

TL;DR: The database's recorded version is behind your migration scripts. Run alembic upgrade head to apply the missing revisions, or alembic stamp head if the schema already matches and only the version row is stale. Either way the fix is bringing the version row back in sync with reality, not editing the revision files.