Allow custom RevisionMap subclass for pluggable revision ordering

[jasonwbarnett]

Problem

We run a high-velocity monorepo where multiple teams land migrations concurrently. In our merge queue, when two PRs each add a migration, the second one to merge discovers there are now two Alembic heads. This kicks the PR out of the merge queue and requires the author to manually rebase and update their migration's down_revision to point at the new head, re-push, and re-enter the queue. With many developers contributing migrations, this compounds — the more PRs in flight, the more frequently authors get ejected and have to rebase, creating a frustrating cycle of churn.

We want to solve this by using git history to automatically determine migration ordering — when concurrent migrations create multiple heads, order them by when they were first introduced in git, so that the merge queue can resolve the ordering deterministically without human intervention. This requires being able to swap in a custom RevisionMap subclass that overrides _topological_sort().

Today there is no way to customize the ordering behavior without monkey-patching internals. The RevisionMap class is instantiated directly inside ScriptDirectory.__init__() with no way to substitute a subclass.

Proposed Solution

Add a revision_map_class configuration option to ScriptDirectory that accepts a dotted Python path to a RevisionMap subclass. This would allow external packages (e.g. a hypothetical alembic-git-ordering) to provide custom ordering logic by overriding _topological_sort() or other methods, without any changes to Alembic core.

This is a minimal, non-breaking change: a single new keyword argument with a None default, and a config option that is entirely opt-in.

Use Cases

• Merge queue compatibility: In CI merge queues (GitHub, Mergify, etc.), concurrent migrations cause repeated head conflicts that eject PRs. Authors must rebase and update down_revision each time, which compounds with team size. A git-history-aware RevisionMap could order unrelated migrations deterministically, eliminating this manual churn.
• Git-history-based ordering: Order concurrent migrations by their first commit date, giving a stable timeline-based ordering across branches.
• Custom merge strategies: Organizations with many parallel branches could implement project-specific rules for how unrelated migrations should be sequenced.

Current Workarounds

The only current options are:

1. Monkey-patching RevisionMap or ScriptDirectory in env.py — fragile and breaks across Alembic upgrades
2. Forking Alembic — heavy-handed for a small customization point
3. Manually rebasing and updating down_revision every time a PR gets ejected — the status quo we're trying to escape

We have a PR ready at #1805 that implements this.

[CaselIT]

Hi,

I'm not sure you use case can work by just changing the topological sort since there are other instances what depend on the revision.down_revision attribute, but we can look at the pull request.

Note that your proposed strategy is not safe in general, since you generally cannot automatically order your migrations using their git commit data, since you may miss migrations if a revision A took one day to merge while another created before A took a week to merge.
That said it would not be an alembic problem if this happened while you used a custom revision map.

@zzzeek what do you think?

[jasonwbarnett]

Thanks for the thoughtful response, @CaselIT.

You raise a good point about down_revision. Let me explain the full picture of what we're trying to achieve, since the revision_map_class is just the first piece.

Our current problem:

1. Two developers independently create migrations on separate branches. Neither migration depends on the other.
2. Both PRs pass CI pre-merge (including a check that there's only one Alembic head).
3. Both PRs enter the merge queue.
4. The first PR merges. Its migration's down_revision correctly points at what was head on main.
5. The second PR fails CI in the merge queue because there are now two heads. The just-merged migration and this PR's migration both point at the old head. The PR gets ejected, and the author has to manually rebase, update down_revision, and re-enter the queue.

What we want to build (the full solution, not just this PR):

The revision_map_class hook would be one piece of a larger solution. The idea is:

1. Migrations would be authored with down_revision = None. Developers would no longer manually maintain the revision chain.
2. A custom RevisionMap subclass would build the ordering entirely from git history, specifically the date each migration file was first committed. If two migrations are introduced in the same commit, the filename/timestamp in the migration acts as a tiebreaker.
3. This means when the merge queue processes the second PR, instead of seeing "two heads, error", the custom RevisionMap would construct a linear chain from git history: the migration committed first goes first, the other follows after it. There are never multiple heads because the ordering is always derived dynamically.

On your concern about ordering safety:

You're right that git commit date ordering is not universally safe. A migration that took a week to merge could end up ordered after one that was created later but merged sooner. However, in our case these are independent, non-conflicting migrations. If migration A adds a widgets table and migration B adds a gadgets column to an unrelated table, it doesn't matter which runs first. The key constraint is that we need a deterministic ordering so CI passes consistently, not that the ordering reflects some semantic dependency.

The ordering would always be fully dynamic. Developers would never set down_revision manually. If two migrations truly do have a dependency between them, the developers would need to coordinate their merge order explicitly, the same way they'd handle any other cross-PR dependency.

CI as a safety net:

We also run the full migration suite in CI both in pre-merge pipelines and in the merge queue. So in the rare case where PR 1's migration actually breaks PR 2's migration when run in sequence, PR 2 would get kicked from the merge queue with a meaningful migration error, the same way any other real conflict surfaces. The difference from today is that PRs only get ejected when there's an actual problem, not just because two independent migrations happened to land concurrently.

Does that clarify the use case? We fully understand the risks and accept that the ordering strategy is our responsibility. We just need the hook to plug it in.

[CaselIT]

I think you misunderstood what I was saying.

The ordering is not deterministic using git commit date:

State 0: B
Merge PR 1 with revision X committed april 9
State 1: B -> X
Merge PR 2 with revision Y committed april 7
State 2: B -> Y -> X

If you deployed to a db state 1, then you go to update to state 2 alembic would see no change is need, but migration Y wan never applied.

That said, if you are fine with it that's ok ok my part.
Note that it would not be considered an issue in alembic the above behavior

[jasonwbarnett]

I think I understand your concern now, and it's a valid one if the ordering were based on the original commit date from the developer's branch. Let me clarify what we'd actually use.

We use merge commits on GitHub. When a PR merges (or enters the merge queue), the merge commit on main gets a new timestamp reflecting when it was actually merged, not when the developer originally authored the migration. So the ordering would be based on when the migration file first appears in main's history via its merge commit.

In your example:

• Developer A commits migration X locally on April 2.
• Developer B commits migration Y locally on March 15.
• PR 1 (migration X) merges into main on April 9 10:00. X gets merge timestamp April 9 10:00.
• Deploy. DB is at state B -> X.
• PR 2 (migration Y) merges into main on April 10 09:00. Y gets merge timestamp April 10 09:00.
• Ordering is B -> X -> Y (not B -> Y -> X), because Y's merge commit on main is newer than X's, regardless of when Developer B originally committed Y locally.
• Alembic sees DB is at X, applies Y. Correct.

The merge commit timestamps on main are always sequential, so the ordering always reflects the actual merge order. A migration can never retroactively slot in before one that was already merged and deployed.

I should have been more precise in my earlier comment. When I said "the date each migration file was first committed" I meant the date it first appears in main's history (via the merge commit), not the original authoring date on the feature branch. Am I missing something obvious here that you still see as a problem?