Database Migrations (sea-orm-migration)
Relevant source files
The following files were used as context for generating this wiki page:
SeaORM provides a robust migration system designed to manage database schema evolution. It allows developers to define version-controlled transformations for creating tables, modifying schemas, and seeding data. The system supports both asynchronous execution for high-performance web services and synchronous execution via sea-orm-sync for lightweight CLI applications.
The migration framework is centered around the MigratorTrait, which defines the sequence of migrations and provides high-level commands for applying or rolling back changes. Developers can interact with migrations via the sea-orm-cli or by integrating the migration runner directly into their Rust applications.
Sources: src/lib.rs:188-190, sea-orm-migration/src/migrator.rs:52-54
Core Components and Architecture
The migration system consists of three primary layers: the migration definitions, the migrator runner, and the CLI interface.
MigratorTrait
The MigratorTrait is the central interface for executing migrations. It manages a vector of migration files and tracks their status in a specialized database table, typically named seaql_migrations.
The diagram above illustrates the relationship between the MigratorTrait and the tracking of migration states.
Sources: sea-orm-migration/src/migrator.rs:52-167
Migration Tracking
SeaORM tracks applied migrations using a dedicated table. This prevents the same migration from being run multiple times and allows the system to determine which migrations are "Pending" versus "Applied".
| Field | Description |
|---|---|
| Name | The unique identifier for the migration (e.g., m20220101_000001_create_table). |
| Status | Indicates if the migration is Pending or Applied. |
Sources: sea-orm-migration/src/migrator.rs:15-32, sea-orm-migration/src/migrator.rs:65-72
CLI Command Workflow
The sea-orm-cli provides commands to initialize, generate, and run migrations. It acts as a wrapper that calls cargo run on the migration project.
This flowchart shows how the CLI facilitates migration management from project initialization to database execution.
Sources: sea-orm-cli/src/commands/migrate.rs:21-70
Key CLI Operations
- Init: Sets up the directory structure, including
Cargo.toml,src/lib.rs, and a template migration. - Generate: Creates a new migration file with a name format of
mYYYYMMDD_HHMMSS_name.rsand automatically registers it in the migrator. - Up/Down: Applies or reverts a specified number of migration steps.
Sources: sea-orm-cli/src/commands/migrate.rs:80-100, sea-orm-cli/src/commands/migrate.rs:114-142
Execution Logic and Transaction Support
Migrations are executed in a sequential "time sequence". The MigratorTrait handles different execution modes to ensure database consistency.
Migration Execution Modes
The system supports several high-level operations for managing the database state:
| Operation | Logic |
|---|---|
| Up | Applies all pending migrations in order. |
| Down | Rolls back a specified number of applied migrations in reverse order. |
| Fresh | Drops all existing tables in the database and then reapplies all migrations from scratch. |
| Refresh | Rolls back all migrations (Down) and then reapplies them all (Up). |
| Reset | Rolls back all migrations and uninstalls the migration tracking table. |
Sources: sea-orm-migration/src/migrator.rs:125-167, examples/seaography_example/migration/README.md:21-42
Transactions
By default, SeaORM uses transactions to ensure atomicity during migration execution. On PostgreSQL, DDL changes are wrapped in transactions by default. On backends like MySQL, which do not support DDL transactions (auto-committing DDL), the system still manages the migration tracking table to reflect the last successful operation.
Test cases verify that:
- Failing migrations in a transaction roll back DDL (where supported).
- Manual transactions can be initiated via
SchemaManager. - SQLite specific modes (
IMMEDIATE,EXCLUSIVE) can be specified for transactions.
Sources: sea-orm-migration/tests/main.rs:248-310, changelog/2.0.0-rc.35.md:7-15
Entity-First Workflow (SeaORM 2.0)
In SeaORM 2.0, a new "Entity-First" workflow is introduced alongside traditional migrations. This allows the system to automatically detect changes in Entity definitions and synchronize the database schema without manual migration scripts.
// Requires the `entity-registry` and `schema-sync` feature flags.
db.get_schema_registry("my_crate::entity::*").sync(db).await;
This feature resolves foreign key dependencies and creates tables in topological order based on the Entity definitions.
Sources: src/lib.rs:194-198, CLAUDE.md:126-130
Conclusion
The sea-orm-migration module provides a comprehensive suite for database version control. By combining the MigratorTrait for structured transformations with the sea-orm-cli for developer productivity, it ensures that database schemas can evolve safely alongside application code. The addition of the Entity-First workflow in version 2.0 further enhances this by providing automated schema synchronization for rapid development environments.