mysql-migration 1.2.5 → 1.4.0

package/README.md

@@ -18,7 +18,9 @@
 - ⏱️ **Timestamped migration files** — Generated with a single command
 - ⚡ **Forward and backward execution** — Run or roll back batches confidently
 - 🔧 **Scriptable CLI** — Plugs into CI/CD pipelines via standard Node.js tooling
-- 📦 **Zero dependencies** — Lightweight and fast
+- 🔐 **Transactional migrations** — Automatic rollback on failure
+- 👁️ **Dry-run mode** — Preview migrations without executing
+- 📘 **TypeScript support** — Full type definitions included
 
 ## 📋 Prerequisites
 
@@ -56,20 +58,23 @@ Edit the generated `migrations/mysql-migration.config.json` file with your datab
 npx mysql-migration create add_users_table main-db
 ```
 
-**4️⃣ Apply pending migrations**
+**4️⃣ Preview migrations (optional)**
 
 ```bash
-npx mysql-migration run main-db
+npx mysql-migration run main-db --dry-run
+```
+
+**5️⃣ Apply pending migrations**
+
+```bash
+npx mysql-migration run main-db --transaction
 ```
 
 ## ⚙️ Configuration
 
-The CLI reads settings from `mysql-migration.config.json`. Define each database you manage inside the `databases` object. Every entry requires the connection credentials documented below:
+The CLI reads settings from `mysql-migration.config.json`. Define each database you manage inside the `databases` object.
 
-- `host`: MySQL server host name or IP.
-- `database`: Database schema name.
-- `user`: User with migration privileges.
-- `password`: Corresponding password.
+### Basic Configuration
 
 ```json
 {
@@ -84,8 +89,6 @@ The CLI reads settings from `mysql-migration.config.json`. Define each database
 }
 ```
 
-Add as many database entries as you need. You can then target each one via the CLI commands below.
-
 ## 📖 Usage
 
 ### 📝 Available Commands
@@ -96,6 +99,8 @@ Add as many database entries as you need. You can then target each one via the C
 | `npx mysql-migration init` | 🎬 Scaffold migrations directory and config |
 | `npx mysql-migration create <name> <dbName>` | ✏️ Scaffold a timestamped migration file |
 | `npx mysql-migration run [dbName]` | ▶️ Execute all pending migrations |
+| `npx mysql-migration run [dbName] --dry-run` | 👁️ Preview migrations without executing |
+| `npx mysql-migration run [dbName] --transaction` | 🔐 Run migrations with automatic rollback on error |
 | `npx mysql-migration rollback <dbName> <batch>` | ⏪ Roll back migrations to specified batch |
 | `npx mysql-migration batch <dbName>` | 📊 Display recorded batches |
 | `npx mysql-migration to-cjs <dbName>` | 🔄 Convert migrations to CommonJS |
@@ -115,7 +120,51 @@ Scaffolds the `migrations/` directory and creates a default `mysql-migration.con
 npx mysql-migration create migration-name database-name
 ```
 
-A new file appears in the `migrations/` directory, timestamped and ready for your SQL `up` and `down` statements.
+A new file appears in the `migrations/` directory, timestamped and ready for your SQL `up` and `down` statements. The generated migration uses modern async/await syntax:
+
+```javascript
+module.exports = {
+   /**
+    * Run the migration
+    * @param {import('mysql2').Connection} connection
+    */
+   up: async (connection) => {
+      const query = "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255))";
+      await connection.promise().query(query);
+   },
+
+   /**
+    * Rollback the migration
+    * @param {import('mysql2').Connection} connection
+    */
+   down: async (connection) => {
+      const query = "DROP TABLE users";
+      await connection.promise().query(query);
+   }
+};
+```
+
+### 👁️ Dry-Run Mode
+
+Preview migrations without executing them:
+
+```bash
+npx mysql-migration run main-db --dry-run
+```
+
+This is useful for CI/CD pipelines or production deployments where you want to verify what will change before applying it.
+
+### 🔐 Transactional Migrations
+
+Run migrations with automatic rollback on failure:
+
+```bash
+npx mysql-migration run main-db --transaction
+```
+
+If any migration fails, all migrations in the current batch will be automatically rolled back, keeping your database in a consistent state.
+
+**Note:** Transactions work best with migrations that don't include DDL statements that cause implicit commits (like `CREATE TABLE`, `DROP TABLE`, etc. in MySQL).
 
 ### ▶️ Run Pending Migrations
 
@@ -146,20 +195,50 @@ View the recorded batches to understand which migrations were executed together.
 If you need to switch your project between CommonJS (`require`) and ES Modules (`import/export`), you can batch convert your existing migration files.
 
 **Convert to CommonJS:**
+
 ```bash
 npx mysql-migration to-cjs database-name
 ```
 
 **Convert to ES Modules:**
+
 ```bash
 npx mysql-migration to-esm database-name
 ```
 
+## 📘 TypeScript Support
+
+The package includes full TypeScript type definitions. Import types in your project:
+
+```typescript
+import type { Migration, Connection } from 'mysql-migration';
+
+// Your migration file can use these types
+const myMigration: Migration = {
+   up: async (connection: Connection) => {
+      // ...
+   },
+   down: async (connection: Connection) => {
+      // ...
+   }
+};
+```
+
+For IDE autocomplete support, ensure you have the package installed and your TypeScript configuration includes `node` types.
+
 ## 🔧 Troubleshooting
 
 - **Authentication errors**: Verify credentials in `mysql-migration.config.json` match your MySQL user.
 - **Connection refused**: Ensure the MySQL server accepts remote connections from your host and the port is open.
 - **Missing migrations folder**: Run `npx mysql-migration init` to scaffold the `migrations/` directory and configuration file.
+- **Connection leaks**: The tool now automatically manages connections with proper cleanup, even on errors.
+
+## 🔒 Security Best Practices
+
+1. **Limit access** to the machine or CI secrets storage that holds your config file
+2. **Never commit** `mysql-migration.config.json` with real passwords to version control
+3. **Use dry-run mode** before running migrations in production
+4. **Use transactional migrations** for safer deployments
 
 ## 💬 Support
 

package/index.d.ts

@@ -0,0 +1,92 @@
+import { Connection } from "mysql2";
+
+/**
+ * Database configuration for migrations
+ */
+export interface DatabaseConfig {
+    host: string;
+    user: string;
+    password: string;
+    database: string;
+    port?: number;
+}
+
+/**
+ * Migration configuration file structure
+ */
+export interface MigrationConfig {
+    databases: Record<string, DatabaseConfig>;
+}
+
+/**
+ * Migration file interface
+ */
+export interface Migration {
+    /**
+     * Run the migration
+     * @param connection - MySQL connection
+     */
+    up(connection: Connection): Promise<void>;
+
+    /**
+     * Rollback the migration
+     * @param connection - MySQL connection
+     */
+    down(connection: Connection): Promise<void>;
+}
+
+/**
+ * Migration record from database
+ */
+export interface MigrationRecord {
+    migration: string;
+    batch: number;
+}
+
+/**
+ * Connection manager for handling database connections
+ */
+export declare class ConnectionManager {
+    constructor();
+    createConnection(name: string, config: DatabaseConfig): Promise<Connection>;
+    getConnection(name: string): Connection | undefined;
+    closeConnection(name: string): Promise<void>;
+    closeAll(): Promise<void>;
+    withConnection<T>(
+        name: string,
+        config: DatabaseConfig,
+        callback: (connection: Connection) => Promise<T>
+    ): Promise<T>;
+    withCleanup<T>(callback: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * Configuration utility functions
+ */
+export declare function loadConfig(configPath: string): MigrationConfig;
+export declare function getDatabaseConfig(dbName: string, config: MigrationConfig): DatabaseConfig;
+export declare function getDatabaseNames(config: MigrationConfig): string[];
+export declare function isValidDatabase(dbName: string, config: MigrationConfig): boolean;
+
+/**
+ * Database utility functions
+ */
+export declare function checkTableMigrations(connection: Connection): Promise<boolean>;
+export declare function createTableMigrations(connection: Connection): Promise<boolean>;
+export declare function getAllMigrations(connection: Connection, batch?: number | null): Promise<MigrationRecord[]>;
+export declare function getCurrentBatch(connection: Connection): Promise<number>;
+export declare function insertMigration(connection: Connection, migration: string, batch: number): Promise<boolean>;
+export declare function deleteMigration(connection: Connection, migration: string, batch: number): Promise<boolean>;
+export declare function getAllBatches(connection: Connection): Promise<MigrationRecord[]>;
+export declare function beginTransaction(connection: Connection): Promise<void>;
+export declare function commitTransaction(connection: Connection): Promise<void>;
+export declare function rollbackTransaction(connection: Connection): Promise<void>;
+export declare function withTransaction<T>(
+    connection: Connection,
+    callback: (connection: Connection) => Promise<T>
+): Promise<T>;
+
+/**
+ * Module loader for CJS and ESM migrations
+ */
+export declare function loadModule(filePath: string): Promise<Migration>;

package/index.js

@@ -1,56 +1,61 @@
 #!/usr/bin/env node
 const { Command } = require("commander");
 const program = new Command();
-//---------------------------------------
+
 program
     .command("help")
     .description("Show all available commands")
     .action(() => {
-        console.log(`\nUsage: cli-tool <command> [options]\n`);
+        console.log(`\nUsage: mysql-migration <command> [options]\n`);
         console.log(`Available commands:\n`);
         console.log(`  init                      Initialize migration`);
-        console.log(`  run [dbName]              Run migration`);
+        console.log(`  run [dbName]              Run migration (supports --dry-run, --transaction)`);
         console.log(`  rollback <dbName> <batch> Rollback migration`);
         console.log(`  create <name> <dbName>    Create a new migration`);
         console.log(`  batch <dbName>            Get the batched migrations`);
         console.log(`  to-esm <dbName>           Convert migrations to ESM`);
         console.log(`  to-cjs <dbName>           Convert migrations to CJS`);
         console.log(`  help                      Show this help message\n`);
+        console.log(`Run command options:\n`);
+        console.log(`  --dry-run, -d             Preview migrations without executing`);
+        console.log(`  --transaction, -t         Use transactions for migrations (auto rollback on error)\n`);
     });
-//---------------------------------------
+
 program
     .command("init")
     .description("Initialize migration")
     .action(() => require("./src/commands/init"));
-//---------------------------------------
+
 program
     .command("run [dbName]")
     .description("Run migration")
-    .action((dbName) => require("./src/commands/run")(dbName));
-//---------------------------------------
+    .option("-d, --dry-run", "Preview migrations without executing")
+    .option("-t, --transaction", "Use transactions for migrations (auto rollback on error)")
+    .action((dbName, options) => require("./src/commands/run")(dbName, options.dryRun, options.transaction));
+
 program
     .command("rollback <dbName> <batch>")
     .description("Rollback migration")
     .action((dbName, batch) => require("./src/commands/back")(dbName, batch));
-//---------------------------------------
+
 program
     .command("create <migrationName> <dbName>")
     .description("Create a new migration")
     .action((migrationName, dbName) => require("./src/commands/create")(migrationName, dbName));
-//---------------------------------------
+
 program
     .command("batch <dbName>")
     .description("Get the batched migrations")
     .action((dbName) => require("./src/commands/batch")(dbName));
-//---------------------------------------
+
 program
     .command("to-esm <dbName>")
     .description("Convert migrations to ESM")
     .action((dbName) => require("./src/commands/to-esm")(dbName));
-//---------------------------------------
+
 program
     .command("to-cjs <dbName>")
     .description("Convert migrations to CJS")
     .action((dbName) => require("./src/commands/to-cjs")(dbName));
-//---------------------------------------
+
 program.parse(process.argv);

package/package.json

@@ -1,8 +1,9 @@
 {
    "name": "mysql-migration",
-   "version": "1.2.5",
-   "description": "Migration for mysql database",
+   "version": "1.4.0",
+   "description": "Migration for mysql database with TypeScript support, transactions, and environment variables",
    "main": "index.js",
+   "types": "index.d.ts",
    "bin": {
       "mysql-migration": "./index.js"
    },
@@ -21,13 +22,31 @@
       "mysql2",
       "database migration",
       "mysql migration database",
-      "mysql migration tool"
+      "mysql migration tool",
+      "typescript",
+      "transactions",
+      "dry-run",
+      "environment variables"
    ],
    "dependencies": {
-      "commander": "^14.0.1",
-      "dayjs": "^1.11.18",
-      "mysql2": "^3.15.3"
+      "commander": "^14.0.2",
+      "dayjs": "^1.11.19",
+      "mysql2": "^3.16.0"
+   },
+   "devDependencies": {
+      "@types/node": "^20.19.27",
+      "typescript": "^5.9.3"
    },
    "author": "SherKan",
-   "license": "SEE LICENSE IN LICENSE.md"
+   "license": "SEE LICENSE IN LICENSE.md",
+   "engines": {
+      "node": ">=18.0.0"
+   },
+   "files": [
+      "index.js",
+      "index.d.ts",
+      "src/",
+      "README.md",
+      "LICENSE.md"
+   ]
 }

package/src/commands/back.js

@@ -1,11 +1,11 @@
 "use strict";
-//==============================================================================
+
 const fs = require("fs");
-const mysql = require("mysql2");
 const path = require("path");
-//---------------------------------------
+
 const currentPath = process.cwd();
 const configPath = path.join(currentPath, "migrations", "mysql-migration.config.json");
+
 if (!fs.existsSync(configPath)) {
     console.error(
         "\x1b[31m%s\x1b[0m",
@@ -13,7 +13,9 @@ if (!fs.existsSync(configPath)) {
     );
     process.exit(1);
 }
-const config = require(configPath);
+
+const ConnectionManager = require("../utils/connectionManager");
+const { loadConfig, getDatabaseConfig, isValidDatabase } = require("../utils/config");
 const {
     checkTableMigrations,
     createTableMigrations,
@@ -22,68 +24,75 @@ const {
     deleteMigration,
 } = require("../utils/functions");
 const { loadModule } = require("../utils/moduleLoader");
-//==============================================================================
+
+/**
+ * Roll back previously applied migrations for a database.
+ * @param {string} dbName - Target database name.
+ * @param {string|number} batch - Batch number threshold for rollback.
+ * @returns {Promise<void>}
+ */
 async function back_migration(dbName, batch) {
-    const connection = {};
-    const databases = config.databases;
+    if (!dbName) {
+        console.error("\x1b[31m%s\x1b[0m", `Error: Database name is required.`);
+        process.exit(1);
+    }
 
-    //---------------------------------------
-    if (dbName) {
-        const batchNumber = parseInt(batch);
-        if (isNaN(batchNumber)) {
-            console.error("\x1b[31m%s\x1b[0m", `Error: Invalid batch number.`);
-            process.exit(1);
-        }
-        //---------------------------------------
-        if (!databases[dbName]) {
+    const batchNumber = parseInt(batch);
+    if (isNaN(batchNumber)) {
+        console.error("\x1b[31m%s\x1b[0m", `Error: Invalid batch number.`);
+        process.exit(1);
+    }
+
+    const config = loadConfig(configPath);
+    const connectionManager = new ConnectionManager();
+
+    try {
+        if (!isValidDatabase(dbName, config)) {
             console.error("\x1b[31m%s\x1b[0m", `Error: Invalid database name "${dbName}".`);
             process.exit(1);
         }
-        //---------------------------------------
-        connection[dbName] = mysql.createConnection(databases[dbName]);
-        try {
-            await connection[dbName].promise().connect();
-        } catch (err) {
-            console.error("\x1b[31m%s\x1b[0m", `Error: Unable to connect to database "${dbName}".\n${err}`);
-            process.exit(1);
-        }
-        //---------------------------------------
-        const tableMigrations = await checkTableMigrations(connection[dbName]);
-        if (!tableMigrations) await createTableMigrations(connection[dbName]);
-        //---------------------------------------
-        const currentBatch = await getCurrentBatch(connection[dbName]);
-        if (batchNumber >= currentBatch) {
-            console.error("\x1b[31m%s\x1b[0m", `Error: Invalid batch number, the current batch is "${currentBatch}".`);
-            await connection[dbName].promise().end();
-            process.exit(1);
-        }
-        const migrations = await getAllMigrations(connection[dbName], batchNumber);
-        if (migrations.length === 0) {
-            console.log("\x1b[32m%s\x1b[0m", `Nothing to rollback for batch greater than ${batchNumber}.`);
-            await connection[dbName].promise().end();
-            process.exit(0);
-        }
-        //---------------------------------------
-        for (let file of migrations) {
-            if (!fs.existsSync(`${currentPath}/migrations/${dbName}_db/${file.migration}.js`)) {
-                console.warn("\x1b[33m%s\x1b[0m", `Warning: Migration "${file.migration}" not found.`);
-            } else {
-                const migrationPath = `${currentPath}/migrations/${dbName}_db/${file.migration}`;
-                const migration = await loadModule(migrationPath);
-                try {
-                    await migration.down(connection[dbName]);
-                    await deleteMigration(connection[dbName], file.migration, batchNumber);
-                    console.log(
-                        "\x1b[32m%s\x1b[0m",
-                        `Migration "${file.migration}" has been successfully rolled back.`
-                    );
-                } catch (err) {
-                    console.warn("\x1b[33m%s\x1b[0m", `Warning: "${err}" in migration "${file.migration}".`);
+
+        const dbConfig = getDatabaseConfig(dbName, config);
+        const migrationsDir = path.join(currentPath, "migrations", `${dbName}_db`);
+
+        await connectionManager.withConnection(dbName, dbConfig, async (connection) => {
+            const tableMigrations = await checkTableMigrations(connection);
+            if (!tableMigrations) await createTableMigrations(connection);
+
+            const currentBatch = await getCurrentBatch(connection);
+            if (batchNumber >= currentBatch) {
+                console.error("\x1b[31m%s\x1b[0m", `Error: Invalid batch number, the current batch is "${currentBatch}".`);
+                return;
+            }
+
+            const migrations = await getAllMigrations(connection, batchNumber);
+            if (migrations.length === 0) {
+                console.log("\x1b[32m%s\x1b[0m", `Nothing to rollback for batch greater than ${batchNumber}.`);
+                return;
+            }
+
+            for (let file of migrations) {
+                const migrationFile = path.join(migrationsDir, `${file.migration}.js`);
+                if (!fs.existsSync(migrationFile)) {
+                    console.warn("\x1b[33m%s\x1b[0m", `Warning: Migration "${file.migration}" not found.`);
+                } else {
+                    const migration = await loadModule(migrationFile);
+                    try {
+                        await migration.down(connection);
+                        await deleteMigration(connection, file.migration, batchNumber);
+                        console.log(
+                            "\x1b[32m%s\x1b[0m",
+                            `Migration "${file.migration}" has been successfully rolled back.`
+                        );
+                    } catch (err) {
+                        console.warn("\x1b[33m%s\x1b[0m", `Warning: "${err}" in migration "${file.migration}".`);
+                    }
                 }
             }
-        }
-        await connection[dbName].promise().end();
-    } else console.error("\x1b[31m%s\x1b[0m", `Error: Database name is empty !`);
+        });
+    } finally {
+        await connectionManager.closeAll();
+    }
 }
-//==============================================================================
+
 module.exports = back_migration;

package/src/commands/batch.js

@@ -1,53 +1,58 @@
 "use strict";
-//==============================================================================
-const mysql = require("mysql2");
-//---------------------------------------
+
+const path = require("path");
+
 const currentPath = process.cwd();
-const config = require(`${currentPath}/migrations/mysql-migration.config.json`);
+const configPath = path.join(currentPath, "migrations", "mysql-migration.config.json");
+
+const ConnectionManager = require("../utils/connectionManager");
+const { loadConfig, getDatabaseConfig, isValidDatabase } = require("../utils/config");
 const { checkTableMigrations, createTableMigrations, getAllBatches, getCurrentBatch } = require("../utils/functions");
-//==============================================================================
+
+/**
+ * Display migrations grouped by batch for a database.
+ * @param {string} dbName - Target database name.
+ * @returns {Promise<void>}
+ */
 async function show_batched_migrations(dbName) {
-    const connection = {};
-    const databases = config.databases;
-    //---------------------------------------
-    if (dbName) {
-        if (!databases[dbName]) {
+    if (!dbName) {
+        console.error("\x1b[31m%s\x1b[0m", `Error: Database name is required.`);
+        process.exit(1);
+    }
+
+    const config = loadConfig(configPath);
+    const connectionManager = new ConnectionManager();
+
+    try {
+        if (!isValidDatabase(dbName, config)) {
             console.error("\x1b[31m%s\x1b[0m", `Error: Invalid database name "${dbName}".`);
             process.exit(1);
         }
-        //---------------------------------------
-        connection[dbName] = mysql.createConnection(databases[dbName]);
-        connection[dbName].connect((err) => {
-            if (err) {
-                console.error("\x1b[31m%s\x1b[0m", `Error: Unable to connect to database "${dbName}".\n${err}`);
-                process.exit(1);
+
+        const dbConfig = getDatabaseConfig(dbName, config);
+
+        await connectionManager.withConnection(dbName, dbConfig, async (connection) => {
+            const tableMigrations = await checkTableMigrations(connection);
+            if (!tableMigrations) await createTableMigrations(connection);
+
+            const currentBatch = await getCurrentBatch(connection);
+            const migrations = await getAllBatches(connection);
+
+            if (migrations.length > 0) {
+                console.log("\x1b[32m%s\x1b[0m", `Batched migrations for database "${dbName}":`);
+                migrations.forEach((migration) => {
+                    const migrationName = migration.migration.split("_").slice(4).join("_");
+                    console.log(`[Batch ${migration.batch}] - ${migrationName}`);
+                });
+            } else {
+                console.log("\x1b[32m%s\x1b[0m", `No batched migrations for database "${dbName}".`);
             }
+
+            console.log("\x1b[36m%s\x1b[0m", `Current batch for database "${dbName}": ${currentBatch}`);
         });
-        //---------------------------------------
-        const tableMigrations = checkTableMigrations(connection[dbName]);
-        if (!tableMigrations) createTableMigrations(connection[dbName]);
-        //---------------------------------------
-        const currentBatch = await getCurrentBatch(connection[dbName]);
-        //---------------------------------------
-        getAllBatches(connection[dbName])
-            .then((migrations) => {
-                if (migrations.length > 0) {
-                    console.log("\x1b[32m%s\x1b[0m", `Batched migrations for database "${dbName}":`);
-                    migrations.forEach((migration) => {
-                        const migrationName = migration.migration.split("_").slice(4).join("_");
-                        console.log(`[Batch ${migration.batch}] - ${migrationName}`);
-                    });
-                } else console.log("\x1b[32m%s\x1b[0m", `No batched migrations for database "${dbName}".`);
-                connection[dbName].end();
-            })
-            .catch((err) => {
-                console.error("\x1b[31m%s\x1b[0m", `Error: ${err}`);
-                connection[dbName].end();
-            })
-            .finally(() => {
-                console.log("\x1b[36m%s\x1b[0m", `Current batch for database "${dbName}": ${currentBatch}`);
-            });
-    } else console.error("\x1b[31m%s\x1b[0m", `Error: Database name is empty !`);
+    } finally {
+        await connectionManager.closeAll();
+    }
 }
-//==============================================================================
+
 module.exports = show_batched_migrations;