@mlagie/sql-connector 3.0.3 → 3.1.0

package/README.md

@@ -1,510 +1,1179 @@
-# sql-connector documentation
+# @mlagie/sql-connector
 
-![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)
+[![npm downloads](https://img.shields.io/npm/dm/%40mlagie%2Fsql-connector)](https://www.npmjs.com/package/@mlagie/sql-connector)
+[![license](https://img.shields.io/github/license/mlagie/sql-connector)](https://github.com/mlagie/sql-connector/blob/main/LICENSE)
 
-[Français](./docs/fr/README_FR.md) | English
+A small, typed and dialect-aware SQL layer for **MySQL** and **PostgreSQL**.
 
-sql-connector helps manage MySQL and PostgreSQL connections, define table schemas, sync tables automatically, and work with database models through a small API.
+`@mlagie/sql-connector` provides:
 
-## Import
+- connection management;
+- declarative table schemas;
+- SQL type aliases and native SQL types;
+- CRUD operations through models;
+- structured `WHERE` / `HAVING` conditions;
+- `IN`, `BETWEEN`, `LIKE`, `ILIKE`, `NULL`, `AND`, `OR` and `NOT` conditions;
+- aggregations, grouping, ordering and joins;
+- foreign-key dependency ordering;
+- schema synchronization;
+- migration planning, approval, execution and status tracking;
+- migration checksums, encrypted migration files and optional encrypted backups;
+- TypeScript declarations for the public API.
 
-```javascript
-const { Schema, connect, logout, Model, ModelInstance, client, sqlTypeMap } = require('sql-connector');
+> **Supported database engines:** MySQL and PostgreSQL.
+>
+> SQL generated by the connector is dialect-specific where necessary. The schema API stays the same across supported engines.
+
+**Documentation:** [English](#table-of-contents) · [Français](./docs/fr/README_FR.md) · [Detailed documentation](./docs/README.md)
+
+---
+
+## Table of contents
+
+1. [Installation](#installation)
+2. [Quick start](#quick-start)
+3. [Connection](#connection)
+4. [Schemas](#schemas)
+   - [Schema field options](#schema-field-options)
+   - [Types](#types)
+   - [Defaults and values](#defaults-and-values)
+   - [Constraints](#constraints)
+   - [Foreign keys](#foreign-keys)
+5. [Models](#models)
+   - [`save`](#save)
+   - [`find`](#find)
+   - [`count`](#count)
+   - [`delete`](#delete)
+   - [`dropTable`](#droptable)
+   - [`generate_uuid`](#generate_uuid)
+   - [`customRequest`](#customrequest)
+6. [Conditions](#conditions)
+   - [Simple values](#simple-values)
+   - [Comparison operators](#comparison-operators)
+   - [`IN` / `NOT IN`](#in--not-in)
+   - [`BETWEEN` / `NOT BETWEEN`](#between--not-between)
+   - [`NULL`](#null)
+   - [`AND` / `OR` / `NOT`](#and--or--not)
+7. [Select, aggregation, grouping and ordering](#select-aggregation-grouping-and-ordering)
+8. [Joins](#joins)
+9. [Schema synchronization](#schema-synchronization)
+10. [Model instances](#model-instances)
+11. [Migrations](#migrations)
+    - [Migration workflow](#migration-workflow)
+    - [Migration options](#migration-options)
+    - [Migration plans](#migration-plans)
+    - [Destructive changes](#destructive-changes)
+    - [Checksums](#checksums)
+    - [Encrypted files](#encrypted-files)
+    - [Backups and retention](#backups-and-retention)
+    - [Migration status](#migration-status)
+12. [TypeScript](#typescript)
+13. [Security and SQL safety](#security-and-sql-safety)
+14. [Dialect matrix](#dialect-matrix)
+15. [API exports](#api-exports)
+16. [Testing](#testing)
+17. [Related documentation](#related-documentation)
+18. [License](#license)
+
+---
+
+## Installation
+
+```bash
+npm install @mlagie/sql-connector
 ```
 
-## Database connection
+The package includes both MySQL (`mysql2`) and PostgreSQL (`pg`) drivers.
 
-`connect(config, dialect)` opens a database connection. MySQL is used by default; pass `"postgres"` to use PostgreSQL.
+---
 
-```javascript
-const config = {
+## Quick start
+
+```js
+const {
+  Schema,
+  Model,
+  connect,
+  logout,
+} = require('@mlagie/sql-connector');
+
+await connect({
   host: 'localhost',
   port: 3306,
   user: 'root',
   password: 'password',
-  database: 'mydatabase'
-};
+  database: 'mydatabase',
+});
+
+const userSchema = new Schema({
+  id: {
+    type: Number,
+    auto_increment: true,
+    primary_key: true,
+  },
+  email: {
+    type: String,
+    length: 255,
+    required: true,
+    unique: true,
+  },
+  status: {
+    type: String,
+    enum: ['active', 'inactive', 'pending'],
+    default: 'pending',
+  },
+});
+
+const User = new Model('users', userSchema);
+
+await Model.syncAllTables();
+await User.save({ email: 'user@example.com', status: 'active' });
+
+const users = await User.find({
+  where: {
+    status: { IN: ['active', 'pending'] },
+  },
+});
+
+console.log(users);
+
+await logout();
+```
+
+For migrations, use the same models as the desired schema:
+
+```js
+const { Migration } = require('@mlagie/sql-connector');
+
+const migration = new Migration({
+  encryptionKey: process.env.SQL_CONNECTOR_MIGRATION_KEY,
+});
+
+const plan = await migration.plan({ name: 'sync-users' });
+
+if (plan.hasChanges()) {
+  plan.approve();
+  await plan.execute();
+}
+```
+
+---
+
+## Connection
 
-await connect(config);
+### MySQL
+
+MySQL is the default dialect.
+
+```js
+await connect({
+  host: 'localhost',
+  port: 3306,
+  user: 'root',
+  password: 'password',
+  database: 'mydatabase',
+});
 ```
 
 ### PostgreSQL
 
-PostgreSQL uses the `pg` driver:
+Pass `postgres` as the second argument.
 
-```javascript
-const postgresConfig = {
+```js
+await connect({
   host: 'localhost',
   port: 5432,
   user: 'postgres',
   password: 'password',
-  database: 'mydatabase'
-};
+  database: 'mydatabase',
+}, 'postgres');
+```
+
+### Close the connection
 
-await connect(postgresConfig, 'postgres');
+```js
+await logout();
 ```
 
-Supported dialects are `mysql` and `postgres`.
+---
 
-| Dialect | Identifier quotes | Query placeholders | Boolean defaults |
-|---------|-------------------|--------------------|------------------|
-| MySQL | Backticks | `?` | `1` / `0` |
-| PostgreSQL | Double quotes | `$1`, `$2`, ... | `TRUE` / `FALSE` |
+## Schemas
 
-`logout()` closes the active connection.
+`Schema` describes the desired structure of a SQL table. A field may be declared with a JavaScript constructor, a SQL-connector type alias, or an object containing a type name.
 
-```javascript
-await logout();
+```js
+const schema = new Schema({
+  name: { type: String, length: 120, required: true },
+  age: { type: Number },
+  active: { type: Boolean, default: true },
+});
 ```
 
-### Example
+### Schema field options
+
+| Property | Type | Description |
+|---|---|---|
+| `type` | constructor / string / `{ name }` | Field type. |
+| `length` | `number` | Length for length-based types. |
+| `precision` | `number` | Decimal precision. |
+| `scale` | `number` | Decimal scale. |
+| `required` | `boolean` | Adds `NOT NULL`. |
+| `default` | any | SQL column default. |
+| `unique` | `boolean` | Adds `UNIQUE`. |
+| `primary_key` | `boolean` | Adds `PRIMARY KEY`. |
+| `auto_increment` | `boolean` | Enables auto-increment / identity behavior depending on dialect. |
+| `enum` | `string[]` | Allowed values. |
+| `foreignKey` | `string` | Foreign-key target such as `users(id)` or `users.id`. |
+| `oldname` | `string` | Existing column name used by migrations to request an explicit rename. |
+| `customize` | `string` | Additional SQL definition appended to the column. |
+
+> Do not combine `primary_key: true` and `unique: true` on the same field. A primary key is already unique and non-null.
+
+### Types
+
+`sqlTypeMap` exposes the connector's supported SQL type aliases:
+
+| Alias | SQL type | Typical JavaScript value |
+|---|---|---|
+| `String` | `VARCHAR` | `string` |
+| `Char` | `CHAR` | `string` |
+| `Number` | `INT` | `number` |
+| `SmallInt` | `SMALLINT` | `number` |
+| `BigInt` | `BIGINT` | `number` / `bigint` |
+| `Decimal` | `DECIMAL` | `number` / decimal string |
+| `Boolean` | `BOOLEAN` | `boolean` |
+| `Date` | `DATETIME` | `Date` |
+| `DateTime` | `DATETIME` | `Date` |
+| `Timestamp` | `TIMESTAMP` | `Date` |
+| `Float` | `FLOAT` | `number` |
+| `Double` | `DOUBLE` | `number` |
+| `Text` | `TEXT` | `string` |
+| `Blob` | `BLOB` | `Buffer` / binary data |
+| `Binary` | `VARBINARY` | binary data |
+| `Uuid` | `CHAR` | `string` |
+| `Object` | `JSON` | object |
+| `Array` | `VARCHAR` | array / serialized value |
+| `Now` | `NOW()` | SQL temporal expression* |
+| `CurrentTimestamp` | `CURRENT_TIMESTAMP` | SQL temporal expression* |
+
+For `Now` and `CurrentTimestamp`, the mapped values are SQL expressions/constants and are primarily intended for defaults; they are not storage column types.
+
+Example:
 
 ```js
-const { connect: dbConnect, client, Model } =  require("@mlagie/sql-connector");
+const { sqlTypeMap } = require('@mlagie/sql-connector');
+
+console.log(sqlTypeMap.String);           // VARCHAR
+console.log(sqlTypeMap.CurrentTimestamp); // CURRENT_TIMESTAMP
+```
+
+The schema API also accepts the JavaScript constructors `String`, `Number`, `Boolean`, `Date`, `Object` and `Array`.
+
+### Length, precision and scale
 
+Length-based types support `length`:
 
-await dbConnect({
-    host: 'localhost',
-    port: 3306,
-    user: 'root',
-    password: 'password',
-    database: 'mydatabase',
-    connectionLimit: 2,
-    multipleStatements: true,
-    idleTimeout: 10000,
-    typeCast: true,
-    }).then(() => { Logger.client("- connected to the database") }).catch(error => {
-        console.error(error);
-        process.exit();
+```js
+const schema = new Schema({
+  code: { type: String, length: 32 },
+  fixed_code: { type: 'CHAR', length: 8 },
+  binary_code: { type: 'VARBINARY', length: 64 },
 });
 ```
 
-## Schema
-
-`Schema` describes the structure of a table. Each field can use the following properties.
+For decimal values:
 
-| Property       | Type                             | Description            |
-|----------------|----------------------------------|------------------------|
-| type           | `SqlType` or `{ name: SqlType }` | SQL type for the field |
-| length         | `number`                         | Maximum length         |
-| required       | `boolean`                        | Not null constraint    |
-| default        | `any`                            | Default value          |
-| unique         | `boolean`                        | Unique constraint      |
-| auto_increment | `boolean`                        | Auto increment         |
-| foreignKey     | `string`                         | Foreign key reference  |
-| enum           | `string[]`                       | Allowed values         |
-| primary_key    | `boolean`                        | Primary key flag       |
-| customize      | `string`                         | Extra SQL options      |
+```js
+const schema = new Schema({
+  amount: {
+    type: 'DECIMAL',
+    precision: 12,
+    scale: 2,
+  },
+});
+```
 
-### Example Schema creation & Model Creation
+### Defaults and values
 
-```javascript
-const { Schema, Model, sqlTypeMap } = require("@mlagie/sql-connector");
+The `default` property accepts values that the active dialect can format as SQL defaults:
 
-const userSchema = new Schema({
-    id: {
-        type: Number,
-        auto_increment: true,
-        primary_key: true
-    },
-    group_uuid: {
-        type: String,
-        required: true,
-        primary_key: true,
-        length: 36
-    },
-    email: {
-        type: String,
-        length: 255,
-        unique: true,
-        required: true
-    },
-    status: {
-        type: String,
-        enum: ['active', 'inactive', '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
-    }
+```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' } },
 });
+```
+
+Supported default value forms include:
+
+- `null`;
+- strings;
+- numbers and `bigint` values;
+- booleans;
+- `Date` instances;
+- objects, serialized as JSON text;
+- temporal SQL values such as `CURRENT_TIMESTAMP`, `NOW` and `NOW()`;
+- functions returning a supported value.
+
+`sqlTypeMap.CurrentTimestamp` can also be used as a semantic constant:
+
+```js
+created_at: {
+  type: Date,
+  default: sqlTypeMap.CurrentTimestamp,
+}
+```
+
+### Constraints
 
-module.exports = new Model("User", userSchema);
+```js
+const schema = new Schema({
+  id: {
+    type: Number,
+    primary_key: true,
+    auto_increment: true,
+  },
+  email: {
+    type: String,
+    required: true,
+    unique: true,
+    length: 320,
+  },
+});
 ```
 
-Example with multiple foreign keys:
+The connector supports the schema-level concepts `NOT NULL`, `UNIQUE`, `PRIMARY KEY`, `FOREIGN KEY`, `DEFAULT`, `ENUM`, auto-increment and custom SQL options.
+
+### Foreign keys
 
-```javascript
+```js
 const orderSchema = new Schema({
-  user_id: { type: Number, foreignKey: 'users(id)' },
-  product_id: { type: Number, foreignKey: 'products.id' }
+  user_id: {
+    type: Number,
+    foreignKey: 'users(id)',
+  },
+  product_id: {
+    type: Number,
+    foreignKey: 'products.id',
+  },
 });
 ```
 
-## Table synchronization
+`Model.syncAllTables()` sorts models according to their foreign-key dependencies. Cyclic dependencies are rejected instead of being silently reordered.
 
-`Model.syncAllTables()` compares JS schemas with the database and applies only meaningful differences. Foreign-key dependencies are created in the required order, and cyclic dependencies are rejected.
+---
 
-- New columns are added automatically.
-- Foreign keys use the `table(column)` format and may be declared on multiple fields.
+## Models
 
-```javascript
-await Model.syncAllTables();
+`Model` represents a database table.
+
+```js
+const User = new Model('users', userSchema);
 ```
 
-Important: do not set both `primary_key: true` and `unique: true` on the same field. A primary key is already unique and not null.
+### `save`
 
-## Models
+```js
+await User.save({
+  email: 'user@example.com',
+  status: 'active',
+});
+```
 
-`Model` represents a SQL table.
+`save(data)` inserts the supplied fields. Values are sent through driver parameters rather than interpolated into the SQL statement.
 
-Main methods:
+### `find`
 
-- `save(data)` Inserts a row
-- `find(options)` Retrieves entries from the table.
-- `count(filter)` Counts rows
-- `customRequest(custom)` Runs a custom SQL query
-- `delete(filter)` Deletes a row
-- `dropTable()` Drops the table
-- `generate_uuid()` Generates a unique UUID
+```js
+const users = await User.find({
+  select: ['id', 'email', { count: 'id', as: 'total' }],
+  where: {
+    status: { IN: ['active', 'pending'] },
+  },
+  groupBy: ['id', 'email'],
+  orderBy: [
+    { field: 'email', direction: 'ASC' },
+  ],
+  limit: 50,
+  offset: 0,
+});
+```
 
-```javascript
-const userModel = new Model('users', userSchema);
+Supported options:
 
-await Model.syncAllTables();
-await userModel.save({ email: 'user@example.com', status: 'active' });
+| Option | Type | Description |
+|---|---|---|
+| `select` | `SelectItem[]` | Columns, `SUM`, `COUNT`, `DISTINCT`, date formatting and aliases. |
+| `where` | structured condition object | Filters rows. Raw SQL strings are rejected. |
+| `groupBy` | array | Columns or date-format expressions. |
+| `having` | structured condition object | Filters grouped results. Raw SQL strings are rejected. |
+| `orderBy` | array | `{ field, direction }` sorting or string columns. |
+| `join` | object | Join configuration. |
+| `limit` | integer | Maximum number of rows. `0` is treated as no limit by the current implementation. |
+| `offset` | integer | Number of rows to skip. |
+
+### `count`
+
+```js
+const total = await User.count({
+  status: 'active',
+});
+```
+
+`count(filter)` returns the number of matching rows.
+
+### `delete`
+
+```js
+await User.delete({
+  email: 'user@example.com',
+});
+```
+
+The method returns `1` when rows are affected and `0` otherwise.
+
+### `dropTable`
 
-const user = await userModel.find({ where: { email: 'user@example.com' }});
-await user[0].delete();
+```js
+await User.dropTable();
 ```
 
-## save function
+Drops the model table.
+
+### `generate_uuid`
+
+```js
+const uuid = await User.generate_uuid();
+const customUuid = await User.generate_uuid('custom_uuid');
+```
 
-Saves data to the database table.
+The method asks the active dialect for a UUID, checks uniqueness and returns the generated UUID or `null`.
 
-- **Parameters** `data` *(Object)* - The data to insert into the table.
-- **Returns** `Promise<Object>` - A promise that resolves with the result of the insertion.
-- **Throws** `Error` - Throws an error if the insert fails.
+### `customRequest`
 
 ```js
-const User = require("user");
+const result = await User.customRequest(
+  'SELECT id, email FROM users'
+);
+```
+
+Use this escape hatch for SQL features not represented by the structured query API. Because the SQL string is executed as supplied, only use trusted SQL here.
+
+---
+
+## Conditions
 
-async function createUser(email, stat) {
-    if (!email || !stat) {
-        console.error("Email & stat is required");
-        return;
-    }
-    await User.save({ email: email, status: stat });
+Conditions are represented as JavaScript objects. Raw `WHERE` and `HAVING` strings are intentionally rejected by the structured query builder.
 
+### Simple values
+
+```js
+{ status: 'active' }
+```
+
+Generates a parameterized equality comparison.
+
+Multiple fields are combined with `AND`:
+
+```js
+{
+  status: 'active',
+  role: 'admin',
 }
 ```
 
-## find function
+### Comparison operators
 
-Retrieves entries from the table.
+The supported comparison operators are:
 
-- **Parameters** `options` *(Object)* - Query options.
-- **Parameters** `options.select` *(Array<string|SelectAggregation>)* - Fields, aggregations, or transformations to be returned.
-- **Parameters** `options.where` *(Object / string)* - Filtering conditions (key/value object or raw string condition).
-- **Parameters** `options.groupBy` *(Array<string|GroupAggregation>)* - Fields, columns, or expressions used to group results.
-- **Parameters** `options.orderBy` *(Array<string|OrderByOption>)* - Sorting rules.
-- **Parameters** `options.join` *(JoinOption / JoinOption[])* - Table join configuration structures.
-- **Parameters** `options.limit` *(number)* - Maximum number of results to return.
-- **Returns** `Promise<Array<ModelInstance>>`
+| Operator | Example |
+|---|---|
+| `=` | `{ age: { '=': 18 } }` |
+| `!=` | `{ status: { '!=': 'deleted' } }` |
+| `>` | `{ age: { '>': 18 } }` |
+| `<` | `{ age: { '<': 65 } }` |
+| `>=` | `{ age: { '>=': 18 } }` |
+| `<=` | `{ age: { '<=': 65 } }` |
+| `LIKE` | `{ email: { LIKE: '%@example.com' } }` |
+| `NOT LIKE` | `{ email: { 'NOT LIKE': '%@example.com' } }` |
+| `ILIKE` | `{ email: { ILIKE: '%@example.com' } }` |
+| `NOT ILIKE` | `{ email: { 'NOT ILIKE': '%@example.com' } }` |
+| `IN` | `{ status: { IN: ['active', 'pending'] } }` |
+| `NOT IN` | `{ status: { 'NOT IN': ['deleted'] } }` |
+| `BETWEEN` | `{ age: { BETWEEN: [18, 65] } }` |
+| `NOT BETWEEN` | `{ age: { 'NOT BETWEEN': [18, 65] } }` |
 
-### Advanced `select` Options (`SelectAggregation`)
+`ILIKE` is native on PostgreSQL. On MySQL it falls back to a case-insensitive `LOWER(column) LIKE LOWER(value)` expression.
 
-Each element in the `select` array can be either a standard string (raw column name) or an object providing advanced SQL capabilities and aggregations:
+### `IN` / `NOT IN`
 
-| Property inside `select` object | Type              | Description                                                                                          |                                  Example / Generated SQL                                           |
-|---------------------------------|-------------------|------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
-| `col`                           | `string`          | Selects a plain, unaggregated table column.                                                          | `{ col: 'email' }` $\rightarrow$ \`email\`                                                         |
-| `sum`                           | `string`          | Computes the sum of all numerical values in a column.                                                | `{ sum: 'error' }` $\rightarrow$ `SUM(` \`error\``)`                                               |
-| `distinct`                      | `string`          | Applies a DISTINCT constraint on the specified column.                                               | `{ distinct: 'status' }` $\rightarrow$ `DISTINCT` \`status\`                                       |
-| `dateFormat`                    | `[string, string]`| Formats a Date column using standard MySQL formatting (Format: `[column, mysql_format_string]`).     | `{ dateFormat: ['created_at', '%Y-%m'] }` $\rightarrow$ `DATE_FORMAT(` \`created_at\``, '%Y-%m')`  |
-| `count`                         | `string`          | Standard row counting (ignores `NULL` values).                                                       | `{ count: 'id' }` $\rightarrow$ `COUNT(` \`id\``)`                                                 |
-| `count` (Array)                 | `string[]`        | Counts unique combinations across multiple columns (COUNT DISTINCT).                                 | `{ count: ['team', 'source'] }` $\rightarrow$ `COUNT( DISTINCT` \`team\``,` \`source\``)`          |
-| `count` (Object)                | `Object`          | Automated conditional aggregation (`CASE WHEN`). Perfect for KPIs and status metrics.                | `{ count: { deletedAt: null } }` $\rightarrow$ `COUNT(CASE WHEN` \`deletedAt\``= NULL THEN 1 END)` |
-| `as`                            | `string`          | Sets a custom output identifier or aggregation alias (SQL `AS`).                                     | `{ count: 'id', as: 'total' }` $\rightarrow$ `COUNT(` \`id\``) AS` \`total\`                       |
+```js
+{
+  status: {
+    IN: ['active', 'pending'],
+  },
+}
+```
+
+Values are parameterized individually.
 
-### Advanced `groupBy` Options (`GroupAggregation`)
+```js
+{
+  status: {
+    'NOT IN': ['deleted', 'blocked'],
+  },
+}
+```
 
-The `groupBy` option accepts an array that can mix standard strings (raw column names) and advanced configuration objects for secure and parameterized grouping:
+Use arrays for these operators. An empty list is not a meaningful SQL `IN` expression and should not be passed.
 
-|    object    | Type               | Description                                                                                       | Example / Generated SQL                                                        |
-|--------------|--------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------|
-| `col`        | `string`           | Safely targets an unaggregated table column using structural object isolation.                    | { col: 'role' } -> `role`                                                      |
-| `dateFormat` | `[string, string]` | Securely groups by a formatted Date column using parameterized inputs (Format: [column, format]). | { dateFormat: ['created_at', '%Y-%m'] } -> DATE_FORMAT( `created_at`, '%Y-%m') |
-| `as`         | `string`           | Targets the specified select alias directly to comply with strict MySQL group structures.         | `{ col: 'role', as: 'user_role' }` ->\`user_role\`                             |
+### `BETWEEN` / `NOT BETWEEN`
 
----
+```js
+{
+  created_at: {
+    BETWEEN: [
+      new Date('2026-01-01'),
+      new Date('2026-12-31'),
+    ],
+  },
+}
+```
+
+The value must contain exactly two bounds: `[min, max]`.
+
+### `NULL`
 
-### Complex Structured Options (`orderBy` & `join`)
+A plain `null` value is translated to `IS NULL`:
 
-#### OrderByOption
+```js
+{ deleted_at: null }
+```
 
-Enables explicit sorting across one or multiple columns:
+Explicit equality and inequality with `null` are normalized as well:
 
-- **field** `(string)`: The target column name to apply sorting on.
-- **direction** `('ASC'\|'DESC')`: The sorting direction (Defaults to `'ASC'`).
+```js
+{ deleted_at: { '=': null } }
+{ deleted_at: { '!=': null } }
+```
 
-#### JoinOption
+These become `IS NULL` and `IS NOT NULL`; no placeholder is consumed for the `NULL` literal.
 
-Specifies one or multiple relational database table joins:
+### `AND` / `OR` / `NOT`
 
-- **table** `(string)`: Target table name to join with.
-- **on** `(string)`: Relational equation statement string (e.g., `"ProjectPipelines.project_id = Projects.id"`).
-- **alias** `(string)` *(Optional)*: An alternative SQL alias name for the joined table.
-- **type** `('INNER'\|'LEFT'\|'RIGHT')` *(Optional)*: SQL join modality (Defaults to `'INNER'`).
+Nested conditions are supported:
 
----
+```js
+{
+  AND: [
+    { active: true },
+    {
+      OR: [
+        { role: 'admin' },
+        { role: 'moderator' },
+      ],
+    },
+  ],
+}
+```
 
-## Example find
+Negation accepts one structured condition object:
 
 ```js
-const User = require("user");
+{
+  NOT: {
+    status: { IN: ['deleted', 'blocked'] },
+  },
+}
+```
+
+Empty `AND` / `OR` arrays and invalid `NOT` values are rejected.
+
+---
+
+## Select, aggregation, grouping and ordering
+
+### Select items
 
-User.find({
+A `select` entry can be a column string or a structured object.
+
+| Form | Meaning |
+|---|---|
+| `'email'` | Select a column. |
+| `'*'` | Select all columns. |
+| `{ col: 'email', as: 'address' }` | Column with alias. |
+| `{ sum: 'amount', as: 'total' }` | `SUM(amount)`. |
+| `{ count: 'id', as: 'total' }` | `COUNT(id)`. |
+| `{ count: ['team', 'source'], as: 'groups' }` | Multi-column count expression. |
+| `{ count: { status: 'active' }, as: 'active' }` | Conditional count expression. |
+| `{ distinct: 'status' }` | `DISTINCT status`. |
+| `{ dateFormat: ['created_at', '%Y-%m'], as: 'period' }` | Formatted date expression. |
+
+Example de sélection et d'agrégation :
+
+```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` s'utilise directement dans les options de `find()`. Il doit correspondre aux colonnes ou expressions qui définissent chaque groupe.
 
-User.find({
+```js
+const stats = await User.find({
   select: [
-    "email"
+    'status',
+    { count: 'id', as: 'total' },
+    { sum: 'amount', as: 'revenue' },
   ],
-  where: {
-    id: 1
-  }
-})
+  groupBy: ['status'],
+});
 ```
 
-### Advanced Examples using `find`
+Un élément de `groupBy` peut être une colonne (`'status'`) ou une expression structurée telle que `dateFormat`.
 
-#### 1. Standard, Distinct, and Multi-Column Counting
+### Filtrer les groupes avec `HAVING`
 
-Count global rows alongside multi-column unique combinations, such as identifying unique team and source pipelines:
+`having` s'applique **après** le groupement et utilise exactement le même format de conditions structurées que `where`. Par exemple, pour conserver uniquement les groupes contenant plus de 10 lignes :
 
 ```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' } // Multi-column COUNT DISTINCT
+    'status',
+    { count: 'id', as: 'total' },
   ],
-  where: { csource: 'web' }
+  groupBy: ['status'],
+  having: {
+    total: { '>': 10 },
+  },
 });
 ```
 
-#### 2. Conditional Aggregations (Active / Decommissioned KPI Metrics)
+Les chaînes SQL brutes dans `having` sont refusées par le query builder.
 
-By passing an object to the `count` attribute, the ORM automatically structures a conditional `CASE WHEN` clause. This allows you to split different status counters into a single database trip:
+### Tri avec `ORDER BY`
 
-```js
-const { MyTable } = require("./models");
+`orderBy` s'ajoute aux mêmes options et permet de trier le résultat final. Il peut notamment trier sur une colonne sélectionnée ou sur un alias d'agrégation :
 
-const ppiStats = await MyTable.find({
+```js
+const stats = await User.find({
   select: [
-    { count: { deletedAt: null }, as: 'active' },          // Counts where deletedAt = NULL
-    { count: { status: 'SUCCESS' }, as: 'total_success' }   // Counts where 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. Table Joins, Mixed-Type Time Series Grouping, and Multi-Column Sorting
+Seules les directions `ASC` et `DESC` sont acceptées.
 
-An advanced query orchestration combining left table joining, date formatting conversions, and sorting:
+### Exemple complet : `SELECT` + agrégation + `WHERE` + `GROUP BY` + `HAVING` + `ORDER BY`
 
-```js
-const { MyTable } = require("./models");
+L'exemple suivant montre comment toutes ces clauses se combinent dans une seule requête :
 
-const history = await MyTable.find({
+```js
+const stats = await User.find({
   select: [
-    { col: 'Projects.name', as: 'project_name' },
-    { dateFormat: ['ProjectPipelines.created_at', '%Y-%m'], as: 'period' },
-    { count: 'ProjectPipelines.id', as: 'pipelines_count' }
+    'status',
+    { count: 'id', as: 'total' },
+    { sum: 'amount', as: 'revenue' },
   ],
   where: {
-    status: 'ACTIVE'
+    active: true,
   },
-  join: {
-    table: 'Projects',
-    on: 'ProjectPipelines.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' },
+  ],
+});
+```
+
+Conceptuellement, cette configuration correspond à :
+
+```sql
+SELECT status, COUNT(id) AS total, SUM(amount) AS revenue
+FROM users
+WHERE active = ?
+GROUP BY status
+HAVING total > ?
+ORDER BY total DESC
+```
+
+Les valeurs de `WHERE` et `HAVING` restent paramétrées par le Connector.
+
+---
+
+## Joins
+
+The current model API exposes an `INNER JOIN` configuration through `find`:
+
+```js
+const rows = await User.find({
+  select: [
+    { col: 'users.email', as: 'email' },
+    { col: 'profiles.display_name', as: 'name' },
   ],
-  limit: 50
+  join: {
+    table: 'profiles',
+    on: 'users.id = profiles.user_id',
+  },
 });
 ```
 
-## count function
+The query builder also documents `JoinOption` shapes with `alias` and `type`; however, the current `Model.find()` implementation builds the join from `table` and `on` and emits `INNER JOIN`. Do not rely on `LEFT` / `RIGHT` behavior until the model layer exposes those options end-to-end.
 
-Counts the number of records matching the given filter.
+---
 
-- **Parameters** `filter` *(Object)* The filter criteria for the query. Should be an object where keys are column names and values are the values to filter by.
-- **Returns** `Promise<ModelInstance|number>` - A promise that resolves to a `ModelInstance` if a record is found, or `0` if no records match the filter.
+## Schema synchronization
 
-## Example count
+`Model.syncAllTables()` creates model tables in foreign-key dependency order.
 
 ```js
-const User = require("user");
+await Model.syncAllTables();
+```
+
+It handles:
+
+- table creation;
+- multiple foreign keys;
+- dependency ordering;
+- cyclic dependency detection.
+
+For controlled schema evolution, prefer the migration API described below.
+
+---
+
+## Migrations
+
+The migration subsystem compares the **desired schema from your models** with the **actual database schema**, creates a migration plan, and can execute the resulting DDL.
 
-User.count({
-  id: id
-})
+Migration components are exposed from the package root:
+
+```js
+const {
+  Migration,
+  MigrationPlan,
+  MigrationStore,
+  MigrationRunner,
+  SchemaDiffer,
+  SchemaInspector,
+  MySQLDialect,
+  PostgreSQLDialect,
+  MigrationError,
+  DestructiveMigrationError,
+  MigrationChecksumError,
+} = require('@mlagie/sql-connector');
 ```
 
-## customRequest function
+### Migration workflow
+
+The recommended workflow is:
+
+```text
+Model schemas
+    │
+    ▼
+Migration.plan()
+    │
+    ├── inspect current database
+    ├── build desired snapshot
+    ├── calculate schema differences
+    └── generate dialect-specific SQL
+    │
+    ▼
+MigrationPlan
+    │
+    ├── inspect changes
+    ├── approve()
+    └── execute()
+    │
+    ▼
+Database + migration history + snapshot
+```
+
+Basic usage:
+
+```js
+const migration = new Migration({
+  encryptionKey: process.env.SQL_CONNECTOR_MIGRATION_KEY,
+});
+
+const plan = await migration.plan({
+  name: 'users-schema',
+});
+
+console.log(plan.toJSON());
+
+if (plan.hasChanges()) {
+  plan.approve();
+  await plan.execute();
+}
+```
+
+Or use the convenience method:
+
+```js
+await Migration.migrate({
+  name: 'users-schema',
+  encryptionKey: process.env.SQL_CONNECTOR_MIGRATION_KEY,
+});
+```
+
+### Migration options
 
-The customRequest function allows you to execute SQL queries that are not supported by sql-connector; this could be in queries where the keywords are not yet implemented.
+`Migration` accepts:
 
-- **Parameters** `custom` *(string)*  The custom SQL_request query to execute.
-- **Returns** `Promise<void>` A promise that resolves when the query is executed.
-- **Throws** `Error` Throws an error if query execution fails.
+| Option | Type | Description |
+|---|---|---|
+| `connection` | driver connection | Existing database connection. Defaults to the active connector connection. |
+| `dialect` | `'mysql' \| 'postgres'` / dialect instance | Database dialect. Defaults to the active connector dialect. |
+| `models` | `Model[]` | Explicit models to compare. Defaults to pending models. |
+| `directory` | `string` | Migration storage directory. Default: `migrations`. |
+| `backupDirectory` | `string` | Encrypted backup directory. |
+| `encryptionKey` | `string` | Secret used for migration and backup encryption. |
+| `retention` | number / duration string | Backup retention. Supports `ms`, `s`, `m`, `h`, `d`, `w`. |
+| `allowDestructiveChanges` | `boolean` | Allows column drops. |
+| `allowDropTables` | `boolean` | Allows table drops. |
 
-## Example customRequest
+Examples:
 
 ```js
-const User = require("user");
+new Migration({
+  directory: './database/migrations',
+  backupDirectory: './database/backups',
+  encryptionKey: process.env.SQL_CONNECTOR_MIGRATION_KEY,
+  retention: '30d',
+});
+```
+
+### Migration plans
 
-User.customRequest("SELECT id, email, status
-  FROM users
-  WHERE status IN ('active', 'pending')
-  AND email LIKE '%gmail.com';")
+`Migration.plan()` returns a `MigrationPlan`.
+
+```js
+const plan = await migration.plan({
+  id: '20260915_add_status',
+  name: 'add status',
+});
 ```
 
-## delete function
+Available methods:
+
+| Method | Description |
+|---|---|
+| `hasChanges()` | Returns whether operations are pending. |
+| `hasDestructiveChanges()` | Returns whether destructive operations are present. |
+| `destructiveChanges()` | Returns destructive operations. |
+| `approve()` | Marks the plan as approved. |
+| `execute(options)` | Executes the attached plan. |
+| `toJSON()` | Returns a serializable plan representation. |
+
+A plan exposes:
+
+- `id`;
+- `dialect`;
+- `checksum`;
+- `operations`;
+- generated `sql`;
+- desired `snapshot`;
+- previous/current baseline snapshot.
 
-Deletes an entry from the SQL table that matches the provided filter.
+### Detected migration operations
 
-- **Parameters** `filter` *(Object)* An object representing the filter conditions for deletion.
-- **Returns** `Promise<number>` A promise that resolves to 0 if no rows were deleted, * or to a ModelInstance representing the deleted row.
-- **Throws** `Error` Throws an error if the SQL query fails.
+The schema differ can generate:
 
-## Example delete
+| Operation | Meaning | Destructive |
+|---|---|---:|
+| `createTable` | Creates a missing table. | No |
+| `addColumn` | Adds a missing column. | No |
+| `renameColumn` | Renames a column declared with `oldname`. | No |
+| `alterColumn` | Changes a column definition. | No |
+| `dropColumn` | Removes a column absent from the desired schema. | Yes |
+| `dropTable` | Removes a table absent from the desired schema. | Yes |
+
+Renames are explicit. The differ does not guess that two similarly named columns are the same column.
+
+Example:
 
 ```js
-const User = require("user");
+const schema = new Schema({
+  email_address: {
+    type: String,
+    length: 320,
+    oldname: 'email',
+  },
+});
+```
 
-User.delete({
-  email: my@gmail.com
-})
+This can produce a `renameColumn` operation from `email` to `email_address`, followed by an `alterColumn` if the definition also changed.
+
+### Destructive changes
+
+Column and table removal require explicit authorization.
+
+```js
+const plan = await migration.plan({
+  allowDestructiveChanges: true,
+  allowDropTables: true,
+});
+
+if (plan.hasDestructiveChanges()) {
+  console.warn(plan.destructiveChanges());
+}
+
+plan.approve();
+await plan.execute({
+  allowDestructiveChanges: true,
+});
 ```
 
-## dropTable function
+Approval and destructive-change authorization are separate safeguards.
+
+### Checksums
 
-Asynchronously drops a table if it exists in the database.
+Every generated migration receives a SHA-256 checksum derived from its migration id, dialect, operations and generated SQL.
 
-This function constructs a SQL_request query to drop a table with the name specified by the `this.name` property. It then executes the query using a promise-based approach.
-If the query is successful, the result is logged to the console.
-If an error occurs during the execution of the query, an error message is logged.
+The migration history table is named `sql_connector_migrations`.
 
-- **Returns** `Promise<void>` A promise that resolves when the query execution is complete.
+If an already-applied migration id is found with a different checksum, execution stops instead of silently accepting the mismatch.
 
-## Example dropTable
+### Encrypted files
+
+Migration SQL is stored as encrypted `.sql.enc` files.
+
+Set the key through the constructor:
 
 ```js
-const User = require("user");
+const migration = new Migration({
+  encryptionKey: process.env.SQL_CONNECTOR_MIGRATION_KEY,
+});
+```
+
+Or through the environment:
 
-User.dropTable();
+```bash
+export SQL_CONNECTOR_MIGRATION_KEY='a-long-random-secret'
 ```
 
-## generate_uuid function
+The encryption format uses AES-256-GCM with a derived key. Migration files are written with restrictive filesystem permissions.
 
-Generates a unique UUID for the current model.
-This function generates a UUID using the SQL_request `UUID()` function and checks if the generated UUID already exists in the database for the current model. If the UUID is unique, it is returned.
-Otherwise, the function resolves to `null`.
+> Never commit `SQL_CONNECTOR_MIGRATION_KEY` or plaintext secrets to source control.
 
-- **Parameters** `string` var_uuid By default, it is set to uuid.
-- **Returns** `Promise<string|null>` A promise that resolves to a unique UUID string if successful, or `null` if an error occurs or the UUID is not unique.
-- **Throws** `Error` If there is an error executing the SQL_request query.
+### Backups and retention
 
-## Example generate_uuid
+If `retention` is configured, affected tables are backed up before migration execution and written as encrypted JSON files.
 
 ```js
-const User = require("user");
+const migration = new Migration({
+  encryptionKey: process.env.SQL_CONNECTOR_MIGRATION_KEY,
+  retention: '30d',
+});
+```
 
-const uuid = await User.generate_uuid();
-const my_uuid = await User.generate_uuid("my_uuid");
+Accepted duration units:
+
+- `ms`: millisecond
+- `s`: seconde
+- `m`: minute
+- `h`: heure
+- `d`: jour
+- `w`: semaine
+
+`Migration.cleanup()` removes expired backup files.
 
-await User.save({ email: "user@example.com", status: "active", uuid: uuid, my_uuid: my_uuid })
+Backups are currently data-oriented snapshots. The connector does not automatically restore them.
+
+### Migration status
+
+```js
+const migration = new Migration();
+const status = await migration.status();
+console.table(status);
 ```
 
-## Model instances
+The migration runner maintains the database-side history table and can also inspect the stored migration files.
+
+---
 
-`ModelInstance` represents a row already loaded from the database.
+## Model instances
 
-- `updateOne(model)` updates the row
-- `delete(model)` deletes the row using a filter
-- `delete()` deletes the instance row
-- `customRequest(custom)` runs a custom query
+Queries return `ModelInstance` objects.
 
 ```js
-const userInstance = await find({ select: "users", where: { email: 'user@example.com' }})[0];
+const [user] = await User.find({
+  where: { email: 'user@example.com' },
+});
+
+await user.updateOne({ status: 'inactive' });
+await user.delete();
+```
 
-await userInstance.updateOne({ status: 'inactive' });
-await userInstance.delete();
+Available methods include:
+
+- `updateOne(data)`;
+- `delete(filter?)`;
+- `customRequest(sql)`;
+- `getRecordData()`;
+- `toJSON()`.
+
+When a model schema contains primary-key fields, `updateOne()` uses those primary-key values to target the row when possible.
+
+---
+
+## TypeScript
+
+The package ships `index.d.ts` declarations.
+
+```ts
+import {
+  Schema,
+  Model,
+  Migration,
+  InferSchema,
+} from '@mlagie/sql-connector';
+
+const schema = new Schema({
+  id: {
+    type: Number,
+    primary_key: true,
+  },
+  email: {
+    type: String,
+    required: true,
+  },
+});
+
+type User = InferSchema<typeof schema.schemaDict>;
 ```
 
-## SQL types
+The declarations cover schema definitions, inferred model records, query conditions, select items and migration classes.
+
+---
+
+## Security and SQL safety
+
+The structured query builder is designed to keep identifiers and values separate.
+
+- `WHERE` values are parameterized.
+- `HAVING` values are parameterized.
+- `IN` / `NOT IN` values are parameterized individually.
+- `BETWEEN` bounds are parameterized individually.
+- PostgreSQL placeholders are generated as `$1`, `$2`, etc.
+- MySQL uses `?` placeholders.
+- Identifiers are validated before dialect-specific escaping.
+- Raw `WHERE` / `HAVING` strings are rejected by the structured builder.
+
+`customRequest()` is intentionally outside that protection because it accepts raw SQL. Use it only with trusted query text.
+
+---
+
+## Dialect matrix
 
-`sqlTypeMap` exposes the common SQL types.
+| Feature | MySQL | PostgreSQL |
+|---|---|---|
+| Connection driver | `mysql2` | `pg` |
+| Identifier quotes | backticks | double quotes |
+| Parameter placeholders | `?` | `$1`, `$2`, ... |
+| Boolean SQL literals | `1` / `0` | `TRUE` / `FALSE` |
+| UUID query | `UUID()` | `gen_random_uuid()` |
+| Transactional DDL | engine-dependent | supported by migration dialect |
 
-```javascript
-console.log(sqlTypeMap.String); // "VARCHAR"
+The migration dialect layer is separate from the query dialect layer so schema DDL and runtime queries can evolve independently.
+
+---
+
+## API exports
+
+The package root exports:
+
+```js
+{
+  client,
+  connect,
+  logout,
+  Schema,
+  Model,
+  ModelInstance,
+  sqlTypeMap,
+  Migration,
+  MigrationPlan,
+  MigrationStore,
+  MigrationRunner,
+  SchemaDiffer,
+  SchemaInspector,
+  MySQLDialect,
+  PostgreSQLDialect,
+  MigrationError,
+  DestructiveMigrationError,
+  MigrationChecksumError,
+}
+```
+
+For implementation-level utilities, see the source tree under `src/`.
+
+---
+
+## Testing
+
+Install dependencies and run:
+
+```bash
+npm install
+npm test
 ```
 
-## Client
+Coverage:
 
-`client` is a shared object meant to host reusable application functions.
+```bash
+npm run test:coverage
+```
 
-```javascript
-module.exports = client => {
-  client.checkServer = () => {
-    if (server.isLaunch()) {
-      return 1;
-    }
+Security/lint checks:
 
-    return 0;
-  };
-};
+```bash
+npm run security
 ```
 
-## Summary
+The migration and query behavior is covered by the test suite, including schema differences, destructive-change protection, condition building, null handling, dialect-specific placeholders and encryption utilities.
+
+---
+
+## Related documentation
+
+- [Documentation index](./docs/README.md)
+- [Schema reference](./docs/SCHEMA.md)
+- [Conditions and query reference](./docs/QUERY.md)
+- [Migration reference](./docs/MIGRATIONS.md)
+- [API reference](./docs/API.md)
+- [Dialect reference](./docs/DIALECTS.md)
+- [French README](./docs/fr/README_FR.md)
+- [Contributing](./CONTRIBUTING.md)
+- [Security policy](./SECURITY.md)
+- [Changelog](./CHANGELOG.md)
+
+## License
 
-sql-connector provides a small layer to connect to MySQL, describe schemas, synchronize tables, and manipulate data with typed models.
+MIT — see [LICENSE](./LICENSE).