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

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

Two revision chains grew from the same parent, so alembic cannot pick one upgrade path. List the heads, create a merge revision that depends on both, and upgrade through it. The merge revision usually has empty upgrade and downgrade bodies; its only job is to join the graph. Add a heads check to CI so the next branch collision fails fast instead of surprising a deploy.

The query

alembic error: Multiple heads are present - how to merge branching heads

Use this when

• alembic upgrade head fails with "Multiple heads are present"
• Two branches each added a migration from the same parent
• alembic heads lists more than one revision
• An agent merged branches without noticing the migration graph forked

Not for

• "Can't locate revision" (a deleted file, not a fork)
• A single head that is simply behind (run upgrade head)
• Intentionally branched histories you plan to keep separate (rare; document it explicitly)

Steps

1. List the heads and see the fork

alembic heads

Expected output: two or more revision ids. Follow with alembic history to see which parent they share and what each branch contains.

2. Check both branches apply cleanly on their own

On a scratch database, upgrade to each head in turn (downgrade between runs) and confirm neither branch is broken independently. A merge cannot fix a branch that was already failing.

Expected output: both heads apply without errors on a fresh database. If one fails, fix that branch first.

3. Create the merge revision

alembic merge -m "merge heads" [head-a] [head-b]

Expected output: a new revision file whose down_revision is the tuple of both heads, with empty upgrade and downgrade functions. Review the file: it should contain no schema operations, only the join.

4. Upgrade through the merge on a scratch database first

alembic upgrade head

Expected output: alembic applies whichever branch is missing and then the merge revision, ending on the new single head. Verify the final schema matches what both branches intended.

5. Add a single-head gate to CI

Add a step that fails the build when alembic heads returns more than one line. Branch collisions then surface at pull-request time, where the merge is cheap, instead of at deploy time.

Expected output: future forks break the build with a clear message instead of breaking the deploy with "Multiple heads are present".

Tool compatibility

alembic 1.x, all backends. alembic merge has existed with the same behavior since 0.7.

Variant phrasings

alembic merge branching heads

Step 3 is the whole fix: alembic merge with both head ids.

alembic two heads after branch merge

Steps 1 and 3: confirm the fork, then merge. The git merge is fine; only the revision graph needs the join.

Multiple heads are present alembic how to fix

Steps 3 and 4: create the merge revision and prove it upgrades cleanly on a scratch database before touching shared environments.

Why it happens

Alembic models history as a directed graph and upgrade head means "walk from the current version to the single head". When two revisions share a parent, the graph has two heads and no unique path, so alembic stops instead of guessing. A merge revision is an explicit statement that both branches are wanted.

Edge cases

• If the two branches touch the same table incompatibly (one drops a column the other alters), the merge upgrades in an arbitrary order: review both branches' operations for conflicts, not just the graph.
• A merge revision with real DDL in it is a smell: keep merges empty and put schema work in normal revisions.
• If one head was a mistake that never applied anywhere, deleting its file is cleaner than merging it in. Only merge branches you intend to keep.

Provenance

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

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

Thread query: alembic error: Multiple heads are present - how to merge branching heads

TL;DR: Two revision chains grew from the same parent, so alembic cannot pick one upgrade path. List the heads, create a merge revision that depends on both, and upgrade through it. The merge revision usually has empty upgrade and downgrade bodies; its only job is to join the graph. Add a heads check to CI so the next branch collision fails fast instead of surprising a deploy.