CtrlK

Community Documentation Log in Get started

tessl/pypi-flask-migrate

SQLAlchemy database migrations for Flask applications using Alembic.

Overview

Eval results

Files

Advanced Operations

Name: tessl/pypi-flask-migrate
Author: tessl

Advanced migration operations for complex scenarios including merging branches, editing revisions, and template management. These functions handle sophisticated migration workflows and customization requirements.

Capabilities

Branch Merging

Merges two revisions together to resolve branching in migration history, creating a new migration file that combines multiple development paths.

def merge(directory=None, revisions='', message=None, branch_label=None, rev_id=None):
    """
    Merge two revisions together, creating a new migration file.
    
    Parameters:
    - directory (str, optional): Migration script directory
    - revisions (str): Revisions to merge (space-separated)
    - message (str, optional): Merge revision message
    - branch_label (str, optional): Specify a branch label to apply to the new revision
    - rev_id (str, optional): Specify a hardcoded revision id instead of generating one
    
    Returns:
    None
    
    Raises:
    CommandError: If merge fails or revisions are invalid
    RuntimeError: If Flask app context is not available
    """

Usage Example:

from flask_migrate import merge

# Merge two specific revisions
merge(revisions='ae1027a6acf 1975ea83b712', message="Merge feature branches")

# Merge with custom branch label
merge(revisions='head1 head2', message="Merge parallel changes", branch_label="merged")

# Merge with specific revision ID
merge(revisions='branch1 branch2', message="Controlled merge", rev_id="custom_merge_001")

Revision Editing

Edits an existing revision file, opening it in the configured editor for manual modification.

def edit(directory=None, revision='current'):
    """
    Edit a revision file.
    
    Parameters:
    - directory (str, optional): Migration script directory
    - revision (str): Revision to edit (default: 'current')
    
    Returns:
    None
    
    Raises:
    CommandError: If revision not found or editing fails
    RuntimeError: If Alembic version is less than 0.8.0 or Flask app context is not available
    """

Usage Example:

from flask_migrate import edit

# Edit current revision
edit()

# Edit specific revision
edit(revision='ae1027a6acf')

# Edit head revision
edit(revision='head')

Requirements:

Alembic 0.8.0 or greater
Configured text editor (via EDITOR environment variable or Alembic configuration)

Template Management

Lists available migration templates that can be used when initializing new migration repositories.

def list_templates():
    """
    List available templates.
    
    Parameters:
    None
    
    Returns:
    None (prints available templates with descriptions)
    
    Raises:
    CommandError: If unable to list templates
    """

Usage Example:

from flask_migrate import list_templates

# Show all available templates
list_templates()

Available Templates:

flask: Single-database configuration for Flask applications
flask-multidb: Multi-database configuration for Flask applications
aioflask: Single-database configuration for async Flask applications
aioflask-multidb: Multi-database configuration for async Flask applications

Advanced Workflow Scenarios

Handling Branched Development

When multiple developers create migrations simultaneously, you may encounter branched history:

from flask_migrate import heads, merge, upgrade

# Check for multiple heads
heads()

# If multiple heads exist, merge them
merge(revisions='head1 head2', message="Merge parallel development")

# Apply the merged migration
upgrade()

Custom Template Usage

Using custom templates for specialized migration setups:

from flask_migrate import init, list_templates

# List available templates first
list_templates()

# Initialize with specific template
init(template='flask-multidb')

# Initialize with custom template path
init(template='/path/to/custom/template')

Manual Migration Editing

For complex migrations that require manual adjustment:

from flask_migrate import migrate, edit, upgrade

# Generate initial migration
migrate(message="Complex schema changes")

# Edit the generated migration manually
edit()

# Apply the edited migration
upgrade()

Database Synchronization

For existing databases that need migration tracking:

from flask_migrate import stamp, init, current

# Initialize migration repository
init()

# Stamp existing database with current schema state
stamp(revision='head')

# Verify stamping
current(verbose=True)

Error Handling and Recovery

Resolving Migration Conflicts

from flask_migrate import current, history, edit, merge

# Check current state
current(verbose=True)

# Review problematic migrations
history(verbose=True)

# Edit problematic migration if needed
edit(revision='problematic_revision')

# Or merge conflicting branches
merge(revisions='branch1 branch2', message="Resolve conflicts")

Alembic Version Compatibility

The edit() function requires Alembic 0.8.0 or greater. If using an older version:

try:
    from flask_migrate import edit
    edit()
except RuntimeError as e:
    print("Alembic 0.8.0 or greater is required for editing")

CLI Equivalents

Each function has a corresponding Flask CLI command:

merge() → flask db merge
edit() → flask db edit
list_templates() → flask db list_templates

tessl i tessl/pypi-flask-migrate@3.1.0

docs

advanced-operations.md

index.md

information-history.md

migration-management.md

tile.json

tessl/pypi-flask-migrate