ts-mysql-migrate

library1.1.2jsnpmunverified

A TypeScript-based MySQL migration tool supporting mysql and mysql2 drivers. Current stable version is 1.1.2, published via npm. It provides programmatic API for upgrade, downgrade, reset, and initialization of migration scripts. Features include timestamp-based migration naming to avoid branch conflicts, strict ordering via environment variables (MIGRATIONS_STRICT_ORDER, MIGRATIONS_NUMERIC_ORDER), and dotenv support for configuration. Key differentiators: first-class TypeScript support (built-in types), dual driver compatibility, and flexible ordering control.

database

npm install ts-mysql-migrate

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TS-MYSQL-MIGRATE

ts-mysql-migrate

databasejavascriptv1.1.2

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.

Migrator

✓ import { Migrator } from 'ts-mysql-migrate'

✗ import Migrator from 'ts-mysql-migrate'

Migrator is a named export, not default. The library exports Migrator class.

MigratorOptions

✓ import { MigratorOptions } from 'ts-mysql-migrate'

✗ import { Options } from 'ts-mysql-migrate'

Options interface is exported as MigratorOptions. TypeScript users should import the type.

initialize

✓ import { Migrator } from 'ts-mysql-migrate'; const migrator = new Migrator(options); await migrator.initialize()

✗ import { initialize } from 'ts-mysql-migrate'

initialize is a method on Migrator instance, not a standalone export.

Shows full initialization and migration execution with environment variable configuration.

import { Migrator } from 'ts-mysql-migrate'; const migrator = new Migrator({ dbConfig: { host: process.env.DB_HOST ?? 'localhost', port: Number(process.env.DB_PORT) ?? 3306, user: process.env.DB_USER ?? 'root', password: process.env.DB_PASSWORD ?? '', database: process.env.DB_DATABASE ?? 'test', }, migrationFolder: './migrations', strictOrder: true, }); async function runMigrations() { await migrator.initialize(); await migrator.up(); console.log('Migrations complete'); await migrator.destroy(); } runMigrations().catch(console.error);

Debug

Known issues

gotchaEnvironment variable MIGRATIONS_STRICT_ORDER defaults to true in production (NODE_ENV='production'), which may cause unexpected failures if migration scripts are not strictly ordered.

fix

Set MIGRATIONS_STRICT_ORDER=false or pass strictOrder: false to constructor explicitly in development.

affects: >=1.0.0

gotchaMigration scripts must export 'upgrade' and 'downgrade' functions exactly, any other export names will be ignored.

fix

Ensure each migration file exports async functions named upgrade and downgrade.

affects: >=1.0.0

breakingIn v1.1.0, timestamp-based migration naming was introduced; older scripts with numeric-only names may not be compatible if MIGRATIONS_NUMERIC_ORDER is true.

fix

Either set MIGRATIONS_NUMERIC_ORDER=false or rename old migrations to use timestamps.

affects: >=1.1.0

deprecatedThe mysql driver (mysqljs) is supported but only in v1.x; v2 plans to deprecate it in favor of mysql2.

fix

Switch to mysql2 driver for future compatibility.

affects: >=1.0.0 <2.0.0

Errors

Common errors & fixes

Cannot find module 'dotenv'

dotenv package is not installed but .env file is present or MIGRATION_FOLDER env var is used.

fix

Install dotenv: npm install dotenv

Access denied for user 'user'@'host' to database 'test'

Incorrect database credentials or insufficient privileges.

fix

Verify DB_USER, DB_PASSWORD, DB_HOST, DB_PORT, DB_DATABASE environment variables.

TypeError: migrator.initialize is not a function

Migrator is imported incorrectly as default import instead of named import.

fix

Use import { Migrator } from 'ts-mysql-migrate'

Migration file 1-init_db.ts does not export upgrade function

Migration script missing required upgrade export.

fix

Add export async function upgrade(queryFn) { ... } to the migration file.

Upgrade

Version history

1.1.2latest on npm

Audit

Dependencies

mysql2optionalMySQL driver used for database connections (also supports mysql package)

dotenvoptionalRequired if using .env file for environment variable configuration

Agent activity

17 hits · last 30 days

node