@mlagie/sql-connector 3.0.3 → 3.1.0

package/docs/fr/README_FR.md

@@ -1,483 +1,727 @@
-# Documentation du module sql-connector
+# @mlagie/sql-connector — Documentation française
 
-![GitHub package.json version](https://img.shields.io/github/package-json/v/lagie-marin/sql-connector?color=#008000) ![NPM Downloads](https://img.shields.io/npm/d18m/%40mlagie%2Fsql-connector?color=#008000) ![NPM Downloads](https://img.shields.io/npm/dw/%40mlagie%2Fsql-connector?color=#008000) ![GitHub followers](https://img.shields.io/github/followers/lagie-marin?style=plastic&color=color%3D%23008000) ![GitHub repo size](https://img.shields.io/github/repo-size/lagie-marin/sql-connector?color=%green)
- ![GitHub last commit](https://img.shields.io/github/last-commit/lagie-marin/sql-connector)
+[![npm version](https://img.shields.io/npm/v/%40mlagie%2Fsql-connector)](https://www.npmjs.com/package/@mlagie/sql-connector)
 
-[English](../../README.md) | Français
+Couche SQL légère et orientée dialecte pour **MySQL** et **PostgreSQL**.
 
-Le module sql-connector permet de gérer des connexions MySQL et PostgreSQL, de définir des schémas, de synchroniser automatiquement des tables et d'exposer des modèles pour manipuler les données simplement.
+`@mlagie/sql-connector` fournit :
 
-## Importation
+- gestion des connexions ;
+- schémas déclaratifs ;
+- types SQL et alias de types ;
+- modèles CRUD ;
+- conditions structurées `WHERE` / `HAVING` ;
+- `IN`, `BETWEEN`, `LIKE`, `ILIKE`, `NULL`, `AND`, `OR`, `NOT` ;
+- agrégations, groupements, tris et jointures ;
+- gestion des dépendances de clés étrangères ;
+- synchronisation des schémas ;
+- planification et exécution des migrations ;
+- checksum, fichiers de migration chiffrés et sauvegardes chiffrées optionnelles ;
+- déclarations TypeScript.
 
-```javascript
-const { Schema, connect, logout, Model, ModelInstance, client, sqlTypeMap } = require('sql-connector');
-```
-
-## Connexion à la base
-
-`connect(config, dialect)` ouvre une connexion à une base de données. MySQL est utilisé par défaut ; utilisez `"postgres"` pour PostgreSQL.
-
-```javascript
-const config = {
-  host: 'localhost',
-  port: 3306,
-  user: 'root',
-  password: 'password',
-  database: 'mydatabase'
-};
-
-await connect(config);
-```
-
-### PostgreSQL
+> **SGBD supportés :** MySQL et PostgreSQL.
 
-PostgreSQL utilise le driver `pg` :
+**Documentation :** [English](../../README.md) · Français
 
-```javascript
-const postgresConfig = {
-  host: 'localhost',
-  port: 5432,
-  user: 'postgres',
-  password: 'password',
-  database: 'mydatabase'
-};
-
-await connect(postgresConfig, 'postgres');
-```
+---
 
-Les dialectes supportés sont `mysql` et `postgres`.
+## Sommaire
+
+1. [Installation](#installation)
+2. [Démarrage rapide](#démarrage-rapide)
+3. [Connexion](#connexion)
+4. [Schémas](#schémas)
+   - [Propriétés d'un champ](#propriétés-dun-champ)
+   - [Types](#types)
+   - [Valeurs par défaut](#valeurs-par-défaut)
+   - [Contraintes](#contraintes)
+   - [Clés étrangères](#clés-étrangères)
+5. [Modèles](#modèles)
+6. [Conditions](#conditions)
+7. [Select, agrégations, groupement et tri](#select-agrégations-groupement-et-tri)
+8. [Jointures](#jointures)
+9. [Synchronisation](#synchronisation)
+10. [Instances de modèle](#instances-de-modèle)
+11. [Migrations](#migrations)
+    - [Migration workflow](#migration-workflow)
+    - [Migration options](#migration-options)
+    - [Migration opérations](#migration-opérations)
+    - [Migration renommage](#migration-renommage)
+    - [Changement destructifs](#changements-destructifs)
+    - [Checksum et historique](#checksum-et-historique)
+    - [Chriffrement](#chiffrement)
+    - [Sauvegardes](#sauvegardes)
+    - [Statut et nettoyage](#statut-et-nettoyage)
+12. [TypeScript](#typescript)
+13. [Sécurité SQL](#sécurité-sql)
+14. [API exportée](#api-exportée)
+15. [Tests](#tests)
+16. [Documentation détaillée](#documentation-détaillée)
+17. [Licence](#licence)
 
-| Dialecte | Guillemets des identifiants | Placeholders | Valeurs booléennes par défaut |
-|----------|-----------------------------|--------------|-------------------------------|
-| MySQL | Accolades inverses | `?` | `1` / `0` |
-| PostgreSQL | Guillemets doubles | `$1`, `$2`, ... | `TRUE` / `FALSE` |
+---
 
-`logout()` ferme proprement la connexion.
+## Installation
 
-```javascript
-await logout();
+```bash
+npm install @mlagie/sql-connector
 ```
 
-## Schéma
-
-`Schema` décrit la structure d'une table. Chaque champ peut utiliser les propriétés suivantes.
+---
 
-| Propriété      | Type                             | Description                 |
-|----------------|----------------------------------|-----------------------------|
-| type           | `SqlType` ou `{ name: SqlType }` | Type SQL du champ           |
-| length         | `number`                         | Longueur maximale           |
-| required       | `boolean`                        | Champ obligatoire           |
-| default        | `any`                            | Valeur par défaut           |
-| unique         | `boolean`                        | Valeur unique               |
-| auto_increment | `boolean`                        | Auto-incrément              |
-| foreignKey     | `string`                         | Référence de clé étrangère  |
-| enum           | `string[]`                       | Liste de valeurs autorisées |
-| primary_key    | `boolean`                        | Clé primaire                |
-| customize      | `string`                         | Options SQL additionnelles  |
+## Démarrage rapide
 
-```javascript
-const { Schema, Model, sqlTypeMap } = require("@mlagie/sql-connector");
+```js
+const {
+  Schema,
+  Model,
+  connect,
+  logout,
+} = require('@mlagie/sql-connector');
+
+await connect({
+  host: 'localhost',
+  port: 3306,
+  user: 'root',
+  password: 'password',
+  database: 'mydatabase',
+});
 
 const userSchema = new Schema({
   id: {
     type: Number,
     auto_increment: true,
-    primary_key: true
+    primary_key: true,
   },
   email: {
     type: String,
     length: 255,
+    required: true,
     unique: true,
-    required: true
   },
   status: {
     type: String,
     enum: ['active', 'inactive', 'pending'],
-    default: 'pending'
+    default: 'pending',
   },
-    uuid: {
-        type: String,
-        required: true,
-        primary_key: true,
-        length: 36
-    },
-    my_uuid: {
-        type: String,
-        required: true,
-        length: 36
-    },
-    created_at: {
-        type: Date,
-        default: sqlTypeMap.CurrentTimestamp
-    }
 });
 
-module.exports = new Model("User", userSchema);
-```
+const User = new Model('users', userSchema);
 
-Exemple avec plusieurs clés étrangères :
+await Model.syncAllTables();
+await User.save({ email: 'user@example.com', status: 'active' });
 
-```javascript
-const orderSchema = new Schema({
-  user_id: { type: Number, foreignKey: 'users(id)' },
-  product_id: { type: Number, foreignKey: 'products.id' }
+const users = await User.find({
+  where: {
+    status: { IN: ['active', 'pending'] },
+  },
 });
+
+await logout();
 ```
 
-## Synchronisation des tables
+---
 
-`Model.syncAllTables()` compare les schémas JS avec la base et applique uniquement les différences utiles. Les dépendances de clés étrangères sont créées dans le bon ordre et les cycles sont rejetés.
+## Connexion
 
-- Ajout de colonne: automatique.
-- Les clés étrangères utilisent le format `table(colonne)` et peuvent être déclarées sur plusieurs champs.
+### MySQL
 
-```javascript
-await Model.syncAllTables();
+MySQL est le dialecte par défaut.
+
+```js
+await connect({
+  host: 'localhost',
+  port: 3306,
+  user: 'root',
+  password: 'password',
+  database: 'mydatabase',
+});
 ```
 
-Point important: ne combinez pas `primary_key: true` et `unique: true` sur le même champ. Une clé primaire est déjà unique et non nulle.
+### PostgreSQL
 
-## Modèles
+```js
+await connect({
+  host: 'localhost',
+  port: 5432,
+  user: 'postgres',
+  password: 'password',
+  database: 'mydatabase',
+}, 'postgres');
+```
+
+### Fermer la connexion
+
+```js
+await logout();
+```
 
-`Model` représente une table SQL.
+---
 
-Méthodes principales:
+## Schémas
 
-- `save(data)` pour insérer une ligne
-- `find(filter, fields)` pour récupérer plusieurs entrées
-- `count(filter)` pour compter les lignes
-- `customRequest(custom)` pour exécuter une requête SQL personnalisée
-- `delete(filter)` pour supprimer une entrée
-- `dropTable()` pour supprimer la table
-- `generate_uuid()` pour générer un UUID unique
+```js
+const schema = new Schema({
+  name: { type: String, length: 120, required: true },
+  age: { type: Number },
+  active: { type: Boolean, default: true },
+});
+```
 
-```javascript
-const userModel = new Model('users', userSchema);
+### Propriétés d'un champ
+
+| Propriété | Type | Description |
+|---|---|---|
+| `type` | constructeur / chaîne / `{ name }` | Type du champ. |
+| `length` | `number` | Longueur du type. |
+| `precision` | `number` | Précision décimale. |
+| `scale` | `number` | Échelle décimale. |
+| `required` | `boolean` | Ajoute `NOT NULL`. |
+| `default` | quelconque | Valeur SQL par défaut. |
+| `unique` | `boolean` | Ajoute `UNIQUE`. |
+| `primary_key` | `boolean` | Ajoute `PRIMARY KEY`. |
+| `auto_increment` | `boolean` | Auto-incrément / identity selon le dialecte. |
+| `enum` | `string[]` | Valeurs autorisées. |
+| `foreignKey` | `string` | Référence comme `users(id)` ou `users.id`. |
+| `oldname` | `string` | Ancien nom utilisé explicitement par les migrations. |
+| `customize` | `string` | SQL additionnel de définition. |
+
+### Types
+
+| Alias | SQL |
+|---|---|
+| `String` | `VARCHAR` |
+| `Char` | `CHAR` |
+| `Number` | `INT` |
+| `SmallInt` | `SMALLINT` |
+| `BigInt` | `BIGINT` |
+| `Decimal` | `DECIMAL` |
+| `Boolean` | `BOOLEAN` |
+| `Date` | `DATETIME` |
+| `DateTime` | `DATETIME` |
+| `Timestamp` | `TIMESTAMP` |
+| `Float` | `FLOAT` |
+| `Double` | `DOUBLE` |
+| `Text` | `TEXT` |
+| `Blob` | `BLOB` |
+| `Binary` | `VARBINARY` |
+| `Uuid` | `CHAR` |
+| `Object` | `JSON` |
+| `Array` | `VARCHAR` |
+| `Now` | `NOW()` |
+| `CurrentTimestamp` | `CURRENT_TIMESTAMP` |
+
+Les constructeurs JavaScript `String`, `Number`, `Boolean`, `Date`, `Object` et `Array` sont également acceptés. `Now` et `CurrentTimestamp` représentent des expressions/constantes SQL temporelles et sont surtout destinés aux valeurs par défaut, pas à des types de stockage portables.
+
+### Valeurs par défaut
 
-await Model.syncAllTables();
-await userModel.save({ email: 'user@example.com', status: 'active' });
+```js
+const schema = new Schema({
+  active: { type: Boolean, default: true },
+  retries: { type: Number, default: 0 },
+  note: { type: String, default: 'pending' },
+  created_at: { type: Date, default: 'CURRENT_TIMESTAMP' },
+  metadata: { type: Object, default: { source: 'api' } },
+});
+```
 
-const user = await userModel.find({ where: { email: 'user@example.com' }});
-await user[0].delete();
+Les valeurs par défaut peuvent être `null`, chaînes, nombres, booléens, `Date`, objets, expressions temporelles SQL ou fonctions retournant une valeur supportée.
+
+```js
+created_at: {
+  type: Date,
+  default: sqlTypeMap.CurrentTimestamp,
+}
 ```
 
-## Fonction save
+### Contraintes
 
-Enregistre les données dans la table de la base de données.
+Le module prend en charge `NOT NULL`, `UNIQUE`, `PRIMARY KEY`, `FOREIGN KEY`, `DEFAULT`, `ENUM`, l'auto-incrément et `customize`.
 
-- **Parameters** `data` *(Object)* - Les données à insérer dans la table.
-- **Returns** `Promise<Object>` - Une promesse avec le résultat de l'insertion.
-- **Throws** `Error` - Lève une erreur si l'insertion échoue.
+Ne combinez pas `primary_key: true` et `unique: true`.
+
+### Clés étrangères
 
 ```js
-const User = require("user");
+const orderSchema = new Schema({
+  user_id: { type: Number, foreignKey: 'users(id)' },
+  product_id: { type: Number, foreignKey: 'products.id' },
+});
+```
 
-async function createUser(email, stat) {
-    if (!email || !stat) {
-        console.error("Email & stat is required");
-        return;
-    }
-    await User.save({ email: email, status: stat });
+`Model.syncAllTables()` respecte l'ordre des dépendances et rejette les cycles.
 
-}
+---
+
+## Modèles
+
+```js
+const User = new Model('users', userSchema);
 ```
 
-## Fonction find
+Méthodes principales :
 
-Récupère des enregistrements de la table.
+- `save(data)` — insertion ;
+- `find(options)` — recherche structurée ;
+- `count(filter)` — comptage ;
+- `delete(filter)` — suppression ;
+- `dropTable()` — suppression de table ;
+- `generate_uuid(column?)` — génération d'UUID ;
+- `customRequest(sql)` — SQL brut de confiance.
 
-- **Paramètres** `options` *(Object)* – Options de la requête.
-- **Paramètres** `options.select` *(Array<string|SelectAggregation>)* – Champs, agrégations ou transformations à retourner.
-- **Paramètres** `options.where` *(Object / string)* – Conditions de filtrage (objet clé/valeur ou clause brute sous forme de chaîne).
-- **Paramètres** `options.groupBy` *(Array<string|GroupAggregation>)* – Champs, colonnes ou expressions utilisés pour regrouper les résultats.
-- **Paramètres** `options.orderBy` *(Array<string|OrderByOption>)* – Règles de tri.
-- **Paramètres** `options.join` *(JoinOption / JoinOption[])* – Structures de configuration pour les jointures de tables.
-- **Paramètres** `options.limit` *(number)* – Nombre maximal de résultats à retourner.
-- **Retourne** `Promise<Array<ModelInstance>>`
+Exemple :
 
-### Options avancées de `select` (`SelectAggregation`)
+```js
+const users = await User.find({
+  select: ['id', 'email'],
+  where: {
+    status: { IN: ['active', 'pending'] },
+  },
+  orderBy: [
+    { field: 'email', direction: 'ASC' },
+  ],
+  limit: 50,
+  offset: 0,
+});
+```
 
-Chaque élément du tableau `select` peut être soit une chaîne de caractères standard (nom brut de la colonne), soit un objet offrant des fonctionnalités SQL et des agrégations avancées :
+---
 
-| Propriété dans l'objet `select` | Type              | Description                                                                                               |                                     Exemple / SQL Généré                                            |
-|---------------------------------|-------------------|-----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
-| `col`                           | `string`          | Sélectionne une colonne de table simple, sans agrégation.                                                 | `{ col: 'email' }` $\rightarrow$ \`email\`                                                          |
-| `sum`                           | `string`          | Calcule la somme de toutes les valeurs numériques d'une colonne.                                          | `{ sum: 'error' }` $\rightarrow$ `SUM(`\`error\``)`                                                 |
-| `distinct`                      | `string`          | Applique une contrainte DISTINCT sur la colonne spécifiée.                                                | `{ distinct: 'status' }` $\rightarrow$ `DISTINCT `\`status\`                                        |
-| `dateFormat`                    | `[string, string]`| Formate une colonne de type Date en utilisant le formatage standard MySQL (`[colonne, chaine_de_format]`).| `{ dateFormat: ['created_at', '%Y-%m'] }` $\rightarrow$ `DATE_FORMAT(`\`created_at\``, '%Y-%m')`    |
-| `count`                         | `string`          | Comptage de lignes standard (ignore les valeurs `NULL`).                                                  | `{ count: 'id' }` $\rightarrow$ `COUNT(`\`id\``)`                                                   |
-| `count` (Array)                 | `string[]`        | Calcule le nombre de combinaisons uniques sur plusieurs colonnes (COUNT DISTINCT).                        | `{ count: ['team', 'source'] }` $\rightarrow$ `COUNT( DISTINCT `\`team\``, `\`source\`` )`          |
-| `count` (Object)                | `Object`          | Agrégation conditionnelle automatisée (`CASE WHEN`). Idéal pour les indicateurs clés (KPIs) et statuts.   | `{ count: { deletedAt: null } }` $\rightarrow$ `COUNT(CASE WHEN `\`deletedAt\`` = NULL THEN 1 END)` |
-| `as`                            | `string`          | Définit un identifiant de sortie personnalisé ou un alias d'agrégation (SQL `AS`).                        | `{ count: 'id', as: 'total' }` $\rightarrow$ `COUNT(`\`id\``) AS `\`total\`                         |
+## Conditions
 
-### Options Avancées de `groupBy` (`GroupAggregation`)
+Les `where` et `having` utilisent des objets structurés. Les chaînes SQL brutes sont refusées par le builder.
 
-L'option `groupBy` accepte un tableau pouvant mélanger des chaînes de caractères simples (noms de colonnes bruts) et des objets de configuration avancés pour un regroupement sécurisé, paramétré et la gestion des alias :
+### Valeur simple
 
-| Propriété dans l'objet `groupBy` | Type              | Description                                                                                                                | Exemple / SQL Généré                                                                  |
-|----------------------------------|-------------------|----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
-| `col`                            | `string`          | Cible de manière sécurisée une colonne de table non agrégée grâce à l'isolation structurelle de l'objet.                   | `{ col: 'role' }` → \`role\`                                                          |
-| `dateFormat`                     | `[string, string]`| Regroupe de manière sécurisée par une colonne Date formatée à l'aide d'entrées paramétrées (Format : `[colonne, format]`). | `{ dateFormat: ['created_at', '%Y-%m'] }` → `DATE_FORMAT(` \`created_at\``, '%Y-%m')` |
-| `as`                             | `string`          | Cible directement l'alias défini dans le select pour respecter les contraintes strictes de syntaxe MySQL.                  | `{ col: 'role', as: 'user_role' }` → \`user_role\`                                    |
+```js
+{ status: 'active' }
+```
 
----
+### Opérateurs
+
+Les opérateurs supportés sont :
+
+```text
+=
+!=
+>
+<
+>=
+<=
+LIKE
+NOT LIKE
+ILIKE
+NOT ILIKE
+IN
+NOT IN
+BETWEEN
+NOT BETWEEN
+```
 
-### Options complexes structurées (`orderBy` & `join`)
+Exemples :
 
-#### OrderByOption
+```js
+{ age: { '>=': 18 } }
+{ email: { LIKE: '%@example.com' } }
+{ status: { IN: ['active', 'pending'] } }
+{ age: { BETWEEN: [18, 65] } }
+```
+
+### NULL
+
+```js
+{ deleted_at: null }
+{ deleted_at: { '=': null } }
+{ deleted_at: { '!=': null } }
+```
 
-Permet d'appliquer un tri explicite sur une ou plusieurs colonnes :
+Ces formes deviennent `IS NULL` / `IS NOT NULL`.
 
-- **field** `(string)` : Le nom de la colonne cible sur laquelle appliquer le tri.
-- **direction** `('ASC'\|'DESC')` : Le sens du tri (Par défaut : `'ASC'`).
+### AND / OR / NOT
 
-#### JoinOption
+```js
+{
+  AND: [
+    { active: true },
+    {
+      OR: [
+        { role: 'admin' },
+        { role: 'moderator' },
+      ],
+    },
+  ],
+}
+```
 
-Spécifie une ou plusieurs jointures de tables relationnelles :
+```js
+{
+  NOT: {
+    status: { IN: ['deleted', 'blocked'] },
+  },
+}
+```
 
-- **table** `(string)` : Nom de la table cible à joindre.
-- **on** `(string)` : Chaîne de caractères représentant la condition de jointure (ex: `"MyTable.project_id = Projects.id"`).
-- **alias** `(string)` *(Optionnel)* : Un alias SQL alternatif pour la table jointe.
-- **type** `('INNER'\|'LEFT'\|'RIGHT')` *(Optionnel)* : Type de jointure SQL (Par défaut : `'INNER'`).
+Les tableaux `AND` / `OR` vides et les valeurs invalides de `NOT` sont refusés.
 
 ---
 
-## Exemple find
+## Select, agrégations, groupement et tri
 
-```js
-const User = require("user");
+Le `select` accepte des chaînes ou des objets structurés :
 
-await User.find({
+```js
+const stats = await User.find({
   select: [
-    { dateFormat: ['date_day', '%Y-%m'], as: 'period' },
-    { sum: 'error' },
-    { sum: 'reload' },
+    'status',
+    { count: 'id', as: 'total' },
+    { sum: 'amount', as: 'revenue' },
   ],
-  groupBy: ['period', { dateFormat: ['date_day', '%Y-%m'] }],
-  orderBy: [{ field: 'period', direction: 'ASC' }],
-  limit: 10
+  where: {
+    active: true,
+  },
 });
 ```
 
-```js
-const User = require("user");
+### Groupement avec `GROUP BY`
+
+`groupBy` est une option de `find()` et permet de regrouper les lignes avant l'application de `having`.
 
-await User.find({
+```js
+const stats = await User.find({
   select: [
-    "email"
+    'status',
+    { count: 'id', as: 'total' },
   ],
-  where: {
-    id: 1
-  }
-})
+  groupBy: ['status'],
+});
 ```
 
-### Exemples avancés avec `find`
+Les éléments de `groupBy` peuvent être des colonnes ou des expressions structurées comme `dateFormat`.
 
-#### 1. Comptage standard, distinct et multi-colonnes
+### Filtrer les groupes avec `HAVING`
 
-Comptez les lignes globales parallèlement à des combinaisons uniques multi-colonnes, comme l'identification des couples uniques d'équipes et de sources de pipelines :
+`having` filtre le résultat **après** le `GROUP BY` et utilise le même format de conditions structurées que `where` :
 
 ```js
-const { MyTable } = require("./models");
-
-const stats = await MyTable.find({
+const stats = await User.find({
   select: [
-    { count: 'id', as: 'total_pipelines' },
-    { count: ['cteam', 'csource'], as: 'unique_groups' } // COUNT DISTINCT multi-colonnes
+    'status',
+    { count: 'id', as: 'total' },
   ],
-  where: { csource: 'web' }
+  groupBy: ['status'],
+  having: {
+    total: { '>': 10 },
+  },
 });
 ```
 
-#### 2. Agrégations conditionnelles (Indicateurs KPIs Actifs / Inactifs)
+Les chaînes SQL brutes dans `having` sont refusées.
 
-En passant un objet à l'attribut count, l'ORM structure automatiquement une clause conditionnelle CASE WHEN. Cela vous permet de ventiler différents compteurs de statuts en une seule et unique requête vers la base de données :
+### Tri avec `ORDER BY`
 
-```js
-const { ProjectPipeline } = require("./models");
+`orderBy` permet de trier le résultat final. Il accepte des colonnes ou des alias de sélection, avec une direction `ASC` ou `DESC` :
 
-const ppiStats = await ProjectPipeline.find({
+```js
+const stats = await User.find({
   select: [
-    { count: { deletedAt: null }, as: 'active' },          // Compte les lignes où deletedAt = NULL
-    { count: { status: 'SUCCESS' }, as: 'total_success' }   // Compte les lignes où status = 'SUCCESS'
+    'status',
+    { count: 'id', as: 'total' },
+  ],
+  groupBy: ['status'],
+  having: {
+    total: { '>': 10 },
+  },
+  orderBy: [
+    { field: 'total', direction: 'DESC' },
+    { field: 'status', direction: 'ASC' },
   ],
-  where: {
-    source: 'jenkins',
-    team: 'GROUP-1'
-  }
 });
-  ```
+```
 
-#### 3. Jointures de tables, groupement temporel et tri multi-colonnes
+### Exemple complet
 
-Une orchestration de requête avancée combinant une jointure gauche (LEFT JOIN), des conversions de formats de date et des tris :
+Toutes les clauses peuvent être combinées dans une seule requête :
 
 ```js
-const { ProjectPipeline } = require("./models");
-
-const history = await ProjectPipeline.find({
+const stats = await User.find({
   select: [
-    { col: 'Projects.name', as: 'project_name' },
-    { dateFormat: ['MyTable.created_at', '%Y-%m'], as: 'period' },
-    { count: 'MyTable.id', as: 'pipelines_count' }
+    'status',
+    { count: 'id', as: 'total' },
+    { sum: 'amount', as: 'revenue' },
   ],
   where: {
-    status: 'ACTIVE'
+    active: true,
   },
-  join: {
-    table: 'Projects',
-    on: 'MyTable.project_id = Projects.id',
-    type: 'LEFT'
+  groupBy: ['status'],
+  having: {
+    total: { '>': 10 },
   },
-  groupBy: [
-    'project_name',
-    { dateFormat: ['ProjectPipelines.created_at', '%Y-%m'] }
-  ],
   orderBy: [
-    { field: 'period', direction: 'DESC' },
-    { field: 'project_name', direction: 'ASC' }
+    { field: 'total', direction: 'DESC' },
   ],
-  limit: 50
 });
 ```
 
-## Fonction count
+Ce flux correspond à `SELECT` → `WHERE` → `GROUP BY` → `HAVING` → `ORDER BY`. Les valeurs de `where` et `having` sont paramétrées par le Connector.
 
-Compte le nombre d'enregistrements correspondant au filtre donné.
+---
 
-- **Parameters** `filter` *(Object)* Les critères de filtrage de la requête. Il doit s'agir d'un objet dont les clés sont les noms des colonnes et les valeurs sont les valeurs de filtrage.
-- **Returns** `Promise<ModelInstance|number>` - Une promesse qui se résout en une instance `ModelInstance` si un enregistrement est trouvé, ou en `0` si aucun enregistrement ne correspond au filtre.
+## Jointures
 
-## Exemple count
+La couche `Model.find()` génère actuellement une `INNER JOIN` à partir de `table` et `on` :
 
 ```js
-const User = require("user");
+join: {
+  table: 'profiles',
+  on: 'users.id = profiles.user_id',
+}
+```
+
+L'expression `on` doit être considérée comme du SQL de confiance.
+
+---
+
+## Synchronisation
 
-await User.count({
-  id: id
-})
+```js
+await Model.syncAllTables();
 ```
 
-## Fonction customRequest
+La synchronisation crée les tables dans l'ordre des dépendances de clés étrangères et détecte les cycles.
 
-La fonction customRequest vous permet d'exécuter des requêtes SQL non prises en charge par sql-connector ; cela peut concerner des requêtes utilisant des mots-clés qui ne sont pas encore implémentés.
+Pour les évolutions contrôlées du schéma, utilisez les migrations.
 
-- **Parameters** `custom` *(string)*  La requête SQL personnalisée à exécuter.
-- **Returns** `Promise<void>` Valeur retournée
-- **Throws** `Error` Lève une erreur si l'exécution de la requête échoue.
+---
 
-## Exemple customRequest
+## Instances de modèle
 
 ```js
-const User = require("user");
+const [user] = await User.find({
+  where: { email: 'user@example.com' },
+});
 
-await User.customRequest("SELECT id, email, status
-  FROM users
-  WHERE status IN ('active', 'pending')
-  AND email LIKE '%gmail.com';")
+await user.updateOne({ status: 'inactive' });
+await user.delete();
 ```
 
-## Fonction delete
+Méthodes : `updateOne`, `delete`, `customRequest`, `getRecordData`, `toJSON`.
 
-Supprime de la table SQL une entrée correspondant au filtre fourni.
+---
 
-- **Parameters** `filter` *(Object)* Un objet représentant les conditions de filtrage pour la suppression.
-- **Returns** `Promise<number>` Une promesse qui se résout à 0 si aucune ligne n'a été supprimée, ou à une instance de modèle représentant la ligne supprimée.
-- **Throws** `Error` Une promesse qui se résout à 0 si aucune ligne n'a été supprimée, ou à une instance de modèle représentant la ligne supprimée.
+## Migrations
 
-## Exemple delete
+Le système de migration compare les modèles souhaités au schéma réellement présent dans la base, produit un plan puis génère le SQL adapté au dialecte.
 
 ```js
-const User = require("user");
-
-await User.delete({
-  email: my@gmail.com
-})
+const {
+  Migration,
+  MigrationPlan,
+  MigrationStore,
+  MigrationRunner,
+  SchemaDiffer,
+  SchemaInspector,
+} = require('@mlagie/sql-connector');
 ```
 
-## Fonction dropTable
+### Migration Workflow
 
-Supprime de manière asynchrone une table si elle existe dans la base de données.
+```js
+const migration = new Migration({
+  encryptionKey: process.env.SQL_CONNECTOR_MIGRATION_KEY,
+});
 
-Cette fonction construit une requête SQL pour supprimer la table dont le nom est spécifié par la propriété `this.name`. Elle exécute ensuite la requête en utilisant une approche basée sur les promesses.
-Si la requête aboutit, le résultat est consigné dans la console.
+const plan = await migration.plan({
+  name: 'users-schema',
+});
 
-En cas d'erreur lors de l'exécution de la requête, un message d'erreur est consigné.
+console.log(plan.toJSON());
 
-- **Returns** `Promise<void>` Une promesse qui se résout une fois l'exécution de la requête terminée.
+if (plan.hasChanges()) {
+  plan.approve();
+  await plan.execute();
+}
+```
 
-## Example dropTable
+Ou directement :
 
 ```js
-const User = require("user");
-
-await User.dropTable();
+await Migration.migrate({
+  name: 'users-schema',
+  encryptionKey: process.env.SQL_CONNECTOR_MIGRATION_KEY,
+});
 ```
 
-## generate_uuid function
+### Migration Options
+
+| Option | Description |
+|---|---|
+| `connection` | Connexion existante. |
+| `dialect` | `mysql`, `postgres` ou instance de dialecte. |
+| `models` | Modèles à comparer. |
+| `directory` | Dossier des migrations. |
+| `backupDirectory` | Dossier des sauvegardes. |
+| `encryptionKey` | Clé de chiffrement. |
+| `retention` | Durée de conservation (`ms`, `s`, `m`, `h`, `d`, `w`). |
+| `allowDestructiveChanges` | Autorise les suppressions de colonnes. |
+| `allowDropTables` | Autorise les suppressions de tables. |
 
-Génère un UUID unique pour le modèle actuel.
+### Migration Opérations
 
-Cette fonction génère un UUID à l'aide de la fonction `UUID()` de SQL_request et vérifie si cet UUID existe déjà dans la base de données pour le modèle actuel. Si l'UUID est unique, il est renvoyé.
+Le diff peut générer :
 
-Sinon, la fonction renvoie `null`.
+- `createTable` ;
+- `addColumn` ;
+- `renameColumn` ;
+- `alterColumn` ;
+- `dropColumn` — destructif ;
+- `dropTable` — destructif.
 
-- **Parameters** `string` var_uuid Par defaut il vaut uuid
-- **Returns** `Promise<string|null>` Une promesse qui se résout en une chaîne UUID unique en cas de succès, ou en `null` si une erreur survient ou si l'UUID n'est pas unique.
-- **Throws** `Error` S'il y a une erreur lors de l'exécution de la requête SQL_request.
+### Migration Renommage
 
-## Example generate_uuid
+Le renommage doit être explicite avec `oldname` :
 
 ```js
-const User = require("user");
+email_address: {
+  type: String,
+  length: 320,
+  oldname: 'email',
+}
+```
+
+### Changements destructifs
+
+Par défaut, la suppression d'une colonne ou d'une table est bloquée.
 
-const uuid = await User.generate_uuid();
-const my_uuid = await User.generate_uuid("my_uuid");
+```js
+const plan = await migration.plan({
+  allowDestructiveChanges: true,
+  allowDropTables: true,
+});
 
-await User.save({ email: "user@example.com", status: "active", uuid: uuid, my_uuid: my_uuid })
+plan.approve();
+await plan.execute({
+  allowDestructiveChanges: true,
+});
 ```
 
-## Instances de modèle
+L'approbation et l'autorisation destructive sont deux protections distinctes.
+
+### Checksum et historique
+
+Le runner crée `sql_connector_migrations` et enregistre l'identifiant, le checksum SHA-256 et les dates d'application/création.
 
-`ModelInstance` représente une ligne déjà chargée depuis la base.
+Un identifiant déjà appliqué avec un checksum différent provoque une erreur.
 
-- `updateOne(model)` met à jour la ligne
-- `delete(model)` supprime la ligne avec un filtre
-- `delete()` supprime la ligne de l'instance
-- `customRequest(custom)` exécute une requête personnalisée
+### Chiffrement
 
-```javascript
-const userInstance = new ModelInstance('users', { email: 'user@example.com' });
+Les migrations sont écrites en `.sql.enc`.
 
-await userInstance.updateOne({ status: 'inactive' });
-await userInstance.delete();
+```bash
+export SQL_CONNECTOR_MIGRATION_KEY='un-secret-long-et-aleatoire'
 ```
 
-## Types SQL
+Le format utilise AES-256-GCM et une clé dérivée.
 
-`sqlTypeMap` expose les types SQL les plus courants.
+### Sauvegardes
 
-```javascript
-console.log(sqlTypeMap.String); // "VARCHAR"
+Avec `retention`, les tables affectées sont sauvegardées avant la migration dans des fichiers JSON chiffrés.
+
+```js
+new Migration({
+  encryptionKey: process.env.SQL_CONNECTOR_MIGRATION_KEY,
+  retention: '30d',
+});
 ```
 
-## Client
+La sauvegarde est un snapshot de données et ne constitue pas un rollback automatique.
 
-`client` est un objet partagé pensé pour centraliser des fonctions applicatives réutilisables.
+### Statut et nettoyage
 
-```javascript
-module.exports = client => {
-  client.checkServer = () => {
-    if (server.isLaunch()) {
-      return 1;
-    }
+```js
+const migration = new Migration();
+const status = await migration.status();
+console.table(status);
 
-    return 0;
-  };
-};
+await migration.cleanup();
 ```
 
-## Résumé
+---
+
+## TypeScript
+
+Le package fournit `index.d.ts` avec les types de schéma, conditions, requêtes, modèles et migrations.
+
+```ts
+import {
+  Schema,
+  Model,
+  Migration,
+  InferSchema,
+} from '@mlagie/sql-connector';
+```
+
+---
+
+## Sécurité SQL
+
+Le builder structuré sépare les identifiants SQL des valeurs :
+
+- valeurs `WHERE` paramétrées ;
+- valeurs `HAVING` paramétrées ;
+- éléments de `IN` / `NOT IN` paramétrés ;
+- bornes de `BETWEEN` paramétrées ;
+- placeholders PostgreSQL numérotés ;
+- échappement des identifiants ;
+- refus des `WHERE` / `HAVING` sous forme de chaînes brutes.
+
+`customRequest()` reste volontairement une porte d'accès au SQL brut et doit recevoir uniquement du SQL de confiance.
+
+---
+
+## API exportée
+
+```text
+client
+connect
+logout
+Schema
+Model
+ModelInstance
+sqlTypeMap
+Migration
+MigrationPlan
+MigrationStore
+MigrationRunner
+SchemaDiffer
+SchemaInspector
+MySQLDialect
+PostgreSQLDialect
+```
+
+---
+
+## Tests
+
+```bash
+npm install
+npm test
+npm run test:coverage
+npm run security
+```
+
+---
+
+## Documentation détaillée
+
+- [Index de documentation](../README.md)
+- [Schéma](../SCHEMA.md)
+- [Conditions et requêtes](../QUERY.md)
+- [Migrations](../MIGRATIONS.md)
+- [API](../API.md)
+- [Dialectes](../DIALECTS.md)
+- [Contribution](../../CONTRIBUTING.md)
+- [Sécurité](../../SECURITY.md)
+
+## Licence
 
-sql-connector fournit une couche simple pour connecter une base MySQL, décrire des schémas, synchroniser les tables et manipuler les données avec des modèles typés.
+MIT — voir [LICENSE](../../LICENSE).