feat: setup seaorm and a first "debug" entity as example

.env.linux.example

@@ -1,2 +1,3 @@
 SESAM_FSV_VERSION=1.40.13
 SESAM_INI_PATH=/etc/opt/santesocial/fsv/${SESAM_FSV_VERSION}/conf/sesam.ini
+DATABASE_URL=sqlite://p4pillon.sqlite?mode=rwc

.env.win.example

@@ -1,2 +1,3 @@
 SESAM_FSV_VERSION=1.40.13
 SESAM_INI_PATH=${ALLUSERSPROFILE}\\santesocial\\fsv\\${SESAM_FSV_VERSION}\\conf\\sesam.ini
+DATABASE_URL=sqlite://p4pillon.sqlite?mode=rwc

.gitignore

@@ -23,3 +23,6 @@ target/
 
 # Ignore .env files
 .env
+
+# Development Database
+*.sqlite

Cargo.toml

@@ -5,4 +5,6 @@ members = [
     "crates/desktop",
     "crates/sesam-vitale",
     "crates/utils",
+    "migration",
+    "entity",
 ]

README.md

@@ -43,6 +43,24 @@ La CLI Tauri est nécessaire au lancement du client `desktop`. Elle peut être i
 cargo install tauri-cli --version "^2.0.0-rc"
 ```
 
+#### SeaORM CLI
+
+SeaORM est notre ORM. Le CLI SeaORM est nécessaire pour la génération des modèles de la base de données et des migrations associées. Elle peut être installée via Cargo :
+
+```bash
+cargo install sea-orm-cli
+```
+
+L'applicatif va chercher les informations de connexion à la base de données dans la variable `DATABASE_URL` importée depuis les [fichiers de configuration](#fichiers-de-configuration).
+
+```.env
+DATABASE_URL=sqlite://p4pillon.sqlite?mode=rwc
+```
+
+Toutefois, l'usage de la CLI de SeaORM nécessite de renseigner les informations de connexion à la base de données dans un fichier `.env` situé à la racine du projet.
+
+> Astuce : utilisé un lien symbolique pour éviter de dupliquer le fichier `.env`.
+
 #### SESAM-Vitale
 
 La crate `sesam-vitale` nécessite la présence des librairies dynamiques fournies par le package FSV et la CryptolibCPS. Les instructions d'installation sont disponibles dans le [README](crates/sesam-vitale/README.md) de la crate `sesam-vitale`.
@@ -75,3 +93,25 @@ Pour packager le client `desktop`, il est nécessaire de faire appel à la CLI T
 ```bash
 cargo tauri build
 ```
+
+## Gestion de la base de données
+
+### Création d'une migration
+
+```bash
+sea-orm-cli migrate generate <nom_de_la_migration> 
+```
+
+Cette commande génère un fichier de migration à adapter dans le dossier `migration/src`.
+
+### Appliquer les migrations
+
+```bash
+sea-orm-cli migrate up
+```
+
+### Génération des entitées
+
+```bash
+sea-orm-cli generate entity -o entity/src/entities
+```

crates/app/Cargo.toml

@@ -8,14 +8,23 @@ askama = "0.12.1"
 askama_axum = "0.4.0"
 axum = "0.7.5"
 axum-htmx = { version = "0.6", features = ["auto-vary"] }
+futures = "0.3.30"
 listenfd = "1.0.1"
 notify = "6.1.1"
+sea-orm = { version = "1.0.1", features = [
+    # Same as in the migration crate
+    "sqlx-sqlite",
+    "runtime-tokio-rustls",
+    "macros",
+] }
 serde = { version = "1.0.204", features = ["derive"] }
 thiserror = "1.0.63"
 tokio = { version = "1.39.1", features = ["macros", "rt-multi-thread"] }
 tower-http = { version = "0.5.2", features = ["fs"] }
 tower-livereload = "0.9.3"
 
+entity = { path = "../../entity" }
+migration = { path = "../../migration" }
 utils = { path = "../utils" }
 
 [dev-dependencies]

crates/app/README.md

@@ -2,6 +2,15 @@
 
 - Récupérer le binaire TailwindCSS : https://tailwindcss.com/blog/standalone-cli
 
+## Configuration
+
+> Astuce : lorsqu'on exécute directement la crate `App` à des fins de développement, le système de configuration n'utilisera pas l'éventuel fichier `.env` situé à la racine du workspace Rust. Pour éviter de dupliquer le fichier `.env`, il est possible de créer un lien symbolique vers le fichier `.env` de la crate `App` :
+
+```bash
+cd crates/app
+ln -s ../../.env .env
+```
+
 ## Exécution
 
 - Lancer tailwindcss en mode watch dans un terminal : 

crates/app/src/db.rs

@@ -0,0 +1,11 @@
+use migration::{Migrator, MigratorTrait};
+use sea_orm::{Database, DatabaseConnection, DbErr};
+use std::env;
+
+pub async fn get_connection() -> Result<DatabaseConnection, DbErr> {
+    let database_url = env::var("DATABASE_URL").expect("DATABASE_URL must be set");
+
+    let db_connection = Database::connect(database_url).await?;
+    Migrator::up(&db_connection, None).await?;
+    Ok(db_connection)
+}

crates/app/src/lib.rs

@@ -2,6 +2,7 @@ use std::path::PathBuf;
 
 use axum::http::{StatusCode, Uri};
 use axum_htmx::AutoVaryLayer;
+use sea_orm::DatabaseConnection;
 use thiserror::Error;
 use tower_http::services::ServeDir;
 
@@ -27,12 +28,20 @@ pub fn init() -> Result<(), InitError> {
     Ok(())
 }
 
+#[derive(Clone)]
+pub struct AppState {
+    db_connection: DatabaseConnection,
+}
 
 pub async fn get_router(assets_path: PathBuf) -> axum::Router<()> {
+    let db_connection = db::get_connection().await.unwrap();
+    let state: AppState = AppState { db_connection };
+
     axum::Router::new()
         .nest_service("/assets", ServeDir::new(assets_path))
         .merge(pages::get_routes())
         .fallback(fallback)
+        .with_state(state)
         // The AutoVaryLayer is used to avoid cache issues with htmx (cf: https://github.com/robertwayne/axum-htmx?tab=readme-ov-file#auto-caching-management)
         .layer(AutoVaryLayer)
 }

crates/app/src/main.rs

@@ -20,6 +20,8 @@ pub enum AppError {
     NotifyWatcher(#[from] notify::Error),
     #[error("Missing environment variable {var}")]
     MissingEnvVar { var: &'static str },
+    #[error("Error with the database connection")]
+    DatabaseConnection(#[from] sea_orm::DbErr),
     #[error("Error while initialising the app")]
     Initialisation(#[from] InitError),
 }

entity/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "entity"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+name = "entity"
+path = "src/lib.rs"
+
+[dependencies]
+sea-orm = { version = "1.0.1" }

entity/src/entities/debug.rs

@@ -0,0 +1,17 @@
+//! `SeaORM` Entity, @generated by sea-orm-codegen 1.0.1
+
+use sea_orm::entity::prelude::*;
+
+#[derive(Clone, Debug, PartialEq, DeriveEntityModel, Eq)]
+#[sea_orm(table_name = "debug")]
+pub struct Model {
+    #[sea_orm(primary_key)]
+    pub id: i32,
+    pub title: String,
+    pub text: String,
+}
+
+#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
+pub enum Relation {}
+
+impl ActiveModelBehavior for ActiveModel {}

entity/src/entities/mod.rs

@@ -0,0 +1,5 @@
+//! `SeaORM` Entity, @generated by sea-orm-codegen 1.0.1
+
+pub mod prelude;
+
+pub mod debug;

entity/src/entities/prelude.rs

@@ -0,0 +1,3 @@
+//! `SeaORM` Entity, @generated by sea-orm-codegen 1.0.1
+
+pub use super::debug::Entity as Debug;

entity/src/lib.rs

@@ -0,0 +1,2 @@
+mod entities;
+pub use entities::*;

migration/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "migration"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+name = "migration"
+path = "src/lib.rs"
+
+[dependencies]
+async-std = { version = "1", features = ["attributes", "tokio1"] }
+
+[dependencies.sea-orm-migration]
+version = "1.0.0"
+features = [
+  # `ASYNC_RUNTIME` and `DATABASE_DRIVER` are required to run migration using the cli
+  # They must be the same as the features in the `sea-orm` dependency in the `app` crate
+  "sqlx-sqlite",          # `DATABASE_DRIVER` feature
+  "runtime-tokio-rustls", # `ASYNC_RUNTIME` feature
+]

migration/README.md

@@ -0,0 +1,41 @@
+# Running Migrator CLI
+
+- Generate a new migration file
+    ```sh
+    cargo run -- generate MIGRATION_NAME
+    ```
+- Apply all pending migrations
+    ```sh
+    cargo run
+    ```
+    ```sh
+    cargo run -- up
+    ```
+- Apply first 10 pending migrations
+    ```sh
+    cargo run -- up -n 10
+    ```
+- Rollback last applied migrations
+    ```sh
+    cargo run -- down
+    ```
+- Rollback last 10 applied migrations
+    ```sh
+    cargo run -- down -n 10
+    ```
+- Drop all tables from the database, then reapply all migrations
+    ```sh
+    cargo run -- fresh
+    ```
+- Rollback all applied migrations, then reapply all migrations
+    ```sh
+    cargo run -- refresh
+    ```
+- Rollback all applied migrations
+    ```sh
+    cargo run -- reset
+    ```
+- Check the status of all migrations
+    ```sh
+    cargo run -- status
+    ```

migration/src/lib.rs

@@ -0,0 +1,12 @@
+pub use sea_orm_migration::prelude::*;
+
+mod m20220101_000001_create_debug_table;
+
+pub struct Migrator;
+
+#[async_trait::async_trait]
+impl MigratorTrait for Migrator {
+    fn migrations() -> Vec<Box<dyn MigrationTrait>> {
+        vec![Box::new(m20220101_000001_create_debug_table::Migration)]
+    }
+}

migration/src/m20220101_000001_create_debug_table.rs

@@ -0,0 +1,35 @@
+use sea_orm_migration::{prelude::*, schema::*};
+
+#[derive(DeriveMigrationName)]
+pub struct Migration;
+
+#[async_trait::async_trait]
+impl MigrationTrait for Migration {
+    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        manager
+            .create_table(
+                Table::create()
+                    .table(Debug::Table)
+                    .if_not_exists()
+                    .col(pk_auto(Debug::Id))
+                    .col(string(Debug::Title))
+                    .col(string(Debug::Text))
+                    .to_owned(),
+            )
+            .await
+    }
+
+    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        manager
+            .drop_table(Table::drop().table(Debug::Table).to_owned())
+            .await
+    }
+}
+
+#[derive(DeriveIden)]
+enum Debug {
+    Table,
+    Id,
+    Title,
+    Text,
+}

migration/src/main.rs

@@ -0,0 +1,6 @@
+use sea_orm_migration::prelude::*;
+
+#[async_std::main]
+async fn main() {
+    cli::run_cli(migration::Migrator).await;
+}