DSL `model!` & `extend!`

Le parseur attend les blocs dans cet ordre strict (les blocs optionnels peuvent être absents mais pas réordonnés) :

model! {
    NomModele,              // 1. Nom (PascalCase)
    table: "nom_table",     // 2. Nom de la table SQL
    pk: champ => type,      // 3. Clé primaire
    enums: { ... },         // 4. Optionnel — enums locaux
    fields: { ... },        // 5. Champs (syntaxe v1 ou v2)
    relations: { ... },     // 6. Optionnel — relations SeaORM
    meta: { ... },          // 7. Optionnel — contraintes & tri
}

Deux syntaxes de champs

Syntaxe v1 — types SQL explicites (bloc nommé fields:) :

model! {
    Article,
    table: "articles",
    pk: id => i32,
    fields: {
        titre:      String [required, max_len(150)],
        contenu:    text   [required],
        is_active:  bool,
        created_at: datetime [auto_now],
    },
}

Syntaxe v2 — types sémantiques (bloc anonyme { ... }) :

model! {
    Article,
    table: "articles",
    pk: id => i32,
    {
        titre:      text      [required, max_length: 150],
        contenu:    textarea  [required],
        is_active:  bool      [default: true],
        created_at: datetime  [auto_now],
    }
}

En syntaxe v2, le bloc anonyme remplace à la fois fields: et form_fields: — ces deux blocs nommés n'existent pas en v2. En v1, form_fields: est un bloc optionnel parsé après meta:, permettant d'ajouter des annotations sémantiques sur des champs déjà déclarés en SQL.

pk: nom_champ => type

L'alias Pk résout en i32 par défaut, ou i64 si la feature big-pk est activée :

[dependencies]
runique = { version = "2.1.5", features = ["big-pk"] }

Utilisez big-pk quand vous anticipez plus de ~2 milliards de lignes dans une table, ou pour interopérer avec un schéma existant utilisant des clés primaires BIGINT.

Contraintes lors de l'activation de big-pk :

• Chaque colonne FK pointant vers une clé primaire Pk doit aussi être déclarée bigint, sinon vous obtenez une erreur de type à la compilation :

derive_form! {
    Commande {
        fields: {
            user_id: bigint [required]   // doit correspondre à users.id qui est Pk (i64)
        }
    }
}

• Le daemon admin génère parse::<Pk>() par défaut dans admin.rs, le code généré suit donc automatiquement la feature — aucun ajustement manuel nécessaire.

• Les fichiers de seeds et tout code manuel qui assigne entity.id (un Pk) à un champ FK i32 doivent utiliser .try_into().unwrap() ou changer la colonne FK en bigint.

big-pk doit être décidé avant la première migration. Une fois les migrations appliquées, basculer entre big-pk et le mode par défaut (i32) est un changement cassant : les colonnes en base sont déjà INT ou BIGINT, et changer la feature flag ne modifie que le type Rust — le schéma reste intact. Changer après coup nécessite une migration manuelle pour ALTER chaque colonne PK et FK, avec un risque de troncature des données si des IDs existants dépassent i32::MAX. Choisissez un mode au démarrage du projet et ne le changez pas.

Dans un bloc [...], séparées par des virgules :

username: String [required, max_len(150), unique],

Utilisent : au lieu de () pour les valeurs :

username: text [required, max_length: 150, unique],

auto_now / auto_now_update : ces champs sont exclus de admin_from_form et d'admin_partial_update. Leur valeur est gérée uniquement par la base. Ils apparaissent dans Model et Column comme Option<T>.

Les enums se déclarent dans un bloc enums: { ... } distinct des champs, puis sont référencés via enum(NomEnum).

model! {
    Commande,
    table: "commandes",
    pk: id => i32,
    enums: {
        StatutCommande: [
            EnAttente  = ("en_attente",  "En attente"),
            EnCours    = ("en_cours",    "En cours"),
            Livree     = ("livree",      "Livrée"),
            Annulee    = ("annulee",     "Annulée"),
        ],
        Priorite: i32 [Basse = 0, Normale = 1, Haute = 2, Urgente = 9],
    },
    {
        statut:   choice [enum(StatutCommande), required],
        priorite: choice [enum(Priorite), required],
    },
}

Quatre formes de variant

La valeur DB est stockée exactement telle qu'écrite. Aucune transformation automatique.

Types de backing

Méthodes générées

use sea_orm::Iterable;

let s = StatutCommande::EnAttente;
s.db_value()   // → "en_attente"
s.to_string()  // → "En attente"

// Pour un <select>
let options: Vec<(String, String)> = StatutCommande::iter()
    .map(|v| (v.db_value().to_string(), v.to_string()))
    .collect();

// Parser depuis une valeur DB
let statut: Option<StatutCommande> = "en_attente".parse().ok();

Dans les templates Tera, la valeur de comparaison doit correspondre exactement à ce qui est stocké en base (sensible à la casse).

model! {
    Article,
    table: "articles",
    pk: id => i32,
    {
        image:        image    [upload_to: "media/articles"],
        fichier:      document [upload_to: "docs/"],
        piece_jointe: file     [upload_to: "media/uploads"],
    },
}

upload_to: est obligatoire pour les trois types. Le chemin est relatif à MEDIA_ROOT.

relations: {
    belongs_to: Model via champ_fk,
    has_many: Model,
    has_many: Comments as user_comments,   // alias optionnel
    has_one: Profile as user_profile,
    many_to_many: Roles through UserRoles via self_id,
}

Contrainte FK réelle : la contrainte SQL FOREIGN KEY et son action (cascade, restrict, set_null, set_default) sont déclarées sur l'option fk(table.col, action) du champ, pas dans le bloc relations:. Le bloc relations: génère uniquement les traits SeaORM pour la navigation objet.

Actions FK disponibles sur l'option fk(...) : cascade · restrict · set_null · set_default

meta: {
    ordering: [-created_at, titre],
    unique_together: [(slug, lang)],
    indexes: [(lang, sort_order)],
    verbose_name: "Article",
    verbose_name_plural: "Articles",
}

Par défaut, le libellé est généré depuis le nom snake_case (sort_order → Sort order). L'option label(...) le remplace :

fields: {
    titre:        text [required, label("Titre de l'article")],
    sort_order:   i32  [label("Ordre d'affichage")],
    is_published: bool [label("Publié")],
},

label et help sont des options v1 uniquement — non disponibles dans le bloc anonyme v2.

Le libellé s'applique au formulaire admin et aux en-têtes de colonnes dans list_display. Il n'a aucun effet sur la migration.

Ajoute des colonnes à une table Runique sans la redéfinir. Le CLI makemigrations détecte les blocs extend!{} et génère des instructions ALTER TABLE ADD COLUMN.

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

Tables autorisées : eihwaz_users, eihwaz_groupes, eihwaz_droits, eihwaz_sessions, eihwaz_users_groupes, eihwaz_groupes_droits. Tout autre nom provoque une erreur à la compilation.

Les champs déclarés dans extend!{} utilisent les mêmes types et options que la syntaxe v2 de model!.

Limitation : la macro search ne fonctionne pas encore sur les colonnes ajoutées via extend!{}.