Migrations

Les migrations vivent dans un crate Rust à part, migration/, qui fait partie du workspace du projet :

migration/
├── Cargo.toml        runique + sea-orm-migration, même moteur que l'application
└── src/
    ├── main.rs       lance la CLI de SeaORM (up, down, status)
    ├── lib.rs        la liste des migrations, tenue à jour par makemigrations
    ├── m<date>_*.rs  les migrations générées
    └── snapshots/    l'état du schéma déjà migré, modèle par modèle

Vous n'avez pas à le créer : runique new l'écrit avec le projet, et runique makemigrations le crée s'il manque (projet non créé par runique new), avec le moteur de DB_ENGINE. Il n'y a rien à écrire à la main dans lib.rs.

Le Cargo.toml attendu

Runique l'écrit une seule fois, à la création ; ensuite il est à vous et Runique n'y touche plus. Voici le fichier tel qu'il est généré (exemple Postgres) :

[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"

Ce qui est obligatoire :

• runique avec la même feature de moteur que l'application (sqlite, postgres, mysql ou mariadb) : il fournit les tables du framework.
• sea-orm-migration à la même version exacte que celle de Runique, avec runtime-tokio-rustls et le pilote du moteur : sqlx-sqlite, sqlx-postgres, ou sqlx-mysql (MySQL comme MariaDB).
• Les features par défaut de sea-orm-migration : elles apportent cli::run_cli, appelé par src/main.rs. Avec default-features = false, ajoutez "cli" à la liste, sinon le crate ne compile plus.
• tokio avec macros et rt-multi-thread (#[tokio::main] de main.rs), et async-trait (les migrations générées).
• [lib] name = "migration" : main.rs appelle migration::Migrator.

1. Générer les fichiers de migration

runique makemigrations

makemigrations lit vos modèles dans src/entities/, les compare aux snapshots, et écrit ce qui a changé :

La commande se termine par le nombre de fichiers écrits, ou « No changes detected » si rien n'a changé, puis rappelle la commande suivante.

2. Appliquer les migrations

runique migration up

Annuler ou consulter

runique migration down -n 1    # annule la dernière migration (son down() s'exécute)
runique migration status       # liste les migrations et leur état

Ces commandes lancent le crate migration (cargo run), qui lit DATABASE_URL dans .env : lancez-les depuis la racine du projet. sea-orm-cli n'est pas nécessaire, et la version de SeaORM utilisée est celle de migration/Cargo.toml, alignée sur Runique.

runique makemigrations est le seul outil à utiliser pour générer les migrations. N'utilisez pas sea-orm-cli migrate generate : Runique tient ses propres snapshots et l'ordre de lib.rs.

Avant d'écrire quoi que ce soit, makemigrations détecte les changements destructifs et refuse de générer la migration, sauf avec --force :

• DROP COLUMN (perte de données)
• changement de type d'une colonne (voir les limites plus bas)
• passage nullable → obligatoire (nécessite une valeur par défaut ou un remplissage préalable)
• réduction de longueur (max_length plus petit) : des valeurs plus longues seraient tronquées ou refusées
• suppression d'une clé étrangère (risque d'enregistrements orphelins)
• ajout d'une FK ON DELETE CASCADE sur des données existantes

runique makemigrations --force

Le contrôle couvre les tables de l'application (model!{}) comme les extensions des tables du framework (extend!{}).

use runique::prelude::*;

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

makemigrations génère les ALTER TABLE ADD COLUMN correspondants. Le snapshot de l'extension est stocké dans migration/src/snapshots/runique/<table>.rs.

Tables extensibles : eihwaz_users et eihwaz_groupes, et elles seules. Étendre une autre table est une erreur de compilation.