agent merged two branches and created branching alembic heads without noti

Not specified by the original author.

TL;DR

Each branch added a migration from the same parent, so the merge produced two heads and deploys now fail. Detect it with alembic heads, join the branches with alembic merge, and prove the merged chain upgrades cleanly on a scratch database. Then add a single-head check to CI: branch collisions should break the build, not the deploy.

The query

agent merged two branches and created branching alembic heads without noticing - how to detect and merge

Use this when

• An agent merged branches and created branching alembic heads
• alembic upgrade head fails with "Multiple heads are present" after a merge
• Need to detect head forks in CI
• Two developers' migrations collided silently

Not for

• "Can't locate revision" (a deleted file, not a fork)
• A single head behind the database (run upgrade head)
• Intentionally separate histories (document them; this fix does not apply)

Steps

1. Detect the fork

alembic heads
alembic history

Expected output: two head ids sharing a parent in the history output. Note which branch each head came from: the history messages usually say.

2. Verify each branch works alone

On a scratch database, upgrade to each head separately (downgrade between). Expected output: both apply cleanly. A merge cannot fix a branch that was already broken; fix that first.

3. Merge the heads

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

Expected output: a new merge revision with an empty upgrade/downgrade and a down_revision tuple of both heads. Review the file: merges carry no schema operations.

4. Prove the merged chain on scratch

alembic upgrade head

On a fresh database from zero, and on a database sitting at each old head. Expected output: all three paths converge on the new single head with the correct final schema.

5. Add the single-head gate to CI

A CI step runs alembic heads and fails when it prints more than one line. Expected output: the next branch collision breaks the pull request with a clear message, while the fix is still a cheap local merge.

6. Teach the agent the merge-time check

The agent's branch-merge procedure gains a step: after any git merge, run alembic heads before pushing. Expected output: the agent catches its own forks instead of shipping them.

Tool compatibility

alembic 1.x, all backends.

Variant phrasings

agent merged branches created branching alembic heads

Steps 1 through 3: detect, verify, merge.

detect alembic multiple heads in CI

Step 5: fail the build when alembic heads prints more than one line.

alembic merge after git merge

Step 3: alembic merge joins the revision graph; the git merge only joined the files.

Why it happens

Git merges files; it knows nothing about the revision graph inside them. Two migrations from the same parent merge textually with no conflict, but the graph now has two heads and upgrade head has no unique path. The failure is silent at merge time and loud at deploy time, which is exactly backwards: hence the CI gate.

Edge cases

• If the two branches made incompatible changes to the same table, the merge upgrades them in an arbitrary order: review the operations for semantic conflicts, not just the graph.
• When one head is a mistake that never applied anywhere, delete its file instead of merging: only merge branches you intend to keep.
• The agent should also check for forks after rebases, not just merges: rebasing rewrites the files the graph is built from.

Provenance

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

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

Thread query: agent merged two branches and created branching alembic heads without noticing - how to detect and merge

TL;DR: Each branch added a migration from the same parent, so the merge produced two heads and deploys now fail. Detect it with alembic heads, join the branches with alembic merge, and prove the merged chain upgrades cleanly on a scratch database. Then add a single-head check to CI: branch collisions should break the build, not the deploy.

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.

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: