`model!` DSL & `extend!`

The parser expects blocks in this strict order (optional blocks may be absent but not reordered):

model! {
    ModelName,              // 1. Name (PascalCase)
    table: "table_name",   // 2. SQL table name
    pk: field => type,     // 3. Primary key
    enums: { ... },        // 4. Optional — local enums
    fields: { ... },       // 5. Fields (v1 or v2 syntax)
    relations: { ... },    // 6. Optional — SeaORM relations
    meta: { ... },         // 7. Optional — constraints & ordering
}

Two field syntaxes

Syntax v1 — explicit SQL types (named fields: block):

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

Syntax v2 — semantic types (anonymous { ... } block):

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

In syntax v2, the form_fields: block is ignored — semantic types already carry widget information.

pk: field_name => type

The Pk alias resolves to i32 by default, or i64 if the big-pk feature is enabled:

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

Use big-pk when you expect more than ~2 billion rows in a table, or when you need to interoperate with an existing schema that uses BIGINT primary keys.

Constraints when enabling big-pk:

• Every FK column pointing to a Pk primary key must also be declared bigint, otherwise you get a type mismatch at compile time:

derive_form! {
    Order {
        fields: {
            user_id: bigint [required]   // must match users.id which is Pk (i64)
        }
    }
}

• The admin daemon generates parse::<Pk>() by default in admin.rs, so the generated code automatically follows the feature — no manual adjustment needed.

• Seed files and any handwritten code that assigns entity.id (a Pk) to an i32 FK field must use .try_into().unwrap() or change the FK column to bigint.

big-pk must be decided before the first migration. Once migrations have been applied, switching between big-pk and the default (i32) is a breaking change: the database columns are already INT or BIGINT, and changing the feature flag alone only changes the Rust type — the schema stays untouched. Switching after the fact requires a manual migration to ALTER every PK and FK column, and risks data truncation if existing IDs exceed i32::MAX. Pick one mode at project start and keep it.

In a [...] block, comma-separated:

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

Using : instead of () for values:

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

auto_now / auto_now_update: excluded from admin_from_form and admin_partial_update. Their value is managed by the database only. They appear in Model and Column as Option<T>.

Declared in a separate enums: { ... } block, then referenced via enum(EnumName).

model! {
    Order,
    table: "orders",
    pk: id => i32,
    enums: {
        OrderStatus: [
            Pending    = ("pending",    "Pending"),
            InProgress = ("in_progress","In progress"),
            Delivered  = ("delivered",  "Delivered"),
            Cancelled  = ("cancelled",  "Cancelled"),
        ],
        Priority: i32 [Low = 0, Normal = 1, High = 2, Urgent = 9],
    },
    {
        status:   choice [enum(OrderStatus), required],
        priority: choice [enum(Priority), required],
    },
}

Four variant forms

The DB value is stored exactly as written. No automatic transformation.

Backing types

Generated methods

use sea_orm::Iterable;

let s = OrderStatus::Pending;
s.db_value()   // → "pending"
s.to_string()  // → "Pending"

// For a <select>
let options: Vec<(String, String)> = OrderStatus::iter()
    .map(|v| (v.db_value().to_string(), v.to_string()))
    .collect();

// Parse from a DB value
let status: Option<OrderStatus> = "pending".parse().ok();

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

upload_to: is required for all three types. The path is relative to MEDIA_ROOT.

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

Actual FK constraint: the SQL FOREIGN KEY and its action (cascade, restrict, set_null, set_default) are declared on the fk(table.col, action) field option, not in the relations: block. The relations: block only generates SeaORM traits for object navigation.

Available FK actions on fk(...): cascade · restrict · set_null · set_default

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

By default, the label is generated from the snake_case field name (sort_order → Sort order). The label(...) option overrides it:

fields: {
    title:        text [required, label("Article title")],
    sort_order:   i32  [label("Display order")],
    is_published: bool [label("Published")],
},

label and help are v1 only options — not available in the v2 anonymous block.

The label applies to the admin form and column headers in list_display. It has no effect on migrations.

Adds columns to a Runique table and generates a complete SeaORM entity for that table.

extend!{} produces two things:

1. SQL schema — makemigrations detects the block and generates ALTER TABLE ADD COLUMN statements
2. Full entity — Model, Column, Entity, AdminForm, admin_from_form, admin_partial_update covering all columns of the table (base columns + extended columns)

// src/entities/user_profile.rs
use runique::prelude::*;

extend! {
    table: "eihwaz_users",
    fields: {
        bio:         textarea,
        avatar:      image  [upload_to: "avatars/"],
        website:     url,
        phone:       phone,
        birth_date:  date,
        is_verified: bool   [default: false],
    }
}

Allowed tables: eihwaz_users, eihwaz_groupes, eihwaz_droits, eihwaz_sessions, eihwaz_users_groupes, eihwaz_groupes_droits. Any other name causes a compile-time error.

Fields in extend!{} use the same types and options as the v2 syntax of model!. No relations: block inside extend!{} — relations are declared in the target model!{} with has_many(user_profile) etc.

Full workflow

# 1. Declare the extension in src/entities/
# 2. Generate the migration
runique makemigrations

# 3. Apply
runique migrate

# 4. Register in admin!{} (src/admin.rs)

admin! {
    configure {
        users: { hidden: true }   // hides the builtin "Users" panel
    }
    user_profile: user_profile::Model => user_profile::AdminForm {
        title: "User profiles",
        list_display: [
            ["username", "User"],
            ["bio", "Bio"],
            ["is_verified", "Verified"],
        ],
    }
}

What is generated

Queries from views

The generated entity is a standard SeaORM EntityTrait — search! works directly:

// All verified profiles
let profiles = search!(user_profile::Entity => is_verified eq true).fetch(&db).await?;

// Multi-column search
let results = search!(user_profile::Entity => or(username icontains q, bio icontains q)).fetch(&db).await?;

Relations targeting the extended entity

Other entities can point to the extended entity via the usual relations: block in model!{}:

model! {
    Article,
    table: "articles",
    pk: id => i32,
    { author_id: int [required] },
    relations: {
        belongs_to: user_profile::Model via author_id,
    }
}