alembic CommandError target database is not up to date

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 app migrates with alembic but the agent checked flyway's history table, so its "already applied" answer was about a different tool's state. Read the correct table (alembic_version), reconcile what actually applied versus what the agent assumed, and fix the agent's runbook to derive the state table from the project's migration tool, never from a guess.

The query

agent's idempotency check looked at the wrong state table - it checked flyway_schema_history but the app uses alembic_version

Use this when

• Agent checked flywayschemahistory but the app uses alembic
• Idempotency check read the wrong state table
• Migration skipped or double-applied due to wrong history source
• Standardizing how agents detect migration state

Not for

• A state table that is genuinely corrupt (repair the table)
• Two tools legitimately managing different schemas (document both)
• An agent that checked the right table and misread it (a reading error, not a source error)

Steps

1. Identify the app's real migration tool

Look at the project: alembic versions directory, flyway SQL directory, prisma/migrations, django migrations package. Exactly one of these is the source of truth for the schema the agent is migrating.

Expected output: the tool name, stated explicitly. Write it in the runbook so the next agent does not guess.

2. Read the correct state table

SELECT version_num FROM alembic_version;

(Or the equivalent: flywayschemahistory, prismamigrations, djangomigrations, schemamigrations.) Expected output: what actually applied, from the tool that applied it. Compare against what the agent assumed from the wrong table.

3. Reconcile any wrong decision the agent made

If the agent skipped a migration that had not applied: apply it now, checking its prerequisites. If the agent double-applied something: inventory the effects and reconcile by hand. The wrong-table check is over; this step repairs its consequences.

Expected output: the schema and the correct state table agree, verified by inspection.

4. Fix the runbook: derive the table from the tool

The agent's migration procedure gains a first step: detect the migration tool from the project layout, then consult that tool's state table. Hard-code nothing: the mapping lives in one place in the runbook.

Expected output: the agent cannot check the wrong table, because the table is derived, not remembered.

5. Add a cross-check for mixed-tool projects

If the project genuinely uses two tools (e.g. flyway for one schema, alembic for another), the runbook lists each tool with its schemas and its table. The agent states which tool it is checking before reading.

Expected output: mixed projects get explicit per-tool checks instead of one guessed table.

Tool compatibility

Tool-agnostic: the pattern (detect tool, read its table, reconcile) applies to every migration framework.

Variant phrasings

agent checked wrong migration state table

Steps 1 and 2: detect the real tool, read its table.

flywayschemahistory vs alembic_version confusion

Step 1: the project layout tells you which tool owns the schema. One project, one tool per schema.

idempotency check wrong history table

Step 4: derive the table from the detected tool in the runbook so it cannot be guessed wrong again.

Why it happens

Every migration tool keeps its own history table with its own name, and the names are similar enough to confuse: an agent that has seen flyway projects "knows" the table is flywayschemahistory and applies that knowledge to an alembic project. The check answered a question about a history that does not govern this schema. State is per-tool; there is no universal migration history.

Edge cases

• A project mid-migration from one tool to another has two true histories for a while: the runbook must say which tool owns which schema during the transition.
• Reading the right table but the wrong database (staging vs prod) is the same class of mistake one level up: the runbook should verify the target too.
• Some tools store state outside tables (files, custom backends): "read the state table" generalizes to "ask the tool for its applied set" via its own CLI.

Provenance

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

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

Thread query: agent's idempotency check looked at the wrong state table - it checked flywayschemahistory but the app uses alembic_version

TL;DR: The app migrates with alembic but the agent checked flyway's history table, so its "already applied" answer was about a different tool's state. Read the correct table (alembic_version), reconcile what actually applied versus what the agent assumed, and fix the agent's runbook to derive the state table from the project's migration tool, never from a guess.