tessl/pypi-alembic

A database migration tool for SQLAlchemy.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

CLI Commands

Name: tessl/pypi-alembic
Author: tessl

Complete command-line interface for Alembic migration management. All commands are accessible through the alembic CLI tool and can also be called programmatically through the alembic.command module.

Capabilities

Environment Initialization

Initialize a new Alembic migration environment with configuration files and directory structure.

def init(config, directory, template='generic', package=False):
    """
    Initialize a new migration environment.
    
    Args:
        config (Config): Alembic configuration object
        directory (str): Target directory for migration environment
        template (str): Template to use ('generic', 'multidb', 'async')
        package (bool): Generate __init__.py files for package structure
    """

CLI Usage: alembic init migrations

Revision Management

Create and manage migration revisions with automatic or manual generation.

def revision(config, message=None, autogenerate=False, sql=False, head='head', splice=False, branch_label=None, version_path=None, rev_id=None, depends_on=None, process_revision_directives=None):
    """
    Create a new revision file.
    
    Args:
        config (Config): Alembic configuration object
        message (str): Revision message/description
        autogenerate (bool): Auto-generate migration operations
        sql (bool): Generate SQL output instead of Python code
        head (str): Head revision to base new revision on
        splice (bool): Allow revision to be spliced into existing history
        branch_label (str): Label for new branch
        version_path (str): Path for version files
        rev_id (str): Custom revision identifier
        depends_on (str): Revision dependencies
        process_revision_directives (ProcessRevisionDirectiveFn): Custom revision processing
    
    Returns:
        Union[Optional[Script], List[Optional[Script]]]: Generated script object(s)
    """

def merge(config, revisions, message=None, branch_label=None, rev_id=None):
    """
    Merge multiple revisions into a single new revision.
    
    Args:
        config (Config): Alembic configuration object
        revisions (str): Comma-separated revision identifiers to merge
        message (str): Message for merge revision
        branch_label (str): Branch label for merge revision
        rev_id (str): Custom revision identifier
    
    Returns:
        Optional[Script]: Generated merge script
    """

def edit(config, rev):
    """
    Edit a revision file in configured editor.
    
    Args:
        config (Config): Alembic configuration object
        rev (str): Revision identifier to edit
        
    Returns:
        None
    """

CLI Usage:

alembic revision -m "Create user table"
alembic revision --autogenerate -m "Auto-generate changes"
alembic merge -m "Merge branches" head1 head2
alembic edit abc123

Database Operations

Upgrade and downgrade database schema to specific revisions.

def upgrade(config, revision, sql=False, tag=None):
    """
    Upgrade to a later revision.
    
    Args:
        config (Config): Alembic configuration object
        revision (str): Target revision ('head', 'base', or specific rev)
        sql (bool): Output SQL instead of executing
        tag (str): Tag to apply to revision
        
    Returns:
        None
    """

def downgrade(config, revision, sql=False, tag=None):
    """
    Revert to a previous revision.
    
    Args:
        config (Config): Alembic configuration object
        revision (str): Target revision ('base', '-1', or specific rev)
        sql (bool): Output SQL instead of executing
        tag (str): Tag to apply to revision
    """

def stamp(config, revision, sql=False, tag=None, purge=False):
    """
    Mark revision as current without running migrations.
    
    Args:
        config (Config): Alembic configuration object
        revision (str): Revision to stamp as current
        sql (bool): Output SQL instead of executing
        tag (str): Tag to apply
        purge (bool): Delete all existing revision entries first
    """

CLI Usage:

alembic upgrade head - Upgrade to latest
alembic upgrade +2 - Upgrade 2 revisions forward
alembic downgrade base - Downgrade to initial state
alembic downgrade -1 - Downgrade 1 revision back
alembic stamp head - Mark as current without running

Status and Information

Check migration status and browse revision history.

def current(config, verbose=False):
    """
    Display current revision.
    
    Args:
        config (Config): Alembic configuration object
        verbose (bool): Show detailed information
    """

def history(config, rev_range=None, verbose=False, indicate_current=False):
    """
    List revision history.
    
    Args:
        config (Config): Alembic configuration object
        rev_range (str): Range of revisions to show (e.g., 'base:head')
        verbose (bool): Show detailed information
        indicate_current (bool): Mark current revision
    """

def heads(config, verbose=False, resolve_dependencies=False):
    """
    Show current head revisions.
    
    Args:
        config (Config): Alembic configuration object
        verbose (bool): Show detailed information
        resolve_dependencies (bool): Show dependency resolution
    """

def branches(config, verbose=False):
    """
    Show branch points in revision history.
    
    Args:
        config (Config): Alembic configuration object
        verbose (bool): Show detailed information
    """

def show(config, rev):
    """
    Show information about a revision.
    
    Args:
        config (Config): Alembic configuration object
        rev (str): Revision identifier to show
    """

def check(config):
    """
    Check if revision command is pending.
    
    Args:
        config (Config): Alembic configuration object
        
    Raises:
        CommandError: If autogenerate changes are detected
    """

CLI Usage:

alembic current - Show current revision
alembic history - Show all revisions
alembic history -r base:head - Show range
alembic heads - Show head revisions
alembic branches - Show branch points
alembic show abc123 - Show specific revision
alembic check - Check for pending changes

Utility Commands

Additional utility functions for migration management.

def list_templates(config):
    """
    List available migration templates.
    
    Args:
        config (Config): Alembic configuration object
        
    Returns:
        None: Prints template list to stdout
    """

def ensure_version(config, sql=False):
    """
    Create alembic_version table in target database.
    
    Args:
        config (Config): Alembic configuration object
        sql (bool): Output SQL instead of executing
    """

CLI Usage:

alembic list_templates - Show available templates
alembic ensure_version - Create version table

Command Line Examples

Basic Workflow

# Initialize environment
alembic init migrations

# Create first migration
alembic revision -m "Initial migration"

# Auto-generate migration from models
alembic revision --autogenerate -m "Add user table"

# Apply migrations
alembic upgrade head

# Check current status
alembic current

# View history
alembic history --verbose

# Rollback one revision
alembic downgrade -1

Advanced Usage

# Create branch
alembic revision -m "Feature branch" --branch-label=feature

# Merge branches
alembic merge -m "Merge feature" head feature

# Generate SQL without executing
alembic upgrade head --sql

# Stamp without running migrations  
alembic stamp head

# Check for pending autogenerate changes
alembic check

Environment Variables and Configuration

Commands respect configuration from alembic.ini and can be overridden:

# Use different config file
alembic -c custom.ini upgrade head

# Override database URL
alembic -x dbname=testdb upgrade head

# Use different script location
alembic -x script_location=custom/migrations current

Return Values

All command functions return relevant objects:

revision(), merge(): Return Script objects
list_templates(): Returns list of template names
Status commands (current, history, etc.): Print to stdout/configured output
Database operations (upgrade, downgrade): No return value, raise exceptions on error

Error Handling

Commands raise specific exceptions:

CommandError: General command execution errors
RevisionError: Revision-related errors
SQLAlchemy exceptions: Database connection/execution errors

Types

# Command function protocol
class CommandFunction(Protocol):
    def __call__(self, config: Config, *args, **kwargs): ...

# Script object returned by revision commands
class Script:
    revision: str
    down_revision: Optional[str]
    branch_labels: Optional[Set[str]]
    depends_on: Optional[Set[str]]
    path: str

Install with Tessl CLI