add rev_id generator function feature to environment.configure(), will apply to revision, merge

[jiayun]

Describe the use case

The merge command should support the process_revision_directives parameter in its programmatic API, consistent with the revision command.

Currently, while both commands support revision_environment (which runs env.py), only the revision command accepts a programmatic process_revision_directives parameter. This creates an API
inconsistency when using Alembic programmatically to customize revision generation logic for merge operations.

Databases / Backends / Drivers targeted

All databases - this is a general Alembic API feature request.

Example Use

Current behavior - revision command (works):

  from alembic import command
  from alembic.config import Config

  config = Config("alembic.ini")

  def my_process_revision_directives(context, revision, directives):
      """Custom revision ID generation logic"""
      for directive in directives:
          directive.rev_id = generate_custom_id()  # Custom logic

This works - process_revision_directives parameter is supported

  command.revision(
      config,
      message="Add new feature",
      process_revision_directives=my_process_revision_directives
  )

Desired behavior - merge command (currently doesn't work):

  # This fails with TypeError - process_revision_directives is not accepted
  command.merge(
      config,
      revisions=("head1", "head2"),
      message="Merge branches",
      process_revision_directives=my_process_revision_directives  # ❌ Not supported
  )

Current workaround:

Users must configure the hook in env.py, which affects all operations:

  # env.py
  def process_revision_directives(context, revision, directives):
      # This applies to ALL revision/merge commands
      for directive in directives:
          directive.rev_id = generate_custom_id()

  context.configure(
      process_revision_directives=process_revision_directives
  )

This workaround doesn't allow per-command customization when using the programmatic API.

Proposed API:

  def merge(
      config: Config,
      revisions: _RevIdType,
      message: Optional[str] = None,
      branch_label: Optional[_RevIdType] = None,
      rev_id: Optional[str] = None,
      process_revision_directives: Optional[ProcessRevisionDirectiveFn] = None,  # NEW
  ) -> Optional[Script]:
      """
      :param process_revision_directives: optional callable that allows
       programmatic customization of the revision directives. Same signature
       as the callable described at
       :paramref:`.EnvironmentContext.configure.process_revision_directives`
      """
      # Implementation already uses RevisionContext internally,
      # just need to accept and pass through the parameter

Use cases:

1. Different logic for merges vs regular revisions: Apply special revision ID schemes or metadata only to merge commits
2. CI/CD automation: Programmatic scripts that customize merge behavior without modifying env.py
3. Multi-tenant environments: Different revision ID generation based on runtime context

Additional context

• The merge command already uses RevisionContext internally (since 1.12.0 when revision_environment support was added via alembic merge ignores revision_environment and cannot find the hooks defined in env.py #1299)
• The implementation would be minimal - just accepting and passing through the parameter
• This would make the API consistent between revision and merge commands
• The parameter would be optional and backward-compatible

Reference:

• alembic/command.py::revision() - Lines 194-320 (already supports this parameter)
• alembic/command.py::merge() - Lines 382-439 (should support this parameter)
• alembic/autogenerate/api.py::RevisionContext - Already supports process_revision_directives

Versions.

• OS: macOS (but applies to all platforms)
• Python: 3.9+
• Alembic: 1.16.5 (latest)
• SQLAlchemy: 1.4+/2.0+
• Database: All
• DBAPI: All

[zzzeek]

hello -

This issue report seems to be missing some basic details and facts.

The merge command already uses RevisionContext internally

No, that's not correct. That change introduces uses of the EnvironmentContext but does not do anything with RevisionContext.

The implementation would be minimal - just accepting and passing through the parameter

not at all, this would require a lot of new logic in RevisionContext to accept the merge use case which receives a list of two fixed revision identifiers.

The definition of merge() is to produce a revision file where the upgrade() and downgrade() functions are fixed at blank. There is no Python code structure produced for the merge operation, and upgrade/downgrade instructions should be performed only outside of merge revision.

If you have some rationale for upgrade/downgrade instructions to be directly inside of a merge (there's no reason I can think of), that would be the start of the discussion and it would be a significant new feature that would need a lot of new tests.

[jiayun]

Thank you for the feedback, @zzzeek. I apologize for the technical inaccuracies in my initial report. Let me clarify:

Correction on Technical Details

You're absolutely correct - I was wrong about merge() using RevisionContext. Looking at the source code:

• revision() uses RevisionContext (command.py:265-269)
• merge() uses EnvironmentContext but not RevisionContext (command.py:330-336)

This is indeed a more significant architectural difference than I initially understood.

Our Actual Use Case

Our need is simpler than what my report may have implied - we only want to customize the revision ID generation for merge operations, not add upgrade/downgrade logic.

Specific requirement: Use custom integer IDs (from our internal number generator) instead of UUID-based IDs for all revisions, including merges.

Why consistency matters: The revision command, when revision_environment=true, executes env.py and respects the process_revision_directives hook configured there - regardless of whether autogenerate is used (command.py:288-292). This allows us to customize revision IDs uniformly.

However, the merge command, even with revision_environment=true, executes env.py but skips the process_revision_directives hook entirely. It directly calls script.generate_revision() with util.rev_id() (command.py:337), bypassing any customization opportunity.

This inconsistency means we can't use the same ID generation logic for both commands through the standard hook mechanism.

Current Workaround (Monkey Patch)

Since we can't customize merge's revision ID through the standard hook, we currently use a global monkey patch:

# migrate/env.py
import alembic.util.langhelpers

def custom_rev_id():
    """Generate custom integer ID instead of UUID"""
    from app.unique_number import next_number
    return str(next_number())

# Must patch both references
alembic.util.langhelpers.rev_id = custom_rev_id  # Original definition in langhelpers
alembic.util.rev_id = custom_rev_id              # Re-exported in util.__init__

With alembic.ini:

revision_environment = true

We also define process_revision_directives in env.py for the revision command:

def process_revision_directives(context, revision, directives):
    """This is called by revision command, but NOT by merge command"""
    from app.unique_number import next_number
    migration_script = directives[0]
    migration_script.rev_id = str(next_number())

This works because merge() calls util.rev_id() directly (command.py:337), but it's fragile.

Why This Isn't Ideal

1. Fragile: Relies on Alembic internals; breaks if implementation changes
2. Non-obvious: Requires patching two module references
3. Inconsistent with revision command: Can't use the same hook mechanism
4. Global effect: Can't have different logic per command when needed
5. Maintenance burden: Requires extensive documentation

Questions

Given the architectural differences you've pointed out:

1. Is there a recommended way to customize merge's revision ID generation without monkey patching?
2. Would you consider making merge() respect the process_revision_directives hook from env.py when revision_environment=true, similar to how revision() does for both autogenerate and non-autogenerate cases?
3. Or is the current approach (using rev_id parameter or monkey patch) the intended way forward?

I understand this might require more work than I initially suggested. If there's interest but concern about implementation complexity, I'm willing to help with implementation or testing.

[zzzeek]

OK there's obviously a lot of AI writing these responses so if maybe you can step out and take a look at what's happening -

if your program is calling revision(), merge() etc. programmatically, you can pass rev_id right in as an argument to those functions. Alembic's rev_id generator is not used. Similarly, this same "rev_id" argument is available on the command line:

usage: alembic revision [-h] [-m MESSAGE] [--autogenerate] [--sql] [--head HEAD] [--splice] [--branch-label BRANCH_LABEL] [--version-path VERSION_PATH] [--rev-id REV_ID]
                        [--depends-on DEPENDS_ON]

options:
  -h, --help            show this help message and exit
  -m, --message MESSAGE
                        Message string to use with 'revision'
  --autogenerate        Populate revision script with candidate migration operations, based on comparison of database to model.
  --sql                 Don't emit SQL to database - dump to standard output/file instead. See docs on offline mode.
  --head HEAD           Specify head revision or <branchname>@head to base new revision on.
  --splice              Allow a non-head revision as the 'head' to splice onto
  --branch-label BRANCH_LABEL
                        Specify a branch label to apply to the new revision
  --version-path VERSION_PATH
                        Specify specific path from config for version file
  --rev-id REV_ID       Specify a hardcoded revision id instead of generating one
  --depends-on DEPENDS_ON
                        Specify one or more revision identifiers which this revision should depend on.

so you always have the ability to pass in the rev_id of your choice.

What we dont have right now is the ability to have a rev-id generator that's enclosed entirely within env.py and takes place automatically. you have to run the command with the rev_id you want passed in ahead of time.

if that's the use case, then that's the feature you're looking for. this has nothing to do with suggesting hacks or tricks, you want the rev_id generator to be pluggable via the EnvironmentContext.

[jiayun]

Thank you for the clarification!

Yes, exactly - I want alembic merge to use a custom rev_id generator automatically (like alembic revision does), instead of having to pass --rev-id manually each time.