@mlagie/sql-connector 3.0.3 → 3.1.0

package/index.js

@@ -1,9 +1,39 @@
-const { Model } = require("./src/models/Model");
-const { ModelInstance } = require("./src/models/ModelInstance");
-const { connect, logout } = require("./src/db/connect");
-const {Schema} = require("./src/models/Schema");
-const { sqlTypeMap } = require("./src/utils/sqlTypeMap");
-
-let client = {};
-
-module.exports = { client, connect, logout, Schema, Model, ModelInstance, sqlTypeMap }
+const { Model } = require("./src/models/Model");
+const { ModelInstance } = require("./src/models/ModelInstance");
+const { connect, logout } = require("./src/db/connect");
+const {Schema} = require("./src/models/Schema");
+const { sqlTypeMap } = require("./src/utils/sqlTypeMap");
+const {
+    Migration,
+    MigrationPlan,
+    MigrationStore,
+    MigrationRunner,
+    SchemaDiffer,
+    SchemaInspector,
+    MySQLDialect,
+    PostgreSQLDialect
+} = require("./src/migration");
+const { MigrationError, DestructiveMigrationError, MigrationChecksumError } = require("./src/migration/errors");
+
+let client = {};
+
+module.exports = {
+    client,
+    connect,
+    logout,
+    Schema,
+    Model,
+    ModelInstance,
+    sqlTypeMap,
+    Migration,
+    MigrationPlan,
+    MigrationStore,
+    MigrationRunner,
+    SchemaDiffer,
+    SchemaInspector,
+    MySQLDialect,
+    PostgreSQLDialect,
+    MigrationError,
+    DestructiveMigrationError,
+    MigrationChecksumError
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlagie/sql-connector",
-  "version": "3.0.3",
+  "version": "3.1.0",
   "description": "The sql-connector module allows you to manage connections to a MySQL database, define table schemas, and interact with data in a simple and efficient way.",
   "main": "index.js",
   "exports": {
@@ -20,7 +20,7 @@
     "test": "rm -r coverage ; node --experimental-vm-modules node_modules/jest/bin/jest.js --runInBand",
     "test:publish": "npm publish --dry-run",
     "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
-    "test:coverage": "rm -r coverage ; node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+    "test:coverage": "rm -r coverage ; node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage && ./scripts/coverage-report.sh",
     "coverage:report": "./scripts/coverage-report.sh",
     "security": "npx eslint . --max-warnings 0 --ignore-pattern './tests/*'"
   },
@@ -66,14 +66,14 @@
   "private": false,
   "dependencies": {
     "@mlagie/logger": "1.0.5",
-    "mysql2": "3.23.3",
+    "mysql2": "3.24.4",
     "pg": "^8.23.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "eslint": "^10.8.1",
+    "eslint": "^10.10.0",
     "eslint-plugin-security": "^4.0.1",
-    "jest": "30.4.2"
+    "jest": "30.5.1"
   },
   "overrides": {
     "test-exclude": "^8.0.0",
@@ -82,6 +82,7 @@
     "brace-expansion": "^5.0.9"
   },
   "allowScripts": {
-    "unrs-resolver@1.12.2": true
+    "unrs-resolver@1.12.2": true,
+    "@parcel/watcher@2.6.0": true
   }
 }

package/src/db/dialects.js

@@ -33,7 +33,7 @@ function escapeIdentifierList(identifiers) {
 }
 
 function isDateLikeType(fieldType) {
-    return ["date", "datetime", "timestamp", "now"].includes(String(fieldType ?? "").toLowerCase());
+    return ["date", "datetime", "timestamp", "now", "time", "year"].includes(String(fieldType ?? "").toLowerCase());
 }
 
 function isSqlTemporalDefault(defaultValue) {

package/src/migration/BackupManager.js

@@ -0,0 +1,42 @@
+const { setSafe } = require("../utils/security/safe");
+
+class BackupManager {
+    constructor(connection, dialect, store) {
+        this.connection = connection;
+        this.dialect = dialect;
+        this.store = store;
+    }
+
+    async backupTables(tables, migrationId) {
+        if (!this.store.retention || tables.length === 0) return null;
+
+        const backup = {
+            version: 1,
+            createdAt: new Date().toISOString(),
+            migrationId,
+            tables: {}
+        };
+
+        const existing = await this.dialect.execute(
+            this.connection,
+            this.dialect.introspectionQueries().tables
+        );
+        const existingNames = new Set(existing.map(row => row.table_name));
+
+        for (const table of tables) {
+            // A table created by the migration does not exist yet and therefore
+            // cannot be backed up. Rollback metadata will remove it if needed.
+            if (!existingNames.has(table)) continue;
+
+            const rows = await this.dialect.execute(
+                this.connection,
+                `SELECT * FROM ${this.dialect.escape(table)}`
+            );
+            setSafe(backup.tables, table, rows);
+        }
+
+        return this.store.writeBackup(migrationId, backup);
+    }
+}
+
+module.exports = { BackupManager };

package/src/migration/Migration.js

@@ -0,0 +1,163 @@
+const { getConnexion } = require("../db/connexion");
+const { getDialect: getConnectorDialect } = require("../db/dialects");
+const { modelsToSnapshot } = require("./SchemaSnapshot");
+const { SchemaInspector } = require("./SchemaInspector");
+const { SchemaDiffer } = require("./SchemaDiffer");
+const { MigrationPlan } = require("./MigrationPlan");
+const { MigrationStore } = require("./MigrationStore");
+const { BackupManager } = require("./BackupManager");
+const { MigrationRunner } = require("./MigrationRunner");
+const { createDialect } = require("./dialects");
+const { migrationId, stableStringify, sha256 } = require("./utils");
+
+function resolveDialect(name) {
+    if (name) return createDialect(name);
+
+    try {
+        const connectorDialect = getConnectorDialect();
+        if (connectorDialect?.name) return createDialect(connectorDialect.name);
+    } catch (error) {
+        console.warn("Failed to resolve connector dialect:", error);
+    }
+
+    return createDialect("mysql");
+}
+
+function resolveModels(models) {
+    if (Array.isArray(models)) return models;
+
+    try {
+        const { Model } = require("../models/Model");
+        return Model.pendingModels || [];
+    } catch {
+        return [];
+    }
+}
+
+class Migration {
+    constructor(options = {}) {
+        this.connection = options.connection || getConnexion();
+        if (!this.connection) {
+            throw new Error("No database connection. Call connect() before using migrations.");
+        }
+
+        this.dialect = options.dialect && typeof options.dialect.execute === "function"
+            ? options.dialect
+            : resolveDialect(options.dialect);
+
+        this.models = resolveModels(options.models);
+        this.store = options.store || new MigrationStore({
+            directory: options.directory || "migrations",
+            backupDirectory: options.backupDirectory,
+            encryptionKey: options.encryptionKey,
+            retention: options.retention
+        });
+
+        this.inspector = new SchemaInspector(this.connection, this.dialect);
+        this.differ = new SchemaDiffer({
+            allowDestructiveChanges: options.allowDestructiveChanges,
+            allowDropTables: options.allowDropTables
+        });
+        this.backupManager = new BackupManager(
+            this.connection,
+            this.dialect,
+            this.store
+        );
+        this.runner = new MigrationRunner({
+            connection: this.connection,
+            dialect: this.dialect,
+            store: this.store,
+            backupManager: this.backupManager
+        });
+    }
+
+    async plan(options = {}) {
+        if (options.models) this.models = options.models;
+
+        const desired = modelsToSnapshot(this.models);
+        const current = await this.inspector.inspect();
+
+        const previous = await this.store.readSnapshot();
+        const baseline = previous || current;
+
+        const differ = new SchemaDiffer({
+            allowDestructiveChanges: options.allowDestructiveChanges ?? false,
+            allowDropTables: options.allowDropTables ?? false
+        });
+
+        // The DB is the safety check; the snapshot is used as history.
+        const operations = differ.diff(desired, current);
+
+        const sql = operations
+            .map(operation => this.runner.sqlForOperation(operation))
+            .join("\n");
+
+        const id = options.id || migrationId(options.name || "schema");
+        const checksum = sha256(stableStringify({
+            id,
+            dialect: this.dialect.name,
+            operations,
+            sql
+        }));
+
+        return new MigrationPlan({
+            id,
+            operations,
+            sql,
+            snapshot: desired,
+            previousSnapshot: baseline,
+            dialect: this.dialect,
+            checksum,
+            executor: (migrationPlan, executeOptions = {}) => this.runner.execute(
+                migrationPlan,
+                executeOptions
+            )
+        });
+    }
+
+    async migrate(options = {}) {
+        const plan = await this.plan(options);
+
+        if (!plan.hasChanges()) {
+            return { applied: false, plan };
+        }
+
+        if (options.approve !== false) plan.approve();
+
+        return this.runner.execute(plan, {
+            requireApproval: options.requireApproval ?? true,
+            allowDestructiveChanges: options.allowDestructiveChanges ?? false
+        });
+    }
+
+    async status() {
+        return this.runner.applied();
+    }
+
+    async rollback(id, options = {}) {
+        if (!id) throw new Error("A migration id is required for rollback.");
+        return this.runner.rollback(id, options);
+    }
+
+    async cleanup() {
+        return this.store.cleanup();
+    }
+
+    static async plan(options = {}) {
+        return new Migration(options).plan(options);
+    }
+
+    static async migrate(options = {}) {
+        return new Migration(options).migrate(options);
+    }
+
+    static async status(options = {}) {
+        return new Migration(options).status();
+    }
+
+    static async rollback(id, options = {}) {
+        return new Migration(options).rollback(id, options);
+    }
+}
+
+module.exports = { Migration };

package/src/migration/MigrationPlan.js

@@ -0,0 +1,62 @@
+const { sha256, stableStringify, migrationId, clone } = require("./utils");
+
+class MigrationPlan {
+    constructor({
+        id,
+        operations,
+        sql,
+        snapshot,
+        previousSnapshot,
+        dialect,
+        checksum = sha256(stableStringify({ id, operations, sql })),
+        executor = null
+    }) {
+        this.id = id || migrationId();
+        this.operations = operations;
+        this.sql = sql;
+        this.snapshot = clone(snapshot);
+        this.previousSnapshot = clone(previousSnapshot);
+        this.dialect = dialect.name;
+        this.checksum = checksum;
+        this.approved = false;
+        this._executor = executor;
+    }
+
+    hasChanges() {
+        return this.operations.length > 0;
+    }
+
+    hasDestructiveChanges() {
+        return this.operations.some(operation => operation.destructive);
+    }
+
+    destructiveChanges() {
+        return this.operations.filter(operation => operation.destructive);
+    }
+
+    approve() {
+        this.approved = true;
+        return this;
+    }
+
+    async execute(options = {}) {
+        if (!this._executor) {
+            throw new Error("This migration plan is not attached to a Migration runner.");
+        }
+        return this._executor(this, options);
+    }
+
+    toJSON() {
+        return {
+            id: this.id,
+            dialect: this.dialect,
+            checksum: this.checksum,
+            operations: this.operations,
+            sql: this.sql,
+            hasChanges: this.hasChanges(),
+            destructive: this.hasDestructiveChanges()
+        };
+    }
+}
+
+module.exports = { MigrationPlan };

package/src/migration/MigrationRunner.js

@@ -0,0 +1,194 @@
+const { getSafe } = require("../utils/security/safe");
+
+class MigrationRunner {
+    constructor({ connection, dialect, store, backupManager }) {
+        this.connection = connection;
+        this.dialect = dialect;
+        this.store = store;
+        this.backupManager = backupManager;
+    }
+
+    async ensureMigrationTable() {
+        await this.dialect.execute(
+            this.connection,
+            this.dialect.createMigrationTable()
+        );
+    }
+
+    async applied() {
+        await this.ensureMigrationTable();
+        return this.dialect.execute(
+            this.connection,
+            this.dialect.selectMigrations()
+        );
+    }
+
+    async execute(plan, options = {}) {
+        if (!plan.hasChanges()) {
+            return { applied: false, reason: "no-changes", plan };
+        }
+
+        if (!plan.approved && options.requireApproval !== false) {
+            throw new Error("Migration must be approved with plan.approve() before execution.");
+        }
+
+        if (plan.hasDestructiveChanges() && !options.allowDestructiveChanges) {
+            throw new Error("Destructive migration requires allowDestructiveChanges=true.");
+        }
+
+        await this.ensureMigrationTable();
+
+        const applied = await this.applied();
+        const existing = applied.find(row => row.id === plan.id);
+
+        if (existing) {
+            if (existing.checksum !== plan.checksum) {
+                throw new Error(
+                    `Migration '${plan.id}' is already applied with a different checksum.`
+                );
+            }
+            return { applied: false, reason: "already-applied", plan };
+        }
+
+        const affectedTables = [...new Set(
+            plan.operations
+                .filter(operation => operation.table)
+                .map(operation => operation.table)
+        )];
+
+        const backupPath = await this.backupManager.backupTables(
+            affectedTables,
+            plan.id
+        );
+
+        const run = async () => {
+            for (const operation of plan.operations) {
+                const sql = this.sqlForOperation(operation);
+                await this.dialect.execute(this.connection, sql);
+            }
+
+            const now = new Date().toISOString();
+            await this.dialect.execute(
+                this.connection,
+                this.dialect.insertMigration(),
+                [plan.id, plan.checksum, now, now]
+            );
+        };
+
+        await this.dialect.transaction(this.connection, run);
+        await this.store.writeMigration(plan);
+        await this.store.writeSnapshot(plan.snapshot);
+        await this.store.cleanup();
+
+        return {
+            applied: true,
+            plan,
+            backupPath
+        };
+    }
+
+    async rollback(id, options = {}) {
+        await this.ensureMigrationTable();
+        const applied = await this.applied();
+        const existing = applied.find(row => row.id === id);
+        if (!existing) throw new Error(`Migration '${id}' is not applied.`);
+
+        // Safety: only the most recently applied migration can be rolled back.
+        // This prevents restoring an old snapshot over newer schema/data changes.
+        if (!options.allowOutOfOrder) {
+            const last = applied[applied.length - 1];
+            if (!last || last.id !== id) {
+                throw new Error(`Migration '${id}' is not the latest applied migration. Roll back newer migrations first.`);
+            }
+        }
+
+        const metadata = await this.store.readMigration(id);
+        if (!metadata) throw new Error(`Rollback metadata for migration '${id}' was not found.`);
+        this.store.validateChecksum(metadata.checksum, existing.checksum);
+
+        const backup = await this.store.readBackup(id);
+        if (!backup) throw new Error(`Backup for migration '${id}' was not found. Rollback aborted.`);
+
+        const operations = this.buildRollbackOperations(metadata);
+        const run = async () => {
+            for (const operation of operations) {
+                await this.dialect.execute(this.connection, this.sqlForOperation(operation));
+            }
+            await this.restoreBackup(backup);
+            await this.dialect.execute(this.connection, this.dialect.deleteMigration(), [id]);
+        };
+
+        await this.dialect.transaction(this.connection, run);
+        await this.store.writeSnapshot(metadata.previousSnapshot || { tables: {} });
+
+        return { rolledBack: true, migrationId: id, operations, backupPath: null };
+    }
+
+    buildRollbackOperations(metadata) {
+        const previousTables = metadata.previousSnapshot?.tables || {};
+        return [...metadata.operations].reverse().map(operation => {
+            switch (operation.type) {
+                case "createTable":
+                    return { type: "dropTable", table: operation.table, destructive: true };
+                case "addColumn":
+                    return { type: "dropColumn", table: operation.table, column: operation.column, destructive: true };
+                case "renameColumn":
+                    return { type: "renameColumn", table: operation.table, oldName: operation.newName, newName: operation.oldName };
+                case "alterColumn": {
+                    const previous = operation.previous || previousTables[operation.table]?.columns?.[operation.column];
+                    if (!previous) throw new Error(`Cannot rollback alterColumn '${operation.table}.${operation.column}': previous definition is missing.`);
+                    return { type: "alterColumn", table: operation.table, column: operation.column, field: previous };
+                }
+                case "dropColumn": {
+                    const field = previousTables[operation.table]?.columns?.[operation.column];
+                    if (!field) throw new Error(`Cannot rollback dropped column '${operation.table}.${operation.column}': previous schema is missing.`);
+                    return { type: "addColumn", table: operation.table, column: operation.column, field };
+                }
+                case "dropTable": {
+                    const schema = previousTables[operation.table]?.columns || previousTables[operation.table];
+                    if (!schema) throw new Error(`Cannot rollback dropped table '${operation.table}': previous schema is missing.`);
+                    return { type: "createTable", table: operation.table, schema };
+                }
+                default:
+                    throw new Error(`Unsupported rollback operation: ${operation.type}`);
+            }
+        });
+    }
+
+    async restoreBackup(backup) {
+        for (const [table, rows] of Object.entries(backup.tables || {})) {
+            if (!Array.isArray(rows)) throw new Error(`Invalid backup rows for table '${table}'.`);
+            await this.dialect.execute(this.connection, `DELETE FROM ${this.dialect.escape(table)};`);
+            if (rows.length === 0) continue;
+
+            const columns = Object.keys(rows[0]);
+            const escapedColumns = columns.map(column => this.dialect.escape(column)).join(", ");
+            for (const row of rows) {
+                const values = columns.map(column => getSafe(row, column));
+                const sql = `INSERT INTO ${this.dialect.escape(table)} (${escapedColumns}) VALUES (${this.dialect.placeholders(values.length)});`;
+                await this.dialect.execute(this.connection, sql, values);
+            }
+        }
+    }
+
+    sqlForOperation(operation) {
+        switch (operation.type) {
+            case "createTable":
+                return this.dialect.createTable(operation.table, operation.schema);
+            case "addColumn":
+                return this.dialect.addColumn(operation.table, operation.column, operation.field);
+            case "renameColumn":
+                return this.dialect.renameColumn(operation.table, operation.oldName, operation.newName);
+            case "alterColumn":
+                return this.dialect.alterColumn(operation.table, operation.column, operation.field);
+            case "dropColumn":
+                return this.dialect.dropColumn(operation.table, operation.column);
+            case "dropTable":
+                return this.dialect.dropTable(operation.table);
+            default:
+                throw new Error(`Unsupported migration operation: ${operation.type}`);
+        }
+    }
+}
+
+module.exports = { MigrationRunner };