db-migrate

Common errors

• Error: Cannot find module 'db-migrate-<driver>'

  cause The required database driver package (e.g., 'db-migrate-pg' for PostgreSQL) is not installed or incorrectly named.
  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.

• Error: No database config found!

  cause db-migrate could not find a `database.json` file in the current working directory or the directory specified by the `cwd` option.
  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.

• Error: db-migrate connection error. Please check your database credentials or connection string.

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

• TypeError: db.createTable is not a function (or similar for other DBMigrate API methods)

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

Warnings

• gotcha 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.
  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.
• gotcha 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.
  Fix: Install the appropriate driver: `npm install db-migrate-<driver-name>`. For example, `npm install db-migrate-pg` for PostgreSQL.
• gotcha 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.
  Fix: Create a `database.json` in your project root or pass `{ cwd: path.resolve(__dirname, 'path/to/config') }` to `DBMigrate.getInstance()`.
• deprecated 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.
  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.

Install

• npm install db-migrate npm
• yarn add db-migrate yarn
• pnpm add db-migrate pnpm

Imports

• DBMigrate
  wrong:

  import DBMigrate from 'db-migrate';

  correct:

  const DBMigrate = require('db-migrate');

  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.
• getInstance (default)
  wrong:

  const dbmigrate = new DBMigrate();

  correct:

  const dbmigrate = DBMigrate.getInstance(true);

  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()`.
• getInstance (custom options)
  wrong:

  const dbmigrate = DBMigrate.getInstance({ cwd: __dirname });

  correct:

  const dbmigrate = DBMigrate.getInstance(false, { cwd: __dirname, env: 'production' });

  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.

Quickstart

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.

import DBMigrate from 'db-migrate';
import path from 'path';
import fs from 'fs';

async function runExampleMigrations() {
  const migrationsDirPath = path.join(__dirname, 'migrations');
  // Ensure migrations directory exists for db-migrate to scan
  if (!fs.existsSync(migrationsDirPath)) {
    fs.mkdirSync(migrationsDirPath);
  }

  // Create a simple migration file (up and down)
  const migrationName = `create-test-table-${Date.now()}`;
  const migrationFilePath = path.join(migrationsDirPath, `${migrationName}.js`);
  const migrationContent = `
    'use strict';
    var dbm;
    var type;
    var seed;

    exports.setup = function(options) {
      dbm = options.dbmigrate;
      type = options.type;
      seed = options.seed;
    };

    exports.up = function(db) {
      console.log('Running UP migration: ${migrationName}');
      return db.createTable('test_table', {
        id: { type: 'int', primaryKey: true, autoIncrement: true },
        value: { type: 'string', length: 255 }
      });
    };

    exports.down = function(db) {
      console.log('Running DOWN migration: ${migrationName}');
      return db.dropTable('test_table');
    };

    exports._meta = {
      "version": 1
    };
  `;
  fs.writeFileSync(migrationFilePath, migrationContent);
  console.log(`Generated migration file: ${migrationName}.js`);

  // Create a minimal database.json for an in-memory SQLite database
  const configPath = path.join(__dirname, 'database.json');
  const dbConfig = {
    "dev": {
      "driver": "sqlite3",
      "filename": ":memory:", // Use in-memory SQLite for easy testing
      "host": "localhost", // Required by some db-migrate internals even for sqlite3
      "database": "testdb" // Required by some db-migrate internals
    }
  };
  fs.writeFileSync(configPath, JSON.stringify(dbConfig, null, 2));
  console.log('Generated database.json for in-memory SQLite.');

  let dbmigrate;
  try {
    // Initialize db-migrate with options
    dbmigrate = DBMigrate.getInstance(true, {
      cwd: __dirname, // Important for db-migrate to find config and migrations
      env: 'dev'
    });

    console.log('\n--- Running UP migrations ---');
    await dbmigrate.up();
    console.log('UP migrations complete.');

    console.log('\n--- Running DOWN migrations ---');
    await dbmigrate.down();
    console.log('DOWN migrations complete.');

  } catch (error) {
    console.error('Migration failed:', error);
    process.exit(1);
  } finally {
    // Cleanup generated files
    if (fs.existsSync(migrationFilePath)) {
      fs.unlinkSync(migrationFilePath);
    }
    if (fs.existsSync(configPath)) {
      fs.unlinkSync(configPath);
    }
    if (fs.existsSync(migrationsDirPath)) {
      fs.rmdirSync(migrationsDirPath, { recursive: true });
    }
  }
}

runExampleMigrations();