Skip to main content

Crate migratio

Crate migratio 

Source
Expand description

migratio is a library for managing database migrations.

Core concepts:

  • Live DB Connections: migratio supplies migration definitions with a live connection to the database, allowing more expressive migration logic than just preparing SQL statements.
  • Code-First: migratio is a code-first library, making embedding it in your application easier than other CLI-first libraries.

§Motivation

§Using a Live Database Connection

Most Rust-based migration solutions focus only on using SQL to define migration logic. Even the ones that say they support writing migrations in Rust use Rust to simply construct SQL instructions, like Refinery.

Taking a hint from Alembic, this library provides the user with a live connection to the database with which to define their migrations. With a live connection, a migration can query the data, transform it in Rust, and write it back. Migrations defined as pure SQL statements can only accomplish this with the toolkit provided by SQL, which is much more limited.

Note: SeaORM allows this, but migratio aims to provide an alternative for developers that don’t want to adopt a full ORM solution.

§Code-first approach

A central use case for migratio is embedding migration logic within an application, usually in the startup procedure. This way, when the application updates, the next time it starts the database will automatically be migrated to the latest version without any manual intervention.

§Benefits

  • Easy adoption from other migration tools or no migration tool.
  • Robust error handling and rollback support (when available).
  • Preview / dry-run support.
  • Migration history querying.
  • Observability hooks.
  • Tracing integration = available with the tracing feature flag.
  • Testing utilities - available with the testing feature flag.

§Database support

  • SQLite - available with the sqlite feature flag.
  • MySQL - available with the mysql feature flag.
  • PostgreSQL - available with the postgres feature flag.

Modules§

mysqlmysql
MySQL migration support
postgrespostgres
PostgreSQL migration support
sqlitesqlite
SQLite migration support
testingtesting
Testing utilities for migration development

Macros§

sql_migration
Define a simple SQL-only migration.

Structs§

AppliedMigration
Represents a migration that has been applied to the database.
MigrationFailure
Represents a failure during a migration.
MigrationReport
A report of actions performed during a migration.

Enums§

Error
Error type for the migratio crate.
MigrationType
Represents the type of a migration entry.
Precondition
Represents the result of a migration precondition check.

Traits§

Migration
A trait that must be implemented to define a migration. The version value must be unique among all migrations supplied to a migrator, and greater than 0. The name and description methods are optional, and only aid in debugging / observability.