mysql-migration 1.2.3 → 1.2.5

package/README.md

@@ -1,25 +1,75 @@
-# MySQL Migration Database
+<div align="center">
 
-A simple command-line tool for generating and running database migrations for MySQL.
+# 🗄️ MySQL Migration Database
 
-## Installation
+**A command-line companion that helps you manage versioned MySQL schema changes from your Node.js projects.**
 
-You can install `mysql-migration` using npm: `npm install mysql-migration`
+[![npm version](https://img.shields.io/npm/v/mysql-migration.svg?style=flat-square)](https://www.npmjs.com/package/mysql-migration)&nbsp;&nbsp;
+[![License](https://img.shields.io/badge/license-Custom-blue.svg?style=flat-square)](LICENSE.md)&nbsp;&nbsp;
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg?style=flat-square)](https://nodejs.org/)
 
-### Initialize the migrations table
+</div>
 
-If you have not yet run any migrations, you need to initialize the migrations table by running the following command: `npx mysql-migration init`
+---
 
-<br>
+## ✨ Features
 
-## Configuration
+- 🎯 **Multi-database support** — Orchestrate migrations across different environments
+- ⏱️ **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
 
-The configuration file `mysql-migration.config.json` should export an object with the following properties:
+## 📋 Prerequisites
 
-- `host`: the MySQL server host
-- `database`: the name of the database to migrate
-- `user`: the MySQL user name
-- `password`: the MySQL user password
+- **Node.js** v18 or later.
+- **MySQL** instance reachable from where you run the CLI.
+- A project workspace where you can store migration files and configuration.
+
+## 📦 Installation
+
+Install locally within your project:
+
+```bash
+npm install --save-dev mysql-migration
+```
+
+Or run ad hoc without installing by prefixing commands with `npx`.
+
+## 🚀 Quick Start
+
+**1️⃣ Initialize the project**
+
+Run the init command to scaffold the `migrations/` directory and create a default configuration file:
+
+```bash
+npx mysql-migration init
+```
+
+**2️⃣ Configure your database**
+
+Edit the generated `migrations/mysql-migration.config.json` file with your database credentials.
+
+**3️⃣ Generate your first migration**
+
+```bash
+npx mysql-migration create add_users_table main-db
+```
+
+**4️⃣ Apply pending migrations**
+
+```bash
+npx mysql-migration run main-db
+```
+
+## ⚙️ 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:
+
+- `host`: MySQL server host name or IP.
+- `database`: Database schema name.
+- `user`: User with migration privileges.
+- `password`: Corresponding password.
 
 ```json
 {
@@ -34,29 +84,95 @@ The configuration file `mysql-migration.config.json` should export an object wit
 }
 ```
 
-<br>
+Add as many database entries as you need. You can then target each one via the CLI commands below.
+
+## 📖 Usage
+
+### 📝 Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx mysql-migration help` | 📚 Show all available commands |
+| `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 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 |
+| `npx mysql-migration to-esm <dbName>` | 🔄 Convert migrations to ESM |
+
+### 🎬 Initialize Project
 
-## Usage
+```bash
+npx mysql-migration init
+```
+
+Scaffolds the `migrations/` directory and creates a default `mysql-migration.config.json` file. Run this once when setting up the tool in a new project.
+
+### ✏️ Create a New Migration
+
+```bash
+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.
+
+### ▶️ Run Pending Migrations
+
+```bash
+npx mysql-migration run database-name
+```
+
+All migrations that have not yet been applied will run sequentially for the selected database.
+
+### ⏪ Roll Back Migrations
+
+```bash
+npx mysql-migration rollback database-name batch
+```
+
+Use this when you need to revert the database state to the specified batch number.
+
+### 📊 Inspect Batches
+
+```bash
+npx mysql-migration batch database-name
+```
+
+View the recorded batches to understand which migrations were executed together.
+
+### 🔄 Convert Module System
+
+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
+```
 
-### Create a new migration
+## 🔧 Troubleshooting
 
-To create a new migration, run the following command:\
-&emsp;`npx mysql-migration create migration-name database-name`
+- **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.
 
-This will create a new migration file in the `migrations` directory with a timestamp and the name `migration-name`.
+## 💬 Support
 
-### Running migrations
+Use `npx mysql-migration help` to review commands, or open an issue on the repository if you encounter bugs or have enhancement ideas.
 
-To run pending migrations, run the following command:\
-&emsp;`npx mysql-migration run database-name(optional)`
+---
 
-This will run all migrations that have not yet been run.
+<div align="center">
 
-### Rolling back migrations
+### 📄 License
 
-To roll back the last migration, run the following command:\
-&emsp;`npx mysql-migration rollback database-name batch`
+This project is distributed under a **custom non-commercial license**. Please review [`LICENSE.md`](LICENSE.md) for the full terms before using the software.
 
-This will roll back migrations to the given batch number.
+Made with ❤️ by [SherKan](https://github.com/SherKan-n)
 
-> **Copyright (c) 2023-present [𝐒𝐡𝐞𝐫𝐊𝐚𝐧](https://github.com/SherKan-n). All Rights Reserved.**
+</div>

package/index.js

@@ -13,6 +13,8 @@ program
         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`);
     });
 //---------------------------------------
@@ -41,4 +43,14 @@ program
     .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,6 +1,6 @@
 {
    "name": "mysql-migration",
-   "version": "1.2.3",
+   "version": "1.2.5",
    "description": "Migration for mysql database",
    "main": "index.js",
    "bin": {

package/src/commands/back.js

@@ -21,6 +21,7 @@ const {
     getCurrentBatch,
     deleteMigration,
 } = require("../utils/functions");
+const { loadModule } = require("../utils/moduleLoader");
 //==============================================================================
 async function back_migration(dbName, batch) {
     const connection = {};
@@ -68,7 +69,7 @@ async function back_migration(dbName, batch) {
                 console.warn("\x1b[33m%s\x1b[0m", `Warning: Migration "${file.migration}" not found.`);
             } else {
                 const migrationPath = `${currentPath}/migrations/${dbName}_db/${file.migration}`;
-                const migration = require(migrationPath);
+                const migration = await loadModule(migrationPath);
                 try {
                     await migration.down(connection[dbName]);
                     await deleteMigration(connection[dbName], file.migration, batchNumber);
@@ -78,8 +79,6 @@ async function back_migration(dbName, batch) {
                     );
                 } catch (err) {
                     console.warn("\x1b[33m%s\x1b[0m", `Warning: "${err}" in migration "${file.migration}".`);
-                } finally {
-                    delete require.cache[require.resolve(migrationPath)];
                 }
             }
         }

package/src/commands/create.js

@@ -2,6 +2,7 @@
 //---------------------------------------
 const fs = require("fs");
 const dayjs = require("dayjs");
+const path = require("path");
 //---------------------------------------
 const currentPath = process.cwd();
 const config = require(`${currentPath}/migrations/mysql-migration.config.json`);
@@ -29,7 +30,22 @@ function create_migration(migrationName, dbName) {
    if (fs.existsSync(filePath))
       console.warn("\x1b[33m%s\x1b[0m", `Warning: File "${fileName}" already exists in the "migrations" directory.`);
    else {
-      const dataText = `module.exports = {
+      let isEsm = false;
+      try {
+         const packageJsonPath = path.join(currentPath, "package.json");
+         if (fs.existsSync(packageJsonPath)) {
+            const packageJson = require(packageJsonPath);
+            if (packageJson.type === "module") {
+               isEsm = true;
+            }
+         }
+      } catch (e) {
+         // Ignore error, default to CJS
+      }
+
+      const exportPrefix = isEsm ? "export default" : "module.exports =";
+
+      const dataText = `${exportPrefix} {
    up: (connection) => {
       const query = "";
 

package/src/commands/run.js

@@ -21,6 +21,7 @@ const {
     getCurrentBatch,
     insertMigration,
 } = require("../utils/functions");
+const { loadModule } = require("../utils/moduleLoader");
 //==============================================================================
 async function run_migration(dbName) {
     const connection = {},
@@ -66,15 +67,13 @@ async function run_migration(dbName) {
         //---------------------------------------
         for (let file of pendingMigrations) {
             const migrationPath = `${currentPath}/migrations/${dbName}_db/${file}`;
-            const migration = require(migrationPath);
+            const migration = await loadModule(migrationPath);
             try {
                 await migration.up(connection[dbName]);
                 await insertMigration(connection[dbName], file.replace(".js", ""), batch);
                 console.log("\x1b[36m%s\x1b[0m", `Migrated: "${file}" successfully.`);
             } catch (err) {
                 console.warn("\x1b[33m%s\x1b[0m", `Warning: "${err}" in migration "${file}".`);
-            } finally {
-                delete require.cache[require.resolve(migrationPath)];
             }
         }
         console.log("\x1b[32m%s\x1b[0m", "All migrations have been completed successfully.\n");
@@ -115,15 +114,13 @@ async function run_migration(dbName) {
         //---------------------------------------
         for (let [file, key, batch] of migrations) {
             const migrationPath = `${currentPath}/migrations/${key}_db/${file}`;
-            const migration = require(migrationPath);
+            const migration = await loadModule(migrationPath);
             try {
                 await migration.up(connection[key]);
                 await insertMigration(connection[key], file.replace(".js", ""), batch);
                 console.log("\x1b[36m%s\x1b[0m", `Migrated: "${file}" in database "${key}" successfully.`);
             } catch (err) {
                 console.warn("\x1b[33m%s\x1b[0m", `Warning: "${err}" in migration "${file}" in database "${key}".`);
-            } finally {
-                delete require.cache[require.resolve(migrationPath)];
             }
         }
         console.log("\x1b[32m%s\x1b[0m", "All migrations have been completed successfully.\n");

package/src/commands/to-cjs.js

@@ -0,0 +1,49 @@
+"use strict";
+//---------------------------------------
+const fs = require("fs");
+const path = require("path");
+//---------------------------------------
+const currentPath = process.cwd();
+const config = require(`${currentPath}/migrations/mysql-migration.config.json`);
+//---------------------------------------
+function convert_to_cjs(dbName) {
+    //---------------------------------------
+    const databases = Object.keys(config.databases);
+    //---------------------------------------
+    if (!databases.includes(dbName)) {
+        console.error("\x1b[31m%s\x1b[0m", `Error: Invalid database name "${dbName}" can be: ${databases.join(", ")}.`);
+        process.exit(1);
+    }
+    //---------------------------------------
+    const migrationsDir = `${currentPath}/migrations/${dbName}_db`;
+    if (!fs.existsSync(migrationsDir)) {
+        console.error("\x1b[31m%s\x1b[0m", `Error: Migrations directory for "${dbName}" not found.`);
+        process.exit(1);
+    }
+    //---------------------------------------
+    const files = fs.readdirSync(migrationsDir);
+    let convertedCount = 0;
+
+    for (const file of files) {
+        if (file.endsWith(".js")) {
+            const filePath = path.join(migrationsDir, file);
+            let content = fs.readFileSync(filePath, "utf8");
+
+            // Simple check and replace for export default
+            if (content.includes("export default")) {
+                content = content.replace("export default", "module.exports =");
+                fs.writeFileSync(filePath, content);
+                console.log("\x1b[32m%s\x1b[0m", `Converted: "${file}" to CJS.`);
+                convertedCount++;
+            }
+        }
+    }
+
+    if (convertedCount === 0) {
+        console.log("\x1b[33m%s\x1b[0m", "No files needed conversion.");
+    } else {
+        console.log("\x1b[32m%s\x1b[0m", `\nSuccessfully converted ${convertedCount} files to CJS.`);
+    }
+}
+//---------------------------------------
+module.exports = convert_to_cjs;

package/src/commands/to-esm.js

@@ -0,0 +1,49 @@
+"use strict";
+//---------------------------------------
+const fs = require("fs");
+const path = require("path");
+//---------------------------------------
+const currentPath = process.cwd();
+const config = require(`${currentPath}/migrations/mysql-migration.config.json`);
+//---------------------------------------
+function convert_to_esm(dbName) {
+    //---------------------------------------
+    const databases = Object.keys(config.databases);
+    //---------------------------------------
+    if (!databases.includes(dbName)) {
+        console.error("\x1b[31m%s\x1b[0m", `Error: Invalid database name "${dbName}" can be: ${databases.join(", ")}.`);
+        process.exit(1);
+    }
+    //---------------------------------------
+    const migrationsDir = `${currentPath}/migrations/${dbName}_db`;
+    if (!fs.existsSync(migrationsDir)) {
+        console.error("\x1b[31m%s\x1b[0m", `Error: Migrations directory for "${dbName}" not found.`);
+        process.exit(1);
+    }
+    //---------------------------------------
+    const files = fs.readdirSync(migrationsDir);
+    let convertedCount = 0;
+
+    for (const file of files) {
+        if (file.endsWith(".js")) {
+            const filePath = path.join(migrationsDir, file);
+            let content = fs.readFileSync(filePath, "utf8");
+
+            // Simple check and replace for module.exports
+            if (content.includes("module.exports =")) {
+                content = content.replace("module.exports =", "export default");
+                fs.writeFileSync(filePath, content);
+                console.log("\x1b[32m%s\x1b[0m", `Converted: "${file}" to ESM.`);
+                convertedCount++;
+            }
+        }
+    }
+
+    if (convertedCount === 0) {
+        console.log("\x1b[33m%s\x1b[0m", "No files needed conversion.");
+    } else {
+        console.log("\x1b[32m%s\x1b[0m", `\nSuccessfully converted ${convertedCount} files to ESM.`);
+    }
+}
+//---------------------------------------
+module.exports = convert_to_esm;

package/src/utils/moduleLoader.js

@@ -0,0 +1,29 @@
+const path = require("path");
+const { pathToFileURL } = require("url");
+
+/**
+ * Loads a module from the specified file path using dynamic import.
+ * Handles both CommonJS and ES Modules.
+ *
+ * @param {string} filePath - The absolute path to the file.
+ * @returns {Promise<any>} - The loaded module content.
+ */
+async function loadModule(filePath) {
+    try {
+        // Convert path to file URL for Windows compatibility with dynamic import
+        const fileUrl = pathToFileURL(filePath).href;
+        const module = await import(fileUrl);
+
+        // If it's a CJS module loaded via import(), the default export holds the module.exports
+        // If it's an ESM module, we return the module namespace object or specific exports
+        // For this migration tool, we expect the migration object to be the default export or the module itself
+        if (module.default) {
+            return module.default;
+        }
+        return module;
+    } catch (error) {
+        throw new Error(`Failed to load module at ${filePath}: ${error.message}`);
+    }
+}
+
+module.exports = { loadModule };