migrate library Evolve a schema

Reviewed schema changes and immutable migration histories written in Dart.

Build a Migration for one database engine, record its checksum in a MigrationHistory, then apply the validated history with Migrator. SchemaSnapshot stores physical schema facts without importing live models.

See the migration guide in doc/migrations.md for creation, review, recovery, and deployment workflows.

Classes

Backfill
A reviewed, bounded update using this migration's historical table definition. Expressions and completion SQL are trusted migration code. Primary keys must remain immutable, including in application writes and triggers.
BackfillProgress
Durable counters and primary-key cursors. Keys use lossless strings (binary keys use base64), so JSON transport never rounds 64-bit integer identifiers.
CatalogObject
A live database object outside the schema features modeled by the ORM.
CheckedSql
PostgreSQL autocommit SQL with explicit recovery conditions. Both checks must return exactly one boolean. They describe durable state, not an object name alone.
CheckedTableSql
One reviewed MySQL/MariaDB DDL statement and its complete physical table pre/postconditions. DDL is autocommit; each successful step is checkpointed. A null before means create, a null after means drop, differing names rename.
CheckInfo
An enforced, validated row CHECK read from this database's catalog.
CheckSchema
A row CHECK expression. A null name leaves naming to the database.
Codec<T>
Converts a typed Dart value to database storage and decodes it on reads.
Codecs
Built-in conversions for SQL scalar values, JSON, and exact numeric types.
Column<T> Physical schema metadata
Physical column metadata coupled to the Dart/storage Codec.
ColumnInfo
Actual catalog columns, rather than a claimed migration version.
ComputedColumn
Database-computed SQL using physical column names.
DropConstraint
Resolves the actual PostgreSQL name by a constraint signature. This also works for baselined databases whose constraint names were chosen elsewhere.
DropTable
A reviewed table removal. The SQLite runner checks foreign keys before commit.
ExecuteSql
One trusted SQL statement executed by the migration's transaction runner.
ForeignKey
A database foreign key described with ordered physical column names.
IndexSchema
A simple index over ordered physical columns.
Migration
One reviewed plan for one database engine. A history cannot change engines.
MigrationHistory
Statically imported migrations and their independently recorded fingerprints. Keep these entries in version order. checked validates before returning them.
MigrationProgress
A recorded checkpoint that allows an interrupted migration to resume safely.
MigrationStatus
The identifier and recorded fingerprint of one fully applied migration.
MigrationStep
An explicit operation in a reviewed migration.
Migrator
Validates and executes a fixed history against one raw SQL runtime.
RebuildTable
SQLite's copy-and-replace operation. Expressions are trusted migration SQL. Both snapshots are after any explicit table/column renames.
SchemaRenames
Explicit physical renames. Column maps are keyed by the final table name. Swaps and chains need separate migrations to make intermediate names explicit.
SchemaSnapshot
Physical schema facts saved as Dart with migrations. Storage codecs support DDL; custom domain decoding remains in the generated application client.
SchemaVerification
Differences between a declared snapshot and the live database catalog.
TableInfo
Physical table facts read from the selected database's catalog.
TableSchema Physical schema metadata
Immutable physical table metadata, independent of Dart model identity.

Enums

ComputedStorage
How a database maintains a computed column, subject to engine capabilities.
MigrationStepState
Durable status of one recoverable migration step.
SqlDialect
SQL engine used for quoting, parameter syntax, and capability validation.

Functions

createSchema(List<TableSchema> tables, SqlDialect dialect) → List<SqlCommand>
Creates a new schema. Applications should execute the resulting SQL through reviewed migrations; this does not inspect or mutate an existing database.
inspectColumns(SqlDatabase<Backend> db, String table) → Future<List<ColumnInfo>>
Reads storage types, nullability, defaults, and computed-column metadata.
inspectTable(SqlDatabase<Backend> db, String table) → Future<TableInfo>
Reads one physical table without changing its schema or data.
migrationHistorySource(Iterable<String> ids, {required SqlDialect dialect}) → String
Emits a static registry. Each file owns its recorded fingerprint so rebuilding this registry does not silently accept edited migration definitions.
migrationSource(Migration migration) → String
Emits a reviewed migration and its fixed fingerprint as ordinary Dart values. Formatting/comments are not part of the fingerprint; SQL and operation data are.
schemaSource(SchemaSnapshot schema) → String
Emits a standalone historical schema library, without application imports.
validateMigrations(List<Migration> migrations, {required SqlDialect dialect}) → void
Validates local ordering, checksum links and operations without opening a database.
verifyColumns(SqlDatabase<Backend> db, List<TableSchema> tables) → Future<List<String>>
Column drift check. Constraints, indexes and unmanaged objects are separate catalog checks; this method does not pretend that columns prove full equality.
verifySchema(SqlDatabase<Backend> db, SchemaSnapshot expected) → Future<SchemaVerification>
Compares modeled tables, columns, keys, indexes, and checks with the catalog.

Exceptions / Errors

OrmException
An ORM failure with a stable machine-readable code and optional cause.