Migrations¶

from sqlspec.migrations import (
    AsyncMigrationCommands,
    AsyncMigrationRunner,
    AsyncMigrationTracker,
    MigrationSquasher,
    PythonFileLoader,
    SchemaEnsureResult,
    SchemaTarget,
    SQLFileLoader,
    SquashPlan,
    SyncMigrationCommands,
    SyncMigrationRunner,
    SyncMigrationTracker,
    create_migration_commands,
    create_migration_runner,
    ensure_schema_async,
    ensure_schema_sync,
)

Programmatic schema migration commands, SQL and Python migration loaders, version table trackers, declarative schema targets, and migration squashing. See the Migrations Guide for end-to-end workflows.

Migration Commands¶

SyncMigrationCommands ¶

Bases: BaseMigrationCommands['SyncConfigT', Any]

Synchronous migration commands.

init ¶

init(directory, package=True)

Initialize migration directory structure.

Parameters:

Name	Type	Description	Default
`directory`	`str`	Directory to initialize migrations in.	required
`package`	`bool`	Whether to create init.py file.	`True`

current ¶

current(verbose=False)

Show current migration version.

Parameters:

Name	Type	Description	Default
`verbose`	`bool`	Whether to show detailed migration history.	`False`

Returns:

Type	Description
`str \| None`	The current migration version or None if no migrations applied.

upgrade ¶

upgrade(
    revision="head",
    allow_missing=False,
    auto_sync=True,
    dry_run=False,
    *,
    use_logger=False,
    echo=None,
    summary_only=None,
)

Upgrade to a target revision.

Validates migration order and warns if out-of-order migrations are detected. Out-of-order migrations can occur when branches merge in different orders across environments.

Parameters:

Name	Type	Description	Default
`revision`	`str`	Target revision or "head" for latest.	`'head'`
`allow_missing`	`bool`	If True, allow out-of-order migrations even in strict mode. Defaults to False.	`False`
`auto_sync`	`bool`	If True, automatically reconcile renamed migrations in database. Defaults to True. Can be disabled via --no-auto-sync flag.	`True`
`dry_run`	`bool`	If True, show what would be done without making changes.	`False`
`use_logger`	`bool`	If True, output to logger instead of Rich console. Defaults to False. Can be set via MigrationConfig for persistent default.	`False`
`echo`	`bool \| None`	Echo output to the console. Defaults to True when unset.	`None`
`summary_only`	`bool \| None`	Emit a single summary log entry when logger output is enabled.	`None`

downgrade ¶

downgrade(
    revision="-1",
    *,
    dry_run=False,
    use_logger=False,
    echo=None,
    summary_only=None,
)

Downgrade to a target revision.

Parameters:

Name	Type	Description	Default
`revision`	`str`	Target revision or "-1" for one step back.	`'-1'`
`dry_run`	`bool`	If True, show what would be done without making changes.	`False`
`use_logger`	`bool`	If True, output to logger instead of Rich console. Defaults to False. Can be set via MigrationConfig for persistent default.	`False`
`echo`	`bool \| None`	Echo output to the console. Defaults to True when unset.	`None`
`summary_only`	`bool \| None`	Emit a single summary log entry when logger output is enabled.	`None`

stamp ¶

stamp(revision)

Mark database as being at a specific revision without running migrations.

Parameters:

Name	Type	Description	Default
`revision`	`str`	The revision to stamp.	required

squash ¶

squash(
    start_version=None,
    end_version=None,
    description=None,
    *,
    dry_run=False,
    update_database=True,
    yes=False,
    allow_gaps=False,
    output_format="sql",
)

Squash a range of migrations into a single file.

Combines multiple sequential migrations into a single "release" migration. UP statements are merged in version order, DOWN statements in reverse order.

Parameters:

Name	Type	Description	Default
`start_version`	`str \| None`	First version in the range to squash (inclusive). When None, defaults to the first sequential migration found.	`None`
`end_version`	`str \| None`	Last version in the range to squash (inclusive). When None, defaults to the last sequential migration found.	`None`
`description`	`str \| None`	Description for the squashed migration file. When None, prompts interactively.	`None`
`dry_run`	`bool`	Preview changes without applying.	`False`
`update_database`	`bool`	Update migration records in database.	`True`
`yes`	`bool`	Skip confirmation prompt.	`False`
`allow_gaps`	`bool`	Allow gaps in version sequence.	`False`
`output_format`	`str`	Output format ("sql" or "py").	`'sql'`

AsyncMigrationCommands ¶

Bases: BaseMigrationCommands['AsyncConfigT', Any]

Asynchronous migration commands.

create_migration_commands ¶

create_migration_commands(config)

Factory function to create the appropriate migration commands.

Parameters:

Name	Type	Description	Default
`config`	`SyncConfigT \| AsyncConfigT`	The SQLSpec configuration.	required

Returns:

Type	Description
`SyncMigrationCommands[SyncConfigT] \| AsyncMigrationCommands[AsyncConfigT]`	Appropriate migration commands instance.

Migration Runners & Trackers¶

SyncMigrationRunner ¶

Bases: BaseMigrationRunner

Synchronous migration runner with pure sync methods.

AsyncMigrationRunner ¶

Bases: BaseMigrationRunner

Asynchronous migration runner with pure async methods.

SyncMigrationTracker ¶

Bases: BaseMigrationTracker['SyncDriverAdapterBase']

Synchronous migration version tracker.

AsyncMigrationTracker ¶

Bases: BaseMigrationTracker['AsyncDriverAdapterBase']

Asynchronous migration version tracker.

Migration Loaders¶

BaseMigrationLoader ¶

Abstract base class for migration loaders.

SQLFileLoader ¶

Bases: BaseMigrationLoader

Loader for SQL migration files.

PythonFileLoader ¶

Bases: BaseMigrationLoader

Loader for Python migration files.

Declarative Schema & Squashing¶

SchemaTarget ¶

Describe one table's target schema.

Parameters:

Name	Type	Description	Default
`table_name`	`str`	Unqualified table name used for introspection and DDL.	required
`create_table`	`CreateTable`	Builder containing the target columns and create DDL.	required
`schema`	`str \| None`	Optional schema containing the table.	`None`

SchemaEnsureResult ¶

Summarize changes made by an ensure operation.

ensure_schema_async ¶

ensure_schema_async(
    driver,
    targets,
    *,
    manage_schema=False,
    create_schema=True,
    run_migrations=False,
    migration_runner=None,
    assume_existing=False,
)

Apply additive target-schema changes with an asynchronous driver.

Parameters:

Name	Type	Description	Default
`driver`	`Any`	Asynchronous driver used for introspection and DDL.	required
`targets`	`Sequence[SchemaTarget]`	Target table descriptors.	required
`manage_schema`	`bool`	Enable automatic table and column management.	`False`
`create_schema`	`bool`	Create target tables that are absent.	`True`
`run_migrations`	`bool`	Run the explicit migration callback first.	`False`
`migration_runner`	`Callable[[Any], Awaitable[None]] \| None`	Explicit asynchronous migration callback.	`None`
`assume_existing`	`bool`	Skip table discovery when the caller already ensured the tables.	`False`

Returns:

Type	Description
`SchemaEnsureResult`	Summary of created tables, added columns, and deferred targets.

Raises:

Type	Description
`ValueError`	If explicit migrations are enabled without a runner.

MigrationSquasher ¶

Core squash engine for combining migrations.

Provides functionality to plan, validate, and execute migration squash operations. Combines multiple sequential migrations into a single file with merged UP/DOWN SQL.