Flaks-migrate

Lightweight MySQL migration tool.
Supports both local and global installation.

Installation

Install with npm, either locally or globally.

Local (project-level):

npm install flaks-migrate

Global:

npm install -g flaks-migrate

Usage

Create a config file (via CLI or manually) and place it in the root of your project.
By default, it is named migrate-config.js.

To use a custom filename, set the environment variable MIGRATE_CONFIG_FILENAME when running CLI commands.

Default config:

/** @type {import("flaks-migrate/types/global").DbConfig} */
const config = {
    /**
     * mysql2 db config. You can adjust as needed (e.g. Unix socket)
     */
    db: {
        host: "127.0.0.1",
        port: 3306,
        user: "root",
        password: "root",
        database: "my_project",
    },

    /**
     * Migration tracking table name
     */
    migrationTable: "migrations",

    /**
     * Directory containing migration files (keep inside your project)
     */
    pathToMigrations: "./migrations",
};

module.exports = config;

CLI

⚠️ Important: You cannot run any commands without a config file (except for config creation).
💡 Note: If installed globally, remove the npx prefix from commands.

Example:
npx flaks-migrate config → flaks-migrate config

Create config

Generate a config file (overwrites if it exists).
Run from the project root.

npx flaks-migrate config

Init migration table

Create the migration table in your database with the name from the config.
⚠️ Do not rename this table afterward, or migrations will stop working.

npx flaks-migrate init

Create migration

Generate a new migration file with up and down methods.

npx flaks-migrate create SomeMigrationName

Replace SomeMigrationName with a descriptive name.

Show migrations

List all migrations in the project.

npx flaks-migrate show

Up migrations

Apply pending migrations in ascending order (by timestamp).
If no count is given, all pending migrations are applied.

npx flaks-migrate up 10

Runs the next 10 migrations.

Down migrations

Rollback migrations in descending order (by timestamp).
If no count is given, only one migration is rolled back.

npx flaks-migrate down 5

Rolls back the last 5 migrations.