alembic downgrade -1 error fails target database not up to date bug

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.

Not specified by the original author.

TL;DR

The dev ini pointed at (or configured for) the wrong database, so a dev-configured alembic ran against production. Assess what ran and with what settings, then separate configs per environment: one ini per environment (or one ini reading the URL from the environment), a wrapper that selects by explicit --env flag, and a guard that refuses dev-configured runs against production hosts.

The query

agent ran alembic with the dev alembic.ini against the production database

Use this when

• Alembic ran with dev alembic.ini against production
• Wrong ini file targeted the wrong database
• Need per-environment alembic configs
• An agent used the dev config on prod

Not for

• The right config failing on prod (fix the migration)
• A dev ini used on a dev database (that is its job)
• Connection-string confusion without ini involvement (guard the URL directly)

Steps

1. Assess what ran and under what settings

Read the dev ini: which sqlalchemy.url did it resolve to, and what settings differ from prod (echo, pool sizes, transaction settings)? Check the state table on the affected database to see which revisions applied.

Expected output: the exact database hit, the revisions applied, and any dev-only settings (like verbose echo or aggressive pooling) that touched prod.

2. Contain and reconcile

If unexpected revisions applied to prod, reconcile the schema and the history (inventory, hand-apply or stamp, as with any out-of-place migration). Rotate any credentials the dev config exposed. Expected output: prod's schema and history are consistent and deliberate again.

3. Separate configs per environment

Create alembic.prod.ini (and staging), or keep one ini that reads the URL from the environment and nothing else. No ini file should contain a production URL as a default a dev command can pick up accidentally.

Expected output: there is no single file that a bare alembic command can load and hit prod with.

4. Add the env-selecting wrapper

The agent runs migrations through a wrapper requiring --env, which selects the ini and prints the resolved target for confirmation. The wrapper refuses --env prod without an additional explicit confirmation flag.

Expected output: running alembic "the normal way" cannot reach prod; reaching prod requires two deliberate flags.

5. Make the dev ini unable to reach prod structurally

The dev ini's URL should resolve to a local database only (YOUR_HOST, or a socket). If the dev config cannot address prod at the network level, the wrong-ini mistake becomes a connection error, not an incident.

Expected output: the entire class of mistake degrades to "connection refused".

Tool compatibility

alembic 1.x. The per-environment config pattern applies to any ini-based tool.

Variant phrasings

alembic dev ini against production

Steps 1 and 2: assess what ran, reconcile prod.

per-environment alembic config

Step 3: one ini per environment, no prod URL as any default.

prevent alembic hitting wrong database

Steps 4 and 5: env-selecting wrapper plus a dev ini that cannot route to prod.

Why it happens

Alembic resolves its database from the ini file, and a bare alembic command loads alembic.ini from the current directory: whatever that file says is the target. When the dev ini is the default and it can address prod (via an env var someone exported, or a URL someone pasted), the tool does exactly what it was configured to do. The bug is a configuration that makes the wrong target reachable by default.

Edge cases

• Env-var-driven URLs are the usual vector: the ini reads sqlalchemy.url from DATABASE_URL, and the agent's shell had prod's. Fix the shell hygiene too, not just the ini.
• A wrapper the agent can bypass with an env var is decoration: the prod confirmation must be a separate explicit flag.
• Audit other ini-driven tools in the agent's reach (pytest configs, deploy scripts): the same default-config hazard usually exists in more than one place.

Provenance

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

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

Thread query: agent ran alembic with the dev alembic.ini against the production database

TL;DR: The dev ini pointed at (or configured for) the wrong database, so a dev-configured alembic ran against production. Assess what ran and with what settings, then separate configs per environment: one ini per environment (or one ini reading the URL from the environment), a wrapper that selects by explicit --env flag, and a guard that refuses dev-configured runs against production hosts.

Not specified by the original author.

TL;DR

The down migration was written once and never executed, so it references a schema that later migrations changed: it is fiction, not a rollback plan. Fix it to reverse exactly what the up migration did against the schema as it exists now, prove it with migrate-up-then-down on a scratch database, and add that test to CI for every migration. An untested down migration is a plan you have never read.

The query

agent skipped the down-migration test and the rollback script references columns that no longer exist

Use this when

• Rollback script references columns that no longer exist
• Down migration was never tested and now fails
• Need up/down migration testing in CI
• An agent skipped testing the down migration

Not for

• Rollbacks that fail because data cannot be restored (a data problem, not a script problem)
• Intentionally irreversible migrations (document them; do not fake a down)
• Up migrations that fail (fix the up direction first)

Steps

1. Read the down migration against the current schema

Open the down function and compare every statement against the schema as it exists after the up migration plus all later migrations. Mark every reference to a column, table, or constraint that no longer exists or has changed.

Expected output: the list of stale references. This is the complete repair list.

2. Rewrite the down to reverse the up exactly

The down migration must undo precisely what its up did: drop what up added, re-add what up dropped (with types), restore what up altered. Where the schema moved on (later migrations changed the same objects), the down must account for the current shape, not the shape at write time.

Expected output: a down migration whose every statement targets objects that exist.

3. Prove it: up then down on scratch

On a fresh database, run the migration up, then immediately down, then up again:

alembic upgrade [rev] && alembic downgrade -1 && alembic upgrade [rev]

(or the equivalent for your tool). Expected output: all three steps succeed, and the schema after the cycle matches the schema after a single up.

4. Add the up/down test to CI

Every migration gets the up-down-up cycle on a scratch database in CI. A migration whose down fails never merges.

Expected output: stale down migrations break the build at pull-request time instead of during a production rollback.

5. Teach the agent the reversibility rule

The agent's migration procedure: no migration is "done" until its down has executed successfully on scratch. Irreversible migrations are declared explicitly and get a compensating plan instead of a fictional down.

Expected output: down migrations stop being write-only.

Tool compatibility

alembic, django, rails, flyway (undo), liquibase (rollback). The up-down-up test pattern maps to every tool.

Variant phrasings

down migration references dropped columns

Steps 1 and 2: diff the down against the current schema, rewrite it to reverse the up exactly.

test rollback migration CI

Step 4: up-down-up on scratch for every migration, in CI.

rollback script never tested fails

Step 3: the up-down-up cycle is the test; run it before trusting any rollback.

Why it happens

Down migrations are written against a schema that keeps changing: later migrations alter the objects the down references, but nobody re-reads the down. The up gets executed constantly (every deploy, every fresh database); the down gets executed only in emergencies, which is the worst time to discover it is stale. Testing is the only thing that keeps the two in sync.

Edge cases

• A down that restores dropped columns restores them empty: data loss is inherent to rolling back a drop. Note it in the migration; the test proves the mechanics, not the data.
• Some downs are only valid immediately after their up (before later migrations build on it): document the valid rollback window, or the test gives false confidence.
• Destructive ups deserve a backup before the up runs, not just a tested down: the down reverses schema, backups reverse data loss.

Provenance

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

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

Thread query: agent skipped the down-migration test and the rollback script references columns that no longer exist

TL;DR: The down migration was written once and never executed, so it references a schema that later migrations changed: it is fiction, not a rollback plan. Fix it to reverse exactly what the up migration did against the schema as it exists now, prove it with migrate-up-then-down on a scratch database, and add that test to CI for every migration. An untested down migration is a plan you have never read.