Migrations

Migrations live in a Rust crate of their own, migration/, part of the project's workspace:

migration/
├── Cargo.toml        runique + sea-orm-migration, same engine as the app
└── src/
    ├── main.rs       runs SeaORM's CLI (up, down, status)
    ├── lib.rs        the list of migrations, kept up to date by makemigrations
    ├── m<date>_*.rs  the generated migrations
    └── snapshots/    the schema already migrated, model by model

You don't create it: runique new writes it with the project, and runique makemigrations creates it when it's missing (a project not created by runique new), with the engine of DB_ENGINE. There is nothing to write by hand in lib.rs.

The expected Cargo.toml

Runique writes it once, at creation; after that it's yours and Runique never touches it again. Here is the file as generated (Postgres example):

[package]
name = "migration"
version = "0.1.0"
edition = "2024"
publish = false

[lib]
name = "migration"
path = "src/lib.rs"

[dependencies]
runique = { version = "4.0.0", features = ["postgres"] }
sea-orm-migration = { version = "=2.0.4", features = [
    "runtime-tokio-rustls",
    "sqlx-postgres",
] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
async-trait = "0.1"

What is required:

• runique with the same engine feature as the app (sqlite, postgres, mysql or mariadb): it provides the framework's tables.
• sea-orm-migration at the exact same version as Runique's, with runtime-tokio-rustls and the engine's driver: sqlx-sqlite, sqlx-postgres, or sqlx-mysql (MySQL and MariaDB alike).
• sea-orm-migration's default features: they bring cli::run_cli, called by src/main.rs. With default-features = false, add "cli" to the list, or the crate no longer compiles.
• tokio with macros and rt-multi-thread (#[tokio::main] in main.rs), and async-trait (the generated migrations).
• [lib] name = "migration": main.rs calls migration::Migrator.

1. Write the migration files

runique makemigrations

makemigrations reads your models in src/entities/, compares them to the snapshots, and writes what changed:

The command ends with the number of files written, or "No changes detected" when nothing changed, then gives the next command.

2. Apply the migrations

runique migration up

Roll back or check

runique migration down -n 1    # rolls back the last migration (its down() runs)
runique migration status       # lists the migrations and their state

These commands run the migration crate (cargo run), which reads DATABASE_URL from .env: run them from the project root. sea-orm-cli isn't needed, and the SeaORM version used is the one migration/Cargo.toml pins, the same as runique's.

runique makemigrations is the only tool to use to write migrations. Don't use sea-orm-cli migrate generate: Runique keeps its own snapshots and the order of lib.rs.

Before writing anything, makemigrations spots destructive changes and refuses to write the migration, unless --force is given:

• DROP COLUMN (data loss)
• a column's type changing (see the limits below)
• nullable → required (needs a default value or a prior backfill)
• a shorter length (smaller max_length): longer values would be truncated or refused
• a dropped foreign key (orphaned rows possible)
• an ON DELETE CASCADE FK added over existing data

runique makemigrations --force

The check covers the app's tables (model!{}) as well as the extensions of the framework's tables (extend!{}).

use runique::prelude::*;

extend! {
    table: "eihwaz_users",
    fields: {
        avatar: image [nullable, upload_to: "avatars/"],
        bio: textarea [nullable],
        website: url [nullable],
    }
}

makemigrations writes the matching ALTER TABLE ADD COLUMN. The extension's snapshot is stored in migration/src/snapshots/runique/<table>.rs.

Extensible tables: eihwaz_users and eihwaz_groupes, and only those. Extending any other table is a compile error.