tessl/pypi-flask-migrate

SQLAlchemy database migrations for Flask applications using Alembic.

Overview

Eval results

Files

Information and History

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

Database migration history, status, and inspection operations. These functions provide visibility into the current migration state, historical changes, and database versioning information without modifying the database.

Capabilities

Current Database State

Displays the current revision for each database, showing which migrations have been applied.

def current(directory=None, verbose=False):
    """
    Display the current revision for each database.
    
    Parameters:
    - directory (str, optional): Migration script directory
    - verbose (bool): Use more verbose output (default: False)
    
    Returns:
    None (prints current revision information)
    
    Raises:
    CommandError: If unable to determine current revision
    RuntimeError: If Flask app context is not available
    """

Usage Example:

from flask_migrate import current

# Show current revision
current()

# Show detailed current revision info
current(verbose=True)

Migration History

Lists migration scripts in chronological order, providing a complete audit trail of database changes.

def history(directory=None, rev_range=None, verbose=False, indicate_current=False):
    """
    List changeset scripts in chronological order.
    
    Parameters:
    - directory (str, optional): Migration script directory
    - rev_range (str, optional): Specify a revision range; format is [start]:[end]
    - verbose (bool): Use more verbose output (default: False)
    - indicate_current (bool): Indicate current version - requires Alembic 0.9.9+ (default: False)
    
    Returns:
    None (prints migration history)
    
    Raises:
    CommandError: If unable to retrieve history
    RuntimeError: If Flask app context is not available
    """

Usage Example:

from flask_migrate import history

# Show all migration history
history()

# Show verbose history
history(verbose=True)

# Show history with current revision indicated
history(indicate_current=True)

# Show history for specific range
history(rev_range='base:head')

Revision Details

Shows detailed information about a specific revision including the migration script content.

def show(directory=None, revision='head'):
    """
    Show the revision denoted by the given symbol.
    
    Parameters:
    - directory (str, optional): Migration script directory
    - revision (str): Revision to show (default: 'head')
    
    Returns:
    None (prints revision details)
    
    Raises:
    CommandError: If revision not found
    RuntimeError: If Flask app context is not available
    """

Usage Example:

from flask_migrate import show

# Show latest revision
show()

# Show specific revision
show(revision='ae1027a6acf')

# Show base revision
show(revision='base')

Head Revisions

Shows current available head revisions in the migration script directory.

def heads(directory=None, verbose=False, resolve_dependencies=False):
    """
    Show current available heads in the script directory.
    
    Parameters:
    - directory (str, optional): Migration script directory
    - verbose (bool): Use more verbose output (default: False)
    - resolve_dependencies (bool): Treat dependency versions as down revisions (default: False)
    
    Returns:
    None (prints head revision information)
    
    Raises:
    CommandError: If unable to determine heads
    RuntimeError: If Flask app context is not available
    """

Usage Example:

from flask_migrate import heads

# Show current heads
heads()

# Show verbose head information
heads(verbose=True)

# Show heads with dependency resolution
heads(resolve_dependencies=True)

Branch Points

Shows current branch points in the migration history, useful for managing parallel development branches.

def branches(directory=None, verbose=False):
    """
    Show current branch points.
    
    Parameters:
    - directory (str, optional): Migration script directory
    - verbose (bool): Use more verbose output (default: False)
    
    Returns:
    None (prints branch point information)
    
    Raises:
    CommandError: If unable to determine branches
    RuntimeError: If Flask app context is not available
    """

Usage Example:

from flask_migrate import branches

# Show branch points
branches()

# Show verbose branch information
branches(verbose=True)

Database Stamping

Marks the revision table with a specific revision without running migrations, useful for initializing migration tracking on existing databases.

def stamp(directory=None, revision='head', sql=False, tag=None):
    """
    'Stamp' the revision table with the given revision; don't run any migrations.
    
    Parameters:
    - directory (str, optional): Migration script directory
    - revision (str): Revision to stamp (default: 'head')
    - sql (bool): Don't emit SQL to database - dump to standard output instead (default: False)
    - tag (str, optional): Arbitrary "tag" name - can be used by custom env.py scripts
    
    Returns:
    None
    
    Raises:
    CommandError: If stamping fails
    RuntimeError: If Flask app context is not available
    """

Usage Example:

from flask_migrate import stamp

# Stamp database as current head
stamp()

# Stamp specific revision
stamp(revision='ae1027a6acf')

# Stamp with SQL output only
stamp(sql=True)

# Stamp with custom tag
stamp(tag='initial_stamp')

Information Workflow

Common patterns for inspecting migration state:

from flask_migrate import current, history, show, heads

# Check current database state
current(verbose=True)

# Review migration history
history(verbose=True, indicate_current=True)

# Examine specific migration
show(revision='ae1027a6acf')

# Check for multiple heads (potential branching issues)
heads()