{"id":25940,"library":"migrate-semver","title":"migrate-semver","description":"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.","status":"active","version":"0.7.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/PDMLab/migrate-semver","tags":["javascript","migration","semver","database"],"install":[{"cmd":"npm install migrate-semver","lang":"bash","label":"npm"},{"cmd":"yarn add migrate-semver","lang":"bash","label":"yarn"},{"cmd":"pnpm add migrate-semver","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for parsing and comparing SemVer version strings","package":"semver","optional":false},{"reason":"Used for control flow in migration execution","package":"async","optional":false}],"imports":[{"note":"Default export is not available; must use named import. CommonJS require with destructuring works.","wrong":"const { SemVerMigration } = require('migrate-semver')","symbol":"SemVerMigration","correct":"import { SemVerMigration } from 'migrate-semver'"},{"note":"The package exports an object with SemVerMigration; no default export.","wrong":"import migrateSemver from 'migrate-semver'","symbol":"migrate-semver","correct":"const migrateSemver = require('migrate-semver')"},{"note":"TypeScript users can import the constructor type for type annotations.","wrong":"import { SemVerMigration } from 'migrate-semver'","symbol":"SemVerMigration (type)","correct":"import type { SemVerMigration } from 'migrate-semver'"}],"quickstart":{"code":"import { SemVerMigration } from 'migrate-semver';\nimport path from 'path';\nimport { plugin } from './my-plugin'; // your database plugin\n\nconst migrate = new SemVerMigration({\n  migrationsDirectory: path.join(process.cwd(), 'migrations')\n}, plugin());\n\nmigrate.connect({}, (err) => {\n  if (err) {\n    console.error('Connection failed', err);\n    process.exit(1);\n  }\n\n  const targetVersion = '0.3.0';\n\n  migrate.canMigrate({ version: targetVersion }, (err, canMigrate) => {\n    if (err || !canMigrate) {\n      console.error('Cannot migrate', err);\n      process.exit(1);\n    }\n\n    migrate.up({ version: targetVersion }, (err) => {\n      if (err) {\n        console.error('Migration failed', err);\n        process.exit(1);\n      }\n      console.log(`Successfully migrated to ${targetVersion}`);\n      migrate.disconnect();\n    });\n  });\n});","lang":"typescript","description":"Shows how to instantiate SemVerMigration with a plugin, connect, check migration feasibility, and run an up migration to a specific SemVer version."},"warnings":[{"fix":"Ensure the path exists and has at least one versioned subfolder (e.g., 0.1.0/).","message":"migrationsDirectory must exist and contain semver-named folders; missing directory throws error","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Manually handle rollbacks outside of migrate-semver or implement a custom plugin with down logic.","message":"No built-in rollback support; down migrations are not implemented","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use promisify or switch to a Promise-based wrapper if available.","message":"Callback API is deprecated in favor of Promises; future versions may drop callback support","severity":"deprecated","affected_versions":">=0.6.0"},{"fix":"Pass a valid plugin object with hasMigrationsTable, createMigrationsTable, etc.","message":"Plugins are required; running without a plugin will throw 'plugin is not a function'","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Wrap your plugin object in a function: plugin() returns the object.","cause":"SemVerMigration constructor expects a plugin factory function, not an object.","error":"Error: Plugin is not a function"},{"fix":"Create the directory with versioned subfolders or correct the path.","cause":"migrationsDirectory does not exist or is misconfigured.","error":"Error: ENOENT: no such file or directory, scandir '.../migrations'"},{"fix":"Ensure a folder named exactly '0.3.0' exists with an index-up.js file.","cause":"The version folder does not exist in the migrations directory, or the file index-up.js is missing.","error":"Error: No migration found for version 0.3.0"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}