Migration Management

def init(directory=None, multidb=False, template=None, package=False):
    """
    Creates a new migration repository.
    
    Parameters:
    - directory (str, optional): Migration script directory (default: 'migrations')
    - multidb (bool): Support multiple databases (default: False)
    - template (str, optional): Repository template to use (default: 'flask')
    - package (bool): Write empty __init__.py files to environment and version locations (default: False)
    
    Returns:
    None
    
    Raises:
    CommandError: If repository already exists or initialization fails
    RuntimeError: If Flask app context is not available
    """

from flask_migrate import init

# Initialize basic migration repository
init()

# Initialize with custom directory
init(directory='custom_migrations')

# Initialize for multi-database setup
init(multidb=True)

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

def revision(directory=None, message=None, autogenerate=False, sql=False, head='head', splice=False, branch_label=None, version_path=None, rev_id=None):
    """
    Create a new revision file.
    
    Parameters:
    - directory (str, optional): Migration script directory
    - message (str, optional): Revision message for the migration file
    - autogenerate (bool): Populate revision script with candidate migration operations (default: False)  
    - sql (bool): Don't emit SQL to database - dump to standard output instead (default: False)
    - head (str): Specify head revision or <branchname>@head to base new revision on (default: 'head')
    - splice (bool): Allow a non-head revision as the "head" to splice onto (default: False)
    - branch_label (str, optional): Specify a branch label to apply to the new revision
    - version_path (str, optional): Specify specific path from config for version file
    - rev_id (str, optional): Specify a hardcoded revision id instead of generating one
    
    Returns:
    None
    
    Raises:
    CommandError: If revision creation fails
    RuntimeError: If Flask app context is not available
    """

from flask_migrate import revision

# Create empty revision
revision(message="Add user table")

# Create revision with autogeneration
revision(message="Update user schema", autogenerate=True)

# Create revision on specific branch
revision(message="Feature branch change", branch_label="feature")

def migrate(directory=None, message=None, sql=False, head='head', splice=False, branch_label=None, version_path=None, rev_id=None, x_arg=None):
    """
    Autogenerate a new revision file (Alias for 'revision --autogenerate').
    
    Parameters:
    - directory (str, optional): Migration script directory
    - message (str, optional): Revision message for the migration file
    - sql (bool): Don't emit SQL to database - dump to standard output instead (default: False)
    - head (str): Specify head revision or <branchname>@head to base new revision on (default: 'head')
    - splice (bool): Allow a non-head revision as the "head" to splice onto (default: False)
    - branch_label (str, optional): Specify a branch label to apply to the new revision
    - version_path (str, optional): Specify specific path from config for version file
    - rev_id (str, optional): Specify a hardcoded revision id instead of generating one
    - x_arg (tuple, optional): Additional arguments consumed by custom env.py scripts
    
    Returns:
    None
    
    Raises:
    CommandError: If migration generation fails
    RuntimeError: If Flask app context is not available
    """

from flask_migrate import migrate

# Generate migration automatically
migrate(message="Auto-detected changes")

# Generate with custom arguments for env.py
migrate(message="Custom migration", x_arg=('custom_arg', 'value'))

# Generate SQL output without applying
migrate(message="Review changes", sql=True)

def upgrade(directory=None, revision='head', sql=False, tag=None, x_arg=None):
    """
    Upgrade to a later version.
    
    Parameters:
    - directory (str, optional): Migration script directory
    - revision (str): Target revision (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
    - x_arg (tuple, optional): Additional arguments consumed by custom env.py scripts
    
    Returns:
    None
    
    Raises:
    CommandError: If upgrade fails
    RuntimeError: If Flask app context is not available
    """

from flask_migrate import upgrade

# Upgrade to latest version
upgrade()

# Upgrade to specific revision
upgrade(revision='ae1027a6acf')

# Upgrade with SQL output only
upgrade(sql=True)

# Upgrade with custom tag
upgrade(tag='production_deploy')

def downgrade(directory=None, revision='-1', sql=False, tag=None, x_arg=None):
    """
    Revert to a previous version.
    
    Parameters:
    - directory (str, optional): Migration script directory
    - revision (str): Target revision (default: '-1' for one step back)
    - 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
    - x_arg (tuple, optional): Additional arguments consumed by custom env.py scripts
    
    Returns:
    None
    
    Raises:
    CommandError: If downgrade fails
    RuntimeError: If Flask app context is not available
    """

from flask_migrate import downgrade

# Downgrade one step
downgrade()

# Downgrade to specific revision  
downgrade(revision='base')

# Downgrade with SQL output only
downgrade(sql=True)

# Downgrade multiple steps
downgrade(revision='-3')

from flask_migrate import init, migrate, upgrade, downgrade

# 1. Initialize repository (once per project)
init()

# 2. Generate migration after model changes
migrate(message="Add user table")

# 3. Review generated migration file, then apply
upgrade()

# 4. If needed, rollback changes
downgrade()