migrate-semver

0.7.0 verified Fri May 01 auth: no javascript

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.

Common errors

error Error: Plugin is not a function ↓

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

fix

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

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

cause migrationsDirectory does not exist or is misconfigured.

fix

Create the directory with versioned subfolders or correct the path.

error Error: No migration found for version 0.3.0 ↓

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

Warnings

gotcha migrationsDirectory 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/).

gotcha No 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.

deprecated Callback 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.

gotcha Plugins are required; running without a plugin will throw 'plugin is not a function' ↓

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

Install

npm install migrate-semver

yarn add migrate-semver

pnpm add migrate-semver

Imports

SemVerMigration
wrong
```
const { SemVerMigration } = require('migrate-semver')
```
correct
```
import { SemVerMigration } from 'migrate-semver'
```
Default export is not available; must use named import. CommonJS require with destructuring works.
migrate-semver
wrong
```
import migrateSemver from 'migrate-semver'
```
correct
```
const migrateSemver = require('migrate-semver')
```
The package exports an object with SemVerMigration; no default export.

SemVerMigration (type)

wrong

import { SemVerMigration } from 'migrate-semver'

correct

import type { SemVerMigration } from 'migrate-semver'

TypeScript users can import the constructor type for type annotations.

Quickstart

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();
    });
  });
});