{"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,"search_vec":"'0.7.0':29 'agnost':11 'allow':68 'alreadi':74 'appli':75 'arbitrari':69 'avail':90 'base':17,65 'class':42 'connect':94 'custom':98 'databas':10,83,106 'database-agnost':9 'database-specif':82 'directori':47 'folder':50 'handl':93 'infrequ':36 'javascript':103 'jump':71 'latest':32 'librari':13,92 'manag':15 'migrat':2,5,16,46,55,95,102,104 'migrate-semv':1,4 'mongoos':88 'need':56 'node.js':12 'number':25 'option':99 'pass':100 'plugin':80,89 'provid':39 'rather':22 'reach':58 'releas':34 'requir':78 'run':52 'scan':44 'semver':3,6,19,105 'semvermigr':41 'sequenti':24 'skip':73 'specif':84 'stabl':33 'storag':85 'string':21 'target':60 'timestamp':27,64 'timestamp-bas':63 'tool':66 'track':96 'unlik':62 'updat':37 'version':20,28,49,61,70,76","created_at":"2026-05-01T13:47:21.836062+00:00","updated_at":"2026-05-01T13:47:21.836062+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/PDMLab/migrate-semver","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/migrate-semver","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","workflow","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-05-01","next_check":"2026-07-30","install_tag":null}}