migrate-mysql

library0.4.0jsnpmunverified

A lightweight migration tool for MySQL databases that runs SQL files sequentially. Current stable version is 0.4.0. Designed for simplicity—no down migrations, just numbered SQL files in a directory. Integrates via CLI or programmatic API. Differentiates by being minimal and easy to set up compared to more complex migration frameworks like db-migrate or node-migrate.

devops database

npm install migrate-mysql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MIGRATE-MYSQL

migrate-mysql

devopsjavascriptv0.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import migrate from 'mysql-migrate'

✗ const migrate = require('mysql-migrate')

Package is ESM-only from v0.4.0.

migrate

✓ import { migrate } from 'mysql-migrate'

✗ const { migrate } = require('mysql-migrate')

Named export for the migrate function, preferred for programmatic usage.

MigrationsOptions

✓ import type { MigrationsOptions } from 'mysql-migrate'

TypeScript type for configuration options, available since v0.4.0.

Shows how to run migrations programmatically using environment variables for database credentials.

import { migrate } from 'mysql-migrate'; import dotenv from 'dotenv'; dotenv.config(); const options = { database: process.env.DB_NAME ?? 'mydb', user: process.env.DB_USER ?? 'root', password: process.env.DB_PASS ?? '', host: process.env.DB_HOST ?? 'localhost', port: Number(process.env.DB_PORT ?? 3306), migrationsDir: './migrations', }; await migrate(options); console.log('Migrations complete');

Debug

Known issues

breakingSince v0.4.0, the package is ESM-only. Using require() will cause a runtime error.

fix

Switch to ESM by adding 'type': 'module' to your package.json or use .mjs extension.

affects: >=0.4.0

breakingThe CLI command is 'mysql-migrate', but the npm package is 'mysql-migrate'. Note the hyphen.

fix

Run 'npx mysql-migrate' (with hyphen) not 'migrate-mysql'.

affects: all

deprecatedThe function 'migrate' no longer accepts a callback; it returns a Promise since v0.4.0.

fix

Use async/await or .then() instead of callback pattern.

affects: >=0.4.0

gotchaMigrations are executed in numeric order based on filenames. Non-numeric prefixes may cause unexpected ordering.

fix

Use leading zeros (e.g., 001, 002) to ensure correct ordering.

affects: all

gotchaNo down migrations. Once a migration is run, it cannot be reverted via this tool.

fix

Manually write reverse SQL scripts if needed, or consider using a different tool.

affects: all

gotchaDatabase credentials must be provided via environment variables or options; no default .env handling if dotenv not used.

fix

Use dotenv or explicitly pass all options to migrate().

affects: <0.4.0

Errors

Common errors & fixes

Error: Cannot find module 'mysql-migrate'

Package not installed or incorrect import path.

fix

Install with 'npm install mysql-migrate --save-dev' and import as 'import migrate from 'mysql-migrate'.

TypeError: migrate is not a function

Using default import but the package requires named import in some versions.

fix

Use 'import { migrate } from 'mysql-migrate' instead of default import.

Error: ENOENT: no such file or directory, open './migrations/1_create-table.sql'

Migrations directory not found or path incorrect.

fix

Ensure the migrations folder exists at the specified path (default './migrations').

Error: ER_ACCESS_DENIED_ERROR: Access denied for user

Database credentials are wrong or missing.

fix

Check your .env file or options object: DB_USER, DB_PASS, DB_HOST, etc.

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

mysqlrequiredMySQL database driver for Node.js

dotenvoptionalUsed for loading database credentials from .env file

Agent activity

10 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/jimmybisenius/migrate-mysql ↗

packagemigrate-mysql ↗

homepagehttps://github.com/jimmybisenius/migrate-mysql#readme ↗