🗄️ MySQL Migration Database

A command-line companion that helps you manage versioned MySQL schema changes from your Node.js projects.

✨ Features

• 🎯 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

📋 Prerequisites

• 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:

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:

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

npx mysql-migration create add_users_table main-db

4️⃣ Apply pending migrations

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.

{
  "databases": {
    "db_name": {
      "host": "db_host",
      "user": "db_user",
      "password": "db_password",
      "database": "db_name"
    }
  }
}

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

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

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

npx mysql-migration run database-name

All migrations that have not yet been applied will run sequentially for the selected database.

⏪ Roll Back Migrations

npx mysql-migration rollback database-name batch

Use this when you need to revert the database state to the specified batch number.

📊 Inspect Batches

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:

npx mysql-migration to-cjs database-name

Convert to ES Modules:

npx mysql-migration to-esm database-name

🔧 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.

💬 Support

Use npx mysql-migration help to review commands, or open an issue on the repository if you encounter bugs or have enhancement ideas.

📄 License

This project is distributed under a custom non-commercial license. Please review LICENSE.md for the full terms before using the software.

Made with ❤️ by SherKan