@mlagie/sql-connector 3.0.3 → 3.2.0

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,162 @@
+const { getConnexion } = require("../db/connexion");
+const { getDialect: getConnectorDialect, createDialect } = 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 { 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 };

package/src/migration/MigrationStore.js

@@ -0,0 +1,137 @@
+const fs = require("fs/promises");
+const path = require("path");
+const { encrypt, decrypt } = require("./crypto");
+const { parseDuration } = require("./utils");
+const { MigrationChecksumError } = require("./errors");
+
+class MigrationStore {
+    constructor(options = {}) {
+        this.directory = path.resolve(options.directory || "migrations");
+        this.backupDirectory = path.resolve(options.backupDirectory || path.join(this.directory, "backups"));
+        this.encryptionKey = options.encryptionKey || process.env.SQL_CONNECTOR_MIGRATION_KEY;
+        this.retention = parseDuration(options.retention ?? null);
+    }
+
+    async ensureDirectories() {
+        await fs.mkdir(this.directory, { recursive: true, mode: 0o700 });
+        await fs.mkdir(this.backupDirectory, { recursive: true, mode: 0o700 });
+    }
+
+    async writeMigration(plan) {
+        await this.ensureDirectories();
+        if (!this.encryptionKey) {
+            throw new Error("An encryption key is required to write migration files.");
+        }
+        const outputPath = path.join(this.directory, `${plan.id}.sql.enc`);
+        const payload = encrypt(plan.sql, this.encryptionKey);
+        await fs.writeFile(outputPath, payload, { encoding: "utf8", mode: 0o600 });
+
+        const metadataPath = path.join(this.directory, `${plan.id}.meta.json.enc`);
+        const metadata = {
+            version: 1,
+            id: plan.id,
+            dialect: plan.dialect,
+            checksum: plan.checksum,
+            operations: plan.operations,
+            previousSnapshot: plan.previousSnapshot,
+            snapshot: plan.snapshot
+        };
+        await fs.writeFile(metadataPath, encrypt(JSON.stringify(metadata, null, 2), this.encryptionKey), {
+            encoding: "utf8",
+            mode: 0o600
+        });
+        return outputPath;
+    }
+
+    async readMigration(id) {
+        await this.ensureDirectories();
+        if (!this.encryptionKey) throw new Error("An encryption key is required to read migration files.");
+        const file = path.join(this.directory, `${id}.meta.json.enc`);
+        try {
+            return JSON.parse(decrypt(await fs.readFile(file, "utf8"), this.encryptionKey));
+        } catch (error) {
+            if (error.code === "ENOENT") return null;
+            throw error;
+        }
+    }
+
+    async readBackup(id) {
+        await this.ensureDirectories();
+        if (!this.encryptionKey) throw new Error("An encryption key is required to read backups.");
+        const file = path.join(this.backupDirectory, `${id}.json.enc`);
+        try {
+            return JSON.parse(decrypt(await fs.readFile(file, "utf8"), this.encryptionKey));
+        } catch (error) {
+            if (error.code === "ENOENT") return null;
+            throw error;
+        }
+    }
+
+    async writeBackup(name, content) {
+        await this.ensureDirectories();
+        if (!this.retention) return null;
+        if (!this.encryptionKey) {
+            throw new Error("An encryption key is required to write backups.");
+        }
+        const outputPath = path.join(this.backupDirectory, `${name}.json.enc`);
+        await fs.writeFile(outputPath, encrypt(JSON.stringify(content, null, 2), this.encryptionKey), {
+            encoding: "utf8",
+            mode: 0o600
+        });
+        return outputPath;
+    }
+
+    async cleanup(now = Date.now()) {
+        if (!this.retention) return 0;
+        await this.ensureDirectories();
+
+        const files = await fs.readdir(this.backupDirectory);
+        let removed = 0;
+        for (const file of files) {
+            const fullPath = path.join(this.backupDirectory, file);
+            const stat = await fs.stat(fullPath);
+            if (now - stat.mtimeMs >= this.retention) {
+                await fs.rm(fullPath, { force: true });
+                removed++;
+            }
+        }
+        return removed;
+    }
+
+    async writeSnapshot(snapshot) {
+        await this.ensureDirectories();
+        const file = path.join(this.directory, "schema.snapshot.json");
+        await fs.writeFile(file, JSON.stringify(snapshot, null, 2) + "\n", {
+            encoding: "utf8",
+            mode: 0o600
+        });
+        return file;
+    }
+
+    async readSnapshot() {
+        try {
+            const file = path.join(this.directory, "schema.snapshot.json");
+            return JSON.parse(await fs.readFile(file, "utf8"));
+        } catch (error) {
+            if (error.code === "ENOENT") return null;
+            throw error;
+        }
+    }
+
+    async listMigrationFiles() {
+        await this.ensureDirectories();
+        return (await fs.readdir(this.directory))
+            .filter(file => file.endsWith(".sql.enc"))
+            .sort();
+    }
+
+    validateChecksum(actual, expected) {
+        if (actual !== expected) {
+            throw new MigrationChecksumError(
+                `Migration checksum mismatch. Expected ${expected}, got ${actual}.`
+            );
+        }
+    }
+}
+
+module.exports = { MigrationStore };