@mlagie/sql-connector 3.0.3 → 3.1.0

package/docs/API.md

@@ -0,0 +1,240 @@
+# API reference
+
+## Table of contents
+
+1. [Root exports](#root-exports)
+2. [Connection](#connection)
+3. [Schema](#schema)
+4. [Model](#model)
+5. [ModelInstance](#modelinstance)
+6. [Migration](#migration)
+7. [MigrationPlan](#migrationplan)
+8. [MigrationStore](#migrationstore)
+9. [MigrationRunner](#migrationrunner)
+10. [SchemaDiffer](#schemadiffer)
+11. [SchemaInspector](#schemainspector)
+12. [Dialect classes](#dialect-classes)
+
+## Root exports
+
+```js
+const api = require('@mlagie/sql-connector');
+```
+
+Exports:
+
+```text
+client
+connect
+logout
+Schema
+Model
+ModelInstance
+sqlTypeMap
+Migration
+MigrationPlan
+MigrationStore
+MigrationRunner
+SchemaDiffer
+SchemaInspector
+MySQLDialect
+PostgreSQLDialect
+MigrationError
+DestructiveMigrationError
+MigrationChecksumError
+```
+
+## Connection
+
+### `connect(config, dialect?)`
+
+Connects to MySQL by default or PostgreSQL when `dialect` is `postgres`.
+
+### `logout()`
+
+Closes the active connector connection.
+
+## Schema
+
+### `new Schema(schemaDict)`
+
+Stores a declarative table schema.
+
+Property:
+
+- `schemaDict` — field definitions.
+
+## Model
+
+### `new Model(name, schema)`
+
+Creates a model for a table.
+
+### `Model.syncAllTables()`
+
+Creates all pending model tables in dependency order.
+
+### `model.save(data)`
+
+Inserts a row.
+
+### `model.find(options?)`
+
+Returns `ModelInstance[]` using structured filters and query options.
+
+### `model.count(filter?)`
+
+Returns the number of matching rows.
+
+### `model.delete(filter)`
+
+Deletes matching rows and returns the affected-row status used by the model API.
+
+### `model.dropTable()`
+
+Drops the model table.
+
+### `model.generate_uuid(column?)`
+
+Generates a unique UUID for a column, defaulting to `uuid`.
+
+### `model.customRequest(sql)`
+
+Executes trusted raw SQL.
+
+## ModelInstance
+
+### `instance.updateOne(data)`
+
+Updates the loaded row, preferring primary-key fields from its schema when available.
+
+### `instance.delete(filter?)`
+
+Deletes the current row or the supplied filter.
+
+### `instance.customRequest(sql)`
+
+Executes trusted raw SQL and wraps returned data.
+
+### `instance.getRecordData()`
+
+Returns the underlying record data.
+
+### `instance.toJSON()`
+
+Returns record data for JSON serialization.
+
+## Migration
+
+### `new Migration(options?)`
+
+Options include:
+
+- `connection`;
+- `dialect`;
+- `models`;
+- `directory`;
+- `backupDirectory`;
+- `encryptionKey`;
+- `retention`;
+- `allowDestructiveChanges`;
+- `allowDropTables`.
+
+Methods:
+
+- `plan(options?)`;
+- `migrate(options?)`;
+- `status()`;
+- `cleanup()`.
+
+Static methods:
+
+- `Migration.plan(options?)`;
+- `Migration.migrate(options?)`;
+- `Migration.status(options?)`.
+
+## MigrationPlan
+
+Properties:
+
+- `id`;
+- `operations`;
+- `sql`;
+- `snapshot`;
+- `previousSnapshot`;
+- `dialect`;
+- `checksum`;
+- `approved`.
+
+Methods:
+
+- `hasChanges()`;
+- `hasDestructiveChanges()`;
+- `destructiveChanges()`;
+- `approve()`;
+- `execute(options?)`;
+- `toJSON()`.
+
+## MigrationStore
+
+Constructor options:
+
+- `directory`;
+- `backupDirectory`;
+- `encryptionKey`;
+- `retention`.
+
+Methods:
+
+- `ensureDirectories()`;
+- `writeMigration(plan)`;
+- `writeBackup(name, content)`;
+- `cleanup()`;
+- `writeSnapshot(snapshot)`;
+- `readSnapshot()`;
+- `listMigrationFiles()`;
+- `validateChecksum(actual, expected)`.
+
+## MigrationRunner
+
+Methods:
+
+- `ensureMigrationTable()`;
+- `applied()`;
+- `execute(plan, options?)`;
+- `sqlForOperation(operation)`.
+
+## SchemaDiffer
+
+Constructor options:
+
+- `allowDestructiveChanges`;
+- `allowDropTables`.
+
+### `diff(desired, current)`
+
+Returns migration operations.
+
+## SchemaInspector
+
+### `inspect()`
+
+Returns the normalized database schema snapshot used by the migration planner.
+
+## Migration errors
+
+### `MigrationError`
+
+Base migration error with a `code` and optional `details`.
+
+### `DestructiveMigrationError`
+
+Raised when a destructive schema operation is not explicitly authorized.
+
+### `MigrationChecksumError`
+
+Raised when a migration checksum does not match the expected value.
+
+## Dialect classes
+
+`MySQLDialect` and `PostgreSQLDialect` implement migration-specific SQL generation and introspection.

package/docs/DIALECTS.md

@@ -0,0 +1,56 @@
+# SQL dialect reference
+
+## Table of contents
+
+1. [Supported dialects](#supported-dialects)
+2. [Runtime query behavior](#runtime-query-behavior)
+3. [Migration DDL](#migration-ddl)
+4. [MySQL](#mysql)
+5. [PostgreSQL](#postgresql)
+
+## Supported dialects
+
+The connector supports:
+
+- `mysql`;
+- `postgres`.
+
+MySQL is the default runtime dialect.
+
+## Runtime query behavior
+
+| Behavior | MySQL | PostgreSQL |
+|---|---|---|
+| Identifier quote | `` `name` `` | `"name"` |
+| Parameter | `?` | `$1`, `$2`, ... |
+| Boolean literal | `1` / `0` | `TRUE` / `FALSE` |
+| UUID generation | `UUID()` | `gen_random_uuid()` |
+
+The query layer tracks placeholder indexes so conditions such as `IN`, `BETWEEN`, `LIMIT` and `OFFSET` remain valid for PostgreSQL.
+
+## Migration DDL
+
+The migration subsystem uses dedicated dialect classes because schema DDL requires different SQL on MySQL and PostgreSQL.
+
+Migration-specific responsibilities include:
+
+- type mapping;
+- column definitions;
+- table creation;
+- adding, renaming, altering and dropping columns;
+- table removal;
+- schema introspection;
+- migration-history storage;
+- transactional DDL behavior.
+
+## MySQL
+
+The runtime uses `mysql2`.
+
+The migration dialect creates the migration history table with `DATETIME` timestamps and uses InnoDB table options for generated tables.
+
+## PostgreSQL
+
+The runtime uses `pg`.
+
+The migration dialect uses PostgreSQL identity syntax for auto-incrementing integer fields and `TIMESTAMPTZ` for migration-history timestamps.

package/docs/MIGRATIONS.md

@@ -0,0 +1,277 @@
+# Migration reference
+
+## Table of contents
+
+1. [Purpose](#purpose)
+2. [Prerequisites](#prerequisites)
+3. [Planning](#planning)
+4. [Executing](#executing)
+5. [Migration options](#migration-options)
+6. [Operations](#operations)
+7. [Renames](#renames)
+8. [Destructive changes](#destructive-changes)
+9. [Checksums and history](#checksums-and-history)
+10. [Encrypted migration files](#encrypted-migration-files)
+11. [Backups](#backups)
+12. [Status and cleanup](#status-and-cleanup)
+13. [Migration classes](#migration-classes)
+
+## Purpose
+
+The migration subsystem turns model schemas into controlled database schema changes.
+
+It compares:
+
+- the desired schema derived from `Model` objects;
+- the schema currently reported by the active database dialect.
+
+It then creates explicit operations and dialect-specific SQL.
+
+## Prerequisites
+
+Connect before constructing a migration unless an explicit connection is supplied:
+
+```js
+await connect(config, 'postgres');
+const migration = new Migration();
+```
+
+For writing migration files, provide an encryption key through `encryptionKey` or `SQL_CONNECTOR_MIGRATION_KEY`.
+
+## Planning
+
+```js
+const plan = await Migration.plan({
+  name: 'users-schema',
+});
+```
+
+The plan contains:
+
+- `id`;
+- `dialect`;
+- `checksum`;
+- `operations`;
+- generated `sql`;
+- desired snapshot;
+- baseline snapshot.
+
+Inspect it before execution:
+
+```js
+console.log(plan.toJSON());
+console.log(plan.sql);
+```
+
+## Executing
+
+Approval is required by default:
+
+```js
+const plan = await Migration.plan({ name: 'users-schema' });
+
+if (plan.hasChanges()) {
+  plan.approve();
+  await plan.execute();
+}
+```
+
+Or:
+
+```js
+await Migration.migrate({
+  name: 'users-schema',
+});
+```
+
+`Migration.migrate()` approves a changed plan by default and then executes it with the runner's approval checks enabled.
+
+## Migration options
+
+```js
+new Migration({
+  connection,
+  dialect: 'mysql',
+  models,
+  directory: './migrations',
+  backupDirectory: './migrations/backups',
+  encryptionKey: process.env.SQL_CONNECTOR_MIGRATION_KEY,
+  retention: '30d',
+  allowDestructiveChanges: false,
+  allowDropTables: false,
+});
+```
+
+`retention` accepts milliseconds as a number or strings using `ms`, `s`, `m`, `h`, `d` and `w`.
+
+## Operations
+
+The differ can generate:
+
+- `createTable`;
+- `addColumn`;
+- `renameColumn`;
+- `alterColumn`;
+- `dropColumn`;
+- `dropTable`.
+
+The first four are non-destructive in the differ's classification. `dropColumn` and `dropTable` are destructive.
+
+## Renames
+
+Declare a rename explicitly:
+
+```js
+const schema = new Schema({
+  email_address: {
+    type: String,
+    length: 320,
+    oldname: 'email',
+  },
+});
+```
+
+The differ checks that the old column exists and that the new name is not already occupied.
+
+## Destructive changes
+
+By default:
+
+- dropping a column throws `DestructiveMigrationError`;
+- dropping a table throws `DestructiveMigrationError`.
+
+Allow them explicitly during planning and execution:
+
+```js
+const plan = await migration.plan({
+  allowDestructiveChanges: true,
+  allowDropTables: true,
+});
+
+plan.approve();
+
+await plan.execute({
+  allowDestructiveChanges: true,
+});
+```
+
+Use these options deliberately in production workflows.
+
+## Checksums and history
+
+The runner creates `sql_connector_migrations` in the active database.
+
+Each applied migration stores:
+
+- migration id;
+- SHA-256 checksum;
+- applied timestamp;
+- creation timestamp.
+
+If an id already exists with a different checksum, execution fails rather than changing migration history silently.
+
+## Encrypted migration files
+
+After a successful migration, the desired schema snapshot is also persisted as `schema.snapshot.json`. Applied plans are written as encrypted files named:
+
+```text
+<directory>/<migration-id>.sql.enc
+```
+
+The encryption key is required to write these files.
+
+```bash
+export SQL_CONNECTOR_MIGRATION_KEY='a-long-random-secret'
+```
+
+The encryption implementation uses AES-256-GCM and a derived key.
+
+## Backups
+
+If retention is enabled, affected tables are selected before execution and stored as encrypted JSON:
+
+```text
+<backupDirectory>/<migration-id>.json.enc
+```
+
+```js
+const migration = new Migration({
+  encryptionKey: process.env.SQL_CONNECTOR_MIGRATION_KEY,
+  retention: '30d',
+});
+```
+
+Backups are data snapshots, not automatic rollback scripts. Restoration must be handled separately.
+
+## Status and cleanup
+
+```js
+const migration = new Migration();
+const status = await migration.status();
+console.table(status);
+
+await migration.cleanup();
+```
+
+`cleanup()` removes backup files older than the configured retention period.
+
+## Migration classes
+
+### `Migration`
+
+High-level API for planning, applying, checking status and cleaning backups.
+
+Methods:
+
+- `plan(options)`;
+- `migrate(options)`;
+- `status()`;
+- `cleanup()`.
+
+Static equivalents:
+
+- `Migration.plan(options)`;
+- `Migration.migrate(options)`;
+- `Migration.status(options)`.
+
+### `MigrationPlan`
+
+Methods:
+
+- `hasChanges()`;
+- `hasDestructiveChanges()`;
+- `destructiveChanges()`;
+- `approve()`;
+- `execute(options)`;
+- `toJSON()`.
+
+### `MigrationStore`
+
+Manages:
+
+- migration directory;
+- backup directory;
+- encrypted migration files;
+- encrypted backups;
+- schema snapshot;
+- retention cleanup;
+- checksum validation.
+
+### `MigrationRunner`
+
+Responsible for:
+
+- migration history table;
+- operation execution;
+- transaction handling through the dialect;
+- checksum consistency;
+- backup creation;
+- persisted migration state.
+
+### `SchemaDiffer`
+
+Compares desired and current snapshots and produces migration operations.
+
+### `SchemaInspector`
+
+Reads the active database schema through dialect-specific information-schema queries.