Expand description
Declarative, self-verifying migrations for PostgreSQL and SQLite.
Most applications should use an adapter crate rather than implement Db:
migratrom-sqlite for a sqlx::SqlitePool
or migratrom-postgres for a
sqlx::PgPool. Each adapter exposes an apply_migrations convenience function
that acquires and pins one connection for the complete migration run.
§The migration model
A Migration is a node in a parent/child DAG containing ordered
Operations. Construct operations with operations’ builders, then pass
the complete migration list to an adapter. The runner:
- creates and reads its history table;
- verifies checksums for migrations already in that table;
- orders pending migrations by their parent relationship; and
- executes each operation as postcheck → precheck → DDL → postcheck.
A passing postcheck skips an operation, so operations are idempotent. Editing the operation body of an applied migration causes a checksum failure rather than silently changing recorded history.
§Define migrations
Build migrations with a dialect matching the database that will apply them. This example only constructs the migration; see the adapter crates for pool setup and execution.
use migratrom::operations::{add_column, create_table};
use migratrom::{ColumnDef, Migration, PrimaryKey, SqliteDialect};
let dialect = SqliteDialect;
let users = Migration::new(
1,
None,
vec![create_table(
"main",
"users",
&[ColumnDef::new("id", "INTEGER"), ColumnDef::new("email", "TEXT")],
Some(&PrimaryKey { columns: vec!["id".into()] }),
&dialect,
)?],
);
let add_name = Migration::new(
2,
Some(users.id),
vec![add_column(
"main",
"users",
&ColumnDef::new("name", "TEXT").nullable(true),
&dialect,
)?],
);
let _: Vec<Migration> = vec![users, add_name];§Applying safely
ApplyOptions controls the history-table name, dry runs, advisory locking,
and progress logging. A dry run executes read-only checks but performs no DDL
or history writes. PostgreSQL migrations acquire an advisory lock by default;
SQLite does not support advisory locks. A migration normally runs in one
transaction. An Operation::outside_transaction operation, such as a
concurrent PostgreSQL index, divides it into transactional segments.
§Advanced integrations
Implement Db only when an application cannot use the provided sqlx
adapters. Implement SqlDialect to support another database engine. Use
MigrationLogger to integrate migration progress with an application’s
logging system.
For supported schema changes, start with the operations cookbook. For
manually authored DDL, use operations::raw_sql and supply explicit checks.
Modules§
- checksum
- Migration checksum API: canonical encoding, digesting, parsing, and verification.
- operations
- Schema-change cookbook.
Structs§
- Applied
Record - A stored history row, used to checksum-verify already-applied migrations.
- Apply
Options - Options controlling an apply run.
- Apply
Result - The result of applying migrations.
- Check
- A boolean-returning SQL probe. Must yield one row / one column / boolean.
- Column
Def - A column definition used by
create_tableandadd_column. - Console
Logger - Default logger writing info/warn to stdout and errors to stderr.
- Create
Index Options - Options for
create_index. - Dialect
Capabilities - What an SQL dialect can express. Builders gate on these flags.
- Execute
Step - A side-effecting DDL/DML statement.
- Foreign
KeyReference - The relation referenced by a foreign key.
- Foreign
KeySpec - A named foreign-key constraint specification.
- Migration
- A migration: a node in the dependency DAG carrying ordered operations.
- Operation
- A single, named, self-verifying unit of change.
- Postgres
Dialect - PostgreSQL dialect: full feature set, catalog-backed existence probes, advisory locking.
- Primary
Key - A composite primary key over existing column names.
- Sqlite
Dialect - SQLite dialect: pragma/
sqlite_master-backed probes, no advanced features, no advisory locks.
Enums§
- Migratrom
Error - Everything that can go wrong while planning or applying migrations.
- OpOutcome
- Whether an operation ran or was skipped because it was already applied.
- Referential
Action - Referential action for foreign keys.
Constants§
- DEFAULT_
HISTORY_ TABLE - Default history table name, shared with the Swift and TypeScript siblings.
Traits§
- Db
- The only contract the engine has with a database.
- Migration
Logger - Receives progress messages from the runner.
- Row
- Positional row decode for the fixed-order
SELECTs used by history reads. - SqlDialect
- Database-specific SQL generator used by migration builders and the runner.
Functions§
- advisory_
lock_ key - First eight SHA-256 bytes of the history-table name as a signed, big-endian 64-bit advisory-lock key.
- apply_
migrations - Apply pending migrations in dependency order and record them in history.
- ensure_
history_ table - Create the history table if it does not already exist.
- plan_
order - Validate the migration graph and return the unapplied migrations in order.
- read_
applied_ ids - Read the set of already-applied migration ids.
- read_
applied_ records - Read the full applied records keyed by id (id, checksum, operations).
- record_
migration - Insert a history row recording an applied migration.
- run_
operation - Run a single operation.
- with_
transaction - Run
bodyinside a transaction, committing on success and rolling back on error.
Type Aliases§
- Result
- Convenient result alias used throughout the crate.