Alternative Approaches to Generate Sequential Revision IDs in Alembic

sqlalchemy database migration alembic

Alembic and Revision IDs

  • Alembic is a popular Python tool used for migrating database schemas in SQLAlchemy applications.
  • It tracks changes to your database structure through version control using revision scripts.
  • Each revision script has a unique identifier, called a revision ID.

Default Revision ID Generation

  • By default, Alembic generates revision IDs using a cryptographic hash.
    • This hash is based on the contents of the revision script file.
    • It ensures uniqueness but doesn't necessarily reflect the order of migrations.

Why Sequential Revision IDs Might Be Desired

  • In some cases, developers might prefer revision IDs to be sequential (e.g., v1, v2, v3).
    • This can provide a clearer sense of the migration order, especially for manual inspection or debugging.

Alembic Doesn't Support Native Sequential IDs

  • Alembic itself doesn't offer a built-in way to generate sequential revision IDs.

Alternative Approaches

  1. Custom Script with Timestamps

    • Write a script that generates revision IDs based on timestamps (e.g., 20240322_1430).
    • Trigger this script before running alembic revision.
    • Pass the generated ID as the --rev-id flag to alembic revision.
  2. Manual Naming

    • Manually name your revision files with sequential numbers (e.g., 001_initial_migration.py, 002_add_user_table.py).
    • This approach requires strict discipline to avoid naming conflicts.


  • Sequential IDs might not be strictly necessary for Alembic's functionality.
  • The cryptographic hash approach ensures uniqueness, which is crucial for migrations.
  • If order clarity is a concern, consider using timestamps or version numbers within your migration scripts for better readability.

In summary:

  • Alembic's default revision IDs are unique but not sequential.
  • Consider alternative approaches if strict order visibility is necessary.
  • Prioritize code maintainability and choose a method that fits your workflow.

Custom Script with Timestamps (Python):

import datetime
import uuid

def generate_revision_id():
    now = datetime.datetime.now().strftime("%Y%m%d_%H%M")
    random_suffix = uuid.uuid4().hex[-12:]  # Get the last 12 characters of a UUID
    return f"{now}_{random_suffix}"

# Example usage (assuming you run this script before `alembic revision`)
revision_id = generate_revision_id()
alembic_command = ["alembic", "revision", "--autogenerate", "--rev-id", revision_id]
# Execute the alembic command with the generated revision ID

Manual Naming (Example File Structure):


Points to Remember:

  • The custom script approach provides more control over the revision ID format but requires an additional step before running alembic revision.
  • Manual naming is simpler but requires discipline to maintain sequential numbering and avoid conflicts.
  • Consider your team's workflow and preferred level of automation when choosing a method.

Custom Alembic Configuration

This approach involves extending Alembic's configuration to implement a custom revision ID generation function. It requires more in-depth knowledge of Alembic's internals but offers greater flexibility. Here's a general outline:

  • Create a custom class that inherits from alembic.config.Config.
  • Override the get_head_revision() method to retrieve the latest revision ID (if needed).
  • Implement a new method (e.g., generate_sequential_id()) that generates the sequential ID based on your logic.
  • In the generate_revision() or autogenerate_revision() method, use the generated ID instead of the default one.

Version Control Integration

If you're using a version control system (VCS) like Git for managing your migration scripts, you could potentially leverage its revision numbering scheme. This might involve:

  • Using a custom script to extract the current VCS revision number.
  • Prefixing the Alembic revision ID with the VCS revision number for a combined identifier.

Database Sequence (Advanced)

For advanced scenarios, you could potentially explore using a database sequence to generate revision IDs directly within the migration scripts. However, this approach requires careful management and might not be suitable for all database platforms:

  • Create a database sequence specifically for generating revision IDs.
  • Access the sequence value within your migration script and use it as the revision ID.

Choosing the Right Approach

The best approach depends on your specific needs and preferences:

  • Simplicity: Manual naming is the simplest but requires discipline.
  • Control: Custom script provides control over the format but adds an extra step.
  • Flexibility: Custom Alembic configuration offers the most flexibility but demands deeper Alembic knowledge.
  • Integration: VCS integration leverages existing version control but might require additional scripting.
  • Database-Specific: Database sequence is advanced, platform-dependent, and requires careful management.

Consider factors like maintainability, team workflow, and desired level of automation when making your choice.

sqlalchemy database-migration alembic