tessl/pypi-flask-migrate

SQLAlchemy database migrations for Flask applications using Alembic.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

CLI Interface

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

Flask CLI integration that provides command-line access to all migration functionality through the flask db command group. The CLI interface mirrors all programmatic API functions with additional command-line specific options and help text.

Capabilities

Command Group

Main CLI entry point that groups all database migration commands under a single command namespace.

@click.group()
@click.option('-d', '--directory', default=None,
              help='Migration script directory (default is "migrations")')
@click.option('-x', '--x-arg', multiple=True,
              help='Additional arguments consumed by custom env.py scripts')
@with_appcontext
def db(directory, x_arg):
    """Perform database migrations."""

Core Migration Commands

Essential CLI commands for the primary migration workflow.

# Initialize migration repository
flask db init [OPTIONS]

# Create new revision file  
flask db revision [OPTIONS]

# Auto-generate migration (alias for revision --autogenerate)
flask db migrate [OPTIONS]

# Upgrade to later version
flask db upgrade [OPTIONS] [REVISION]

# Downgrade to previous version  
flask db downgrade [OPTIONS] [REVISION]

Revision Management Commands

CLI commands for advanced revision control operations.

# Edit revision file
flask db edit [OPTIONS] [REVISION]

# Merge revisions together
flask db merge [OPTIONS] [REVISIONS]...

# Stamp revision table without running migrations
flask db stamp [OPTIONS] [REVISION]

Information Commands

CLI commands for inspecting migration state and history.

# Show revision information
flask db show [OPTIONS] [REVISION]

# List changeset scripts in chronological order
flask db history [OPTIONS]

# Show current available heads
flask db heads [OPTIONS]

# Show current branch points
flask db branches [OPTIONS]

# Display current revision for each database
flask db current [OPTIONS]

# Check if there are any new operations to migrate
flask db check [OPTIONS]

# List available templates
flask db list-templates

Command Details

Initialize Repository

flask db init [OPTIONS]

Options:
  -d, --directory TEXT    Migration script directory (default is "migrations")
  --multidb               Support multiple databases
  -t, --template TEXT     Repository template to use (default is "flask")
  --package               Write empty __init__.py files to environment and version locations
  --help                  Show this message and exit

Create Revision

flask db revision [OPTIONS]

Options:
  -d, --directory TEXT        Migration script directory (default is "migrations")
  -m, --message TEXT         Revision message
  --autogenerate             Populate revision script with candidate migration operations
  --sql                      Don't emit SQL to database - dump to standard output instead
  --head TEXT                Specify head revision or <branchname>@head to base new revision on
  --splice                   Allow a non-head revision as the "head" to splice onto
  --branch-label TEXT        Specify a branch label to apply to the new revision
  --version-path TEXT        Specify specific path from config for version file
  --rev-id TEXT             Specify a hardcoded revision id instead of generating one
  --help                    Show this message and exit

Auto-generate Migration

flask db migrate [OPTIONS]

Options:
  -d, --directory TEXT        Migration script directory (default is "migrations")
  -m, --message TEXT         Revision message
  --sql                      Don't emit SQL to database - dump to standard output instead
  --head TEXT                Specify head revision or <branchname>@head to base new revision on
  --splice                   Allow a non-head revision as the "head" to splice onto
  --branch-label TEXT        Specify a branch label to apply to the new revision
  --version-path TEXT        Specify specific path from config for version file
  --rev-id TEXT             Specify a hardcoded revision id instead of generating one
  -x, --x-arg TEXT          Additional arguments consumed by custom env.py scripts (multiple)
  --help                    Show this message and exit

Upgrade Database

flask db upgrade [OPTIONS] [REVISION]

Options:
  -d, --directory TEXT    Migration script directory (default is "migrations")
  --sql                  Don't emit SQL to database - dump to standard output instead
  --tag TEXT            Arbitrary "tag" name - can be used by custom env.py scripts
  -x, --x-arg TEXT      Additional arguments consumed by custom env.py scripts (multiple)
  --help                Show this message and exit

Arguments:
  REVISION              Target revision (default: head)

Downgrade Database

flask db downgrade [OPTIONS] [REVISION]

Options:
  -d, --directory TEXT    Migration script directory (default is "migrations")
  --sql                  Don't emit SQL to database - dump to standard output instead
  --tag TEXT            Arbitrary "tag" name - can be used by custom env.py scripts
  -x, --x-arg TEXT      Additional arguments consumed by custom env.py scripts (multiple)
  --help                Show this message and exit

Arguments:
  REVISION              Target revision (default: -1)

Usage Examples

Basic CLI Workflow

# Set Flask app environment variable
export FLASK_APP=myapp

# Initialize migration repository
flask db init

# Create initial migration
flask db migrate -m "Initial migration"

# Apply migration to database
flask db upgrade

# Create new migration after model changes
flask db migrate -m "Add user email field"

# Apply new migration
flask db upgrade

Advanced CLI Operations

# Initialize with multi-database support
flask db init --multidb

# Create manual revision (no autogenerate)
flask db revision -m "Custom changes"

# Generate SQL without executing
flask db upgrade --sql

# Downgrade two steps
flask db downgrade -2

# Upgrade to specific revision
flask db upgrade abc123

# Show migration history
flask db history --verbose

# Check current status
flask db current

Template and Information Commands

# List available templates
flask db list-templates

# Initialize with custom template
flask db init -t flask-multidb

# Show specific revision details
flask db show abc123

# Show branch information
flask db branches --verbose

# Merge revisions
flask db merge abc123 def456 -m "Merge feature branches"

Custom Environment Arguments

# Pass custom arguments to env.py scripts
flask db upgrade -x custom_arg=value

# Multiple custom arguments
flask db migrate -x db=users -x schema=public -m "Multi-db migration"

Global Options

All commands support global directory and x-arg options:

# Use custom migration directory for all commands
flask db -d custom_migrations init
flask db -d custom_migrations migrate -m "Custom location"

# Pass custom arguments globally
flask db -x global_arg=value migrate -m "Global custom arg"

Install with Tessl CLI