Registry / database / mysql-node-migrator

mysql-node-migrator

library1.3.0jsnpmunverified

mysql-node-migrator is a lightweight database migration tool for Node.js and MySQL, currently at version 1.3.0 (stable, low release cadence). It manages SQL change scripts in a folder, tracking executed migrations in a `migration_schema` table. Unlike more complex tools like Knex or Sequelize migrations, it focuses on simplicity: plain SQL files named with a version prefix (e.g., V1__init.sql), automatic execution order, and no rollback support. It wraps promise-mysql (which wraps mysqljs/mysql) and works only with `.createConnection()`, limiting advanced connection pooling. Best suited for small projects or teams wanting minimal migration overhead.

database devops

npm install mysql-node-migrator

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MYSQL-NODE-MIGRATO

mysql-node-migrator

databasejavascriptv1.3.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 (migrator)

✓ import migrator from 'mysql-node-migrator';

✗ const migrator = require('mysql-node-migrator'); // CJS not supported; throws error

The package is ESM-only; do not use require(). The default export is a function that takes connection options and migration options.

Shows how to import and run migrations with mysql-node-migrator using ESM syntax, environment variables for credentials, and a migrations folder.

import migrator from 'mysql-node-migrator'; const connectionOptions = { host: process.env.MYSQL_HOST ?? 'localhost', user: process.env.MYSQL_USER ?? 'root', password: process.env.MYSQL_PASSWORD ?? '', database: process.env.MYSQL_DB ?? 'test', }; const options = { folder: 'sql_migrations', loggingFunction: console, logging: true, }; migrator(connectionOptions, options) .then(() => { console.log('Migrations completed successfully'); }) .catch((err) => { console.error('Migration failed:', err); });

Debug

Known issues

breakingESM-only package; CommonJS require() will fail.

fix

Use import syntax or set type: module in package.json.

affects: >=1.0.0

gotchaOnly supports .createConnection(); connection pooling (e.g., .createPool) is not available.

fix

Use a different migration library if you need connection pooling.

affects: >=1.0.0

gotchaMigrations are SQL files only (no JavaScript); must follow V{version}__{name}.sql naming convention.

fix

Name files accordingly, e.g., V1__init.sql, V2__add_users.sql.

affects: >=1.0.0

gotchaNo rollback support; migrations run only forward.

fix

Manually write reverse SQL scripts or use another tool for rollbacks.

affects: >=1.0.0

gotchaPromises only; no async/await or callback support natively (though you can wrap with async/await).

fix

Use .then().catch() or wrap in async function using await.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/mysql-node-migrator/index.js from /path/to/yourfile.js not supported.

Trying to use require() on an ESM-only package.

fix

Change to import syntax: import migrator from 'mysql-node-migrator';.

TypeError: migrator is not a function

Default import used incorrectly, or import style mismatch.

fix

Ensure you use default import: import migrator from 'mysql-node-migrator'; (no curly braces).

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

promise-mysqlrequiredCore dependency for MySQL promise-based connection. Note: promise-mysql is a thin wrapper around mysqljs/mysql; transitive dependency.

mysqlrequiredTransitive dependency via promise-mysql. This is the raw mysql driver; version conflicts can arise.

Agent activity

12 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/patrikmolsson/mysql-node-migrator ↗

packagemysql-node-migrator ↗

homepagehttps://github.com/patrikmolsson/mysql-node-migrator#readme ↗