{"id":16335,"library":"db-migrator","title":"DB Migrator","description":"db-migrator is a complete and easy-to-use database migration tool for Node.js projects, offering robust support for both PostgreSQL and MySQL databases. The current stable version is 2.4.0, and based on its active GitHub repository, it appears to maintain an ongoing, though not explicitly defined, release cadence. A key differentiator is its comprehensive feature set, including automatic migration from scratch to the latest version, granular step-by-step forward and backward migration capabilities, and the ability to migrate to a specific database version. It supports deep searching for migration scripts within subfolders and ensures data integrity through transactional \"all or nothing\" execution, where failures result in a full rollback. This tool builds upon its `pg-migrator` predecessor by introducing timestamp-based version IDs, storing execution times, allowing descriptive migration file names, favoring `npm` scripts for execution, and crucially, adding support for MySQL. It mandates Node.js v7.6.0 or higher due to its reliance on `async/await` syntax in its codebase.","status":"active","version":"2.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/Pajk/db-migrator","tags":["javascript","pg","postgres","postgresql","migrate","migration","migrator","pg-migrate","pg-migration"],"install":[{"cmd":"npm install db-migrator","lang":"bash","label":"npm"},{"cmd":"yarn add db-migrator","lang":"bash","label":"yarn"},{"cmd":"pnpm add db-migrator","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for PostgreSQL database connectivity.","package":"pg","optional":true},{"reason":"Required for MySQL database connectivity.","package":"promise-mysql","optional":true}],"imports":[],"quickstart":{"code":"{\n  \"scripts\": {\n    \"db-migrate\": \"db-migrate\",\n    \"db-rollback\": \"db-rollback\",\n    \"db-create\": \"db-create\",\n    \"db-status\": \"db-status\"\n  }\n}\n\n// .npmrc configuration for database connection\n// For PostgreSQL:\ndb_migrator_db_url=postgresql://mydatabase@localhost?ssl=false\n// For MySQL:\ndb_migrator_db_url=mysql://user:pass@host/db\n\n// Create a directory for your migration files (default is 'migrations')\n// mkdir migrations\n\n// Example usage via npm scripts:\n// To generate new migration files:\n// npm run db-create \"add_users_table\"\n\n// To apply all pending migrations:\n// npm run db-migrate\n\n// To rollback the most recent migration:\n// npm run db-rollback\n\n// To view the current migration status:\n// npm run db-status","lang":"javascript","description":"This quickstart demonstrates how to integrate db-migrator into your project using npm scripts, configure your database connection via .npmrc, and use the primary CLI commands for creating, migrating, rolling back, and checking migration status."},"warnings":[{"fix":"Upgrade your Node.js runtime environment to version 7.6.0 or later.","message":"db-migrator requires Node.js v7.6.0 or higher due to its use of `async/await` features. Older Node.js versions are not supported.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Remove all transaction control statements (e.g., `BEGIN`, `COMMIT`, `ROLLBACK`) from your migration SQL scripts.","message":"All migration scripts are executed within a single transaction scope. Explicit `BEGIN`, `COMMIT`, or `ROLLBACK` statements within your SQL migration files will interfere with `db-migrator`'s transactional behavior and should be avoided.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To alter a PostgreSQL ENUM type, a common workaround involves changing the column's type to `VARCHAR`, recreating the ENUM with the new values, and then changing the column's type back to use the updated ENUM. This sequence must be handled carefully within your migration script.","message":"PostgreSQL ENUM types cannot be altered directly within a transaction, which is how `db-migrator` executes scripts. Attempting to add values to an existing ENUM type will typically result in a transaction-related error.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Grant the necessary database privileges (e.g., `CREATE`, `ALTER`, `DROP` for schema changes, `SELECT`, `INSERT`, `UPDATE`, `DELETE` for data manipulation) to the database user configured for `db-migrator`.","message":"The database user specified in your `db_migrator_db_url` connection string must have sufficient permissions to execute all operations defined in your migration scripts. Insufficient privileges will lead to migration failures.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you have `db-migrator` installed locally (`npm install db-migrator`) and are running the commands through your `package.json` scripts, e.g., `npm run db-migrate`.","cause":"The `db-migrate` command-line utility is not directly available in your shell's PATH, or the npm scripts are not correctly set up.","error":"db-migrate: command not found"},{"fix":"Install the appropriate database driver for your chosen database: `npm install pg --save` for PostgreSQL, or `npm install promise-mysql --save` for MySQL.","cause":"The required database driver (PostgreSQL's `pg` or MySQL's `promise-mysql`) was not installed.","error":"Error: Cannot find module 'pg' (or 'promise-mysql')"},{"fix":"Manually create the database (e.g., `createdb your_database_name` for PostgreSQL, or `CREATE DATABASE your_database_name;` for MySQL) before attempting to run migrations.","cause":"The database specified in the `db_migrator_db_url` configuration does not exist on the database server.","error":"error: database \"your_database_name\" does not exist"},{"fix":"Review and update the permissions granted to the database user. Ensure the user has sufficient privileges for schema modifications and data operations on the target database.","cause":"The database user configured in your `db_migrator_db_url` lacks the necessary permissions to perform an operation defined in one of your migration scripts.","error":"ERROR: permission denied for relation some_table (PostgreSQL) / Access denied for user 'user'@'host' to database 'db' (MySQL)"}],"ecosystem":"npm"}