migrate-semver

library0.7.0jsnpmunverified

migrate-semver is a database-agnostic Node.js library that manages migrations based on SemVer version strings rather than sequential numbers or timestamps. Version 0.7.0 is the latest stable release, with infrequent updates. It provides a SemVerMigration class that scans a migrations directory for versioned folders and runs only the migrations needed to reach a target version. Unlike timestamp-based tools, it allows arbitrary version jumps and skips already applied versions. It requires a plugin for database-specific storage, with a Mongoose plugin available. The library handles connections, migration tracking, and custom options passed to migrations.

database workflow devops

npm install migrate-semver

github ↗package ↗

INSTALL

IMPORT

SIG · MIGRATE-SEMVER

migrate-semver

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

SemVerMigration

✓ import { SemVerMigration } from 'migrate-semver'

✗ const { SemVerMigration } = require('migrate-semver')

Default export is not available; must use named import. CommonJS require with destructuring works.

migrate-semver

✓ const migrateSemver = require('migrate-semver')

✗ import migrateSemver from 'migrate-semver'

The package exports an object with SemVerMigration; no default export.

SemVerMigration (type)

✓ import type { SemVerMigration } from 'migrate-semver'

✗ import { SemVerMigration } from 'migrate-semver'

TypeScript users can import the constructor type for type annotations.

Shows how to instantiate SemVerMigration with a plugin, connect, check migration feasibility, and run an up migration to a specific SemVer version.

import { SemVerMigration } from 'migrate-semver'; import path from 'path'; import { plugin } from './my-plugin'; // your database plugin const migrate = new SemVerMigration({ migrationsDirectory: path.join(process.cwd(), 'migrations') }, plugin()); migrate.connect({}, (err) => { if (err) { console.error('Connection failed', err); process.exit(1); } const targetVersion = '0.3.0'; migrate.canMigrate({ version: targetVersion }, (err, canMigrate) => { if (err || !canMigrate) { console.error('Cannot migrate', err); process.exit(1); } migrate.up({ version: targetVersion }, (err) => { if (err) { console.error('Migration failed', err); process.exit(1); } console.log(`Successfully migrated to ${targetVersion}`); migrate.disconnect(); }); }); });

Debug

Known issues

gotchamigrationsDirectory must exist and contain semver-named folders; missing directory throws error

fix

Ensure the path exists and has at least one versioned subfolder (e.g., 0.1.0/).

affects: >=0.1.0

gotchaNo built-in rollback support; down migrations are not implemented

fix

Manually handle rollbacks outside of migrate-semver or implement a custom plugin with down logic.

affects: >=0.1.0

deprecatedCallback API is deprecated in favor of Promises; future versions may drop callback support

fix

Use promisify or switch to a Promise-based wrapper if available.

affects: >=0.6.0

gotchaPlugins are required; running without a plugin will throw 'plugin is not a function'

fix

Pass a valid plugin object with hasMigrationsTable, createMigrationsTable, etc.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Plugin is not a function

SemVerMigration constructor expects a plugin factory function, not an object.

fix

Wrap your plugin object in a function: plugin() returns the object.

Error: ENOENT: no such file or directory, scandir '.../migrations'

migrationsDirectory does not exist or is misconfigured.

fix

Create the directory with versioned subfolders or correct the path.

Error: No migration found for version 0.3.0

The version folder does not exist in the migrations directory, or the file index-up.js is missing.

fix

Ensure a folder named exactly '0.3.0' exists with an index-up.js file.

Upgrade

Version history

0.7.0latest on npm

Audit

Dependencies

semverrequiredUsed for parsing and comparing SemVer version strings

asyncrequiredUsed for control flow in migration execution

Agent activity

18 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/PDMLab/migrate-semver ↗

packagehttps://www.npmjs.com/package/migrate-semver ↗