{"id":10717,"library":"db-migrate","title":"db-migrate","description":"db-migrate is a robust database migration framework for Node.js, designed to manage schema changes across various SQL database systems. Its current stable version is 0.11.14, released in late 2019, with a `v1.0.0-beta.0` also from 2019. The project is currently in a maintenance phase, with ongoing commits to the GitHub repository but no new stable releases for several years. It supports a wide array of databases including PostgreSQL, MySQL, SQLite, and MSSQL, requiring separate driver packages for each. A key differentiator is its dual interface: a powerful command-line tool for everyday use and a comprehensive programmatic API for deeper integration into application deployment and testing workflows. It ensures transactional integrity for migrations and offers clear 'up' and 'down' scripts for reliable schema evolution and rollback capabilities.","status":"maintenance","version":"0.11.14","language":"javascript","source_language":"en","source_url":"https://github.com/db-migrate/node-db-migrate","tags":["javascript","database","db","migrate","migration","sqlite","mysql","pg","postgre"],"install":[{"cmd":"npm install db-migrate","lang":"bash","label":"npm"},{"cmd":"yarn add db-migrate","lang":"bash","label":"yarn"},{"cmd":"pnpm add db-migrate","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for PostgreSQL database support.","package":"db-migrate-pg","optional":true},{"reason":"Required for MySQL database support.","package":"db-migrate-mysql","optional":true},{"reason":"Required for SQLite database support.","package":"db-migrate-sqlite3","optional":true},{"reason":"Required for Microsoft SQL Server database support.","package":"db-migrate-mssql","optional":true}],"imports":[{"note":"db-migrate is a CommonJS module. Direct ES module `import` syntax is not officially supported and might require transpilation or dynamic `import()` in pure ESM environments.","wrong":"import DBMigrate from 'db-migrate';","symbol":"DBMigrate","correct":"const DBMigrate = require('db-migrate');"},{"note":"The primary way to interact with db-migrate programmatically is by obtaining an instance through `getInstance()`. Passing `true` as the first argument loads a default instance with default options, typically reading `database.json` from `process.cwd()`.","wrong":"const dbmigrate = new DBMigrate();","symbol":"getInstance (default)","correct":"const dbmigrate = DBMigrate.getInstance(true);"},{"note":"To create a custom db-migrate instance with specific options (e.g., custom current working directory `cwd` or environment `env`), pass `false` as the first argument to `getInstance()`, followed by an options object.","wrong":"const dbmigrate = DBMigrate.getInstance({ cwd: __dirname });","symbol":"getInstance (custom options)","correct":"const dbmigrate = DBMigrate.getInstance(false, { cwd: __dirname, env: 'production' });"}],"quickstart":{"code":"import DBMigrate from 'db-migrate';\nimport path from 'path';\nimport fs from 'fs';\n\nasync function runExampleMigrations() {\n  const migrationsDirPath = path.join(__dirname, 'migrations');\n  // Ensure migrations directory exists for db-migrate to scan\n  if (!fs.existsSync(migrationsDirPath)) {\n    fs.mkdirSync(migrationsDirPath);\n  }\n\n  // Create a simple migration file (up and down)\n  const migrationName = `create-test-table-${Date.now()}`;\n  const migrationFilePath = path.join(migrationsDirPath, `${migrationName}.js`);\n  const migrationContent = `\n    'use strict';\n    var dbm;\n    var type;\n    var seed;\n\n    exports.setup = function(options) {\n      dbm = options.dbmigrate;\n      type = options.type;\n      seed = options.seed;\n    };\n\n    exports.up = function(db) {\n      console.log('Running UP migration: ${migrationName}');\n      return db.createTable('test_table', {\n        id: { type: 'int', primaryKey: true, autoIncrement: true },\n        value: { type: 'string', length: 255 }\n      });\n    };\n\n    exports.down = function(db) {\n      console.log('Running DOWN migration: ${migrationName}');\n      return db.dropTable('test_table');\n    };\n\n    exports._meta = {\n      \"version\": 1\n    };\n  `;\n  fs.writeFileSync(migrationFilePath, migrationContent);\n  console.log(`Generated migration file: ${migrationName}.js`);\n\n  // Create a minimal database.json for an in-memory SQLite database\n  const configPath = path.join(__dirname, 'database.json');\n  const dbConfig = {\n    \"dev\": {\n      \"driver\": \"sqlite3\",\n      \"filename\": \":memory:\", // Use in-memory SQLite for easy testing\n      \"host\": \"localhost\", // Required by some db-migrate internals even for sqlite3\n      \"database\": \"testdb\" // Required by some db-migrate internals\n    }\n  };\n  fs.writeFileSync(configPath, JSON.stringify(dbConfig, null, 2));\n  console.log('Generated database.json for in-memory SQLite.');\n\n  let dbmigrate;\n  try {\n    // Initialize db-migrate with options\n    dbmigrate = DBMigrate.getInstance(true, {\n      cwd: __dirname, // Important for db-migrate to find config and migrations\n      env: 'dev'\n    });\n\n    console.log('\\n--- Running UP migrations ---');\n    await dbmigrate.up();\n    console.log('UP migrations complete.');\n\n    console.log('\\n--- Running DOWN migrations ---');\n    await dbmigrate.down();\n    console.log('DOWN migrations complete.');\n\n  } catch (error) {\n    console.error('Migration failed:', error);\n    process.exit(1);\n  } finally {\n    // Cleanup generated files\n    if (fs.existsSync(migrationFilePath)) {\n      fs.unlinkSync(migrationFilePath);\n    }\n    if (fs.existsSync(configPath)) {\n      fs.unlinkSync(configPath);\n    }\n    if (fs.existsSync(migrationsDirPath)) {\n      fs.rmdirSync(migrationsDirPath, { recursive: true });\n    }\n  }\n}\n\nrunExampleMigrations();","lang":"javascript","description":"This quickstart demonstrates the programmatic use of db-migrate to define and run both 'up' and 'down' migrations against an in-memory SQLite database, cleaning up all generated files afterward."},"warnings":[{"fix":"For CommonJS, use `const DBMigrate = require('db-migrate');`. For ESM, consider `import('./path/to/db-migrate.js').then(mod => mod.default)` or ensure your bundler handles CommonJS interoperability.","message":"db-migrate is primarily a CommonJS module. While it can be used in ESM projects, direct `import DBMigrate from 'db-migrate'` might require build tool configuration or dynamic `import()` for seamless integration in a pure ESM environment.","severity":"gotcha","affected_versions":">=0.11.0"},{"fix":"Install the appropriate driver: `npm install db-migrate-<driver-name>`. For example, `npm install db-migrate-pg` for PostgreSQL.","message":"Each database type (PostgreSQL, MySQL, SQLite, MSSQL) requires its own `db-migrate-*` driver package (e.g., `db-migrate-pg`, `db-migrate-mysql`). Forgetting to install the correct driver for your configured database will lead to runtime errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Create a `database.json` in your project root or pass `{ cwd: path.resolve(__dirname, 'path/to/config') }` to `DBMigrate.getInstance()`.","message":"Configuration for db-migrate is typically done via a `database.json` file. Ensure this file is correctly located in your project's root or specified via the `cwd` option when using the programmatic API, otherwise, db-migrate might fail to initialize or connect to the database.","severity":"gotcha","affected_versions":"all"},{"fix":"Be aware that using `db-migrate` with current Node.js versions might uncover compatibility issues not covered by older test suites. Monitor the GitHub repository for updates and test thoroughly.","message":"The `v1.0.0-beta.0` release from 2019 was a beta and the project has not released a stable v1.0.0 since. While active, the core functionality resides in the 0.11.x branch, and future breaking changes are possible if a stable v1 is ever released.","severity":"deprecated","affected_versions":">=0.11.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the missing driver: `npm install db-migrate-<driver>` (e.g., `npm install db-migrate-pg`). Ensure the driver name in `database.json` matches the installed package suffix.","cause":"The required database driver package (e.g., 'db-migrate-pg' for PostgreSQL) is not installed or incorrectly named.","error":"Error: Cannot find module 'db-migrate-<driver>'"},{"fix":"Create a `database.json` file in your project root or ensure the `cwd` option for `DBMigrate.getInstance()` points to the correct directory where `database.json` resides.","cause":"db-migrate could not find a `database.json` file in the current working directory or the directory specified by the `cwd` option.","error":"Error: No database config found!"},{"fix":"Verify all connection details in your `database.json` for the selected environment. Ensure the database server is running and accessible from the machine running db-migrate.","cause":"db-migrate failed to establish a connection to the database. This is typically due to incorrect credentials, host, port, database name in `database.json`, or the database server not running/being inaccessible.","error":"Error: db-migrate connection error. Please check your database credentials or connection string."},{"fix":"Ensure your migration files correctly define `exports.setup = function(options) { dbm = options.dbmigrate; ... };` and that `exports.up = function(db) { ... };` and `exports.down = function(db) { ... };` use the `db` object passed to them, which contains the API methods like `createTable`, `addColumn`, etc.","cause":"This error usually indicates an issue with how the migration file `exports.up` or `exports.down` is structured, specifically if the `db` object passed to these functions is not being correctly used.","error":"TypeError: db.createTable is not a function (or similar for other DBMigrate API methods)"}],"ecosystem":"npm"}