pg-bump

library5.0.0jsnpmunverified

pg-bump is a CLI tool (v5.0.0) for managing PostgreSQL schema migrations written in plain SQL. It is ESM-only (since v4), powered by the `postgres` library instead of `pg`, and designed for use in package.json scripts. Key differentiators: single-transaction migrations by default, advisory locking, and file-based migration definitions split into up/down SQL files. It supports make, status, up, down commands. Requires Node >=14.

database

npm install pg-bump

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-BUMP

pg-bump

databasejavascriptv5.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

pg-bump (CLI)

✓ npx pg-bump [command]

✗ require('pg-bump') for use as a library

pg-bump is primarily a CLI tool, not a library. Importing programmatically is unsupported.

Initialize pg-bump, create a migration, write SQL, and apply it.

npx pg-bump init npx pg-bump make create_users_table cat > migrations/*_create_users_table/up.sql <<SQL CREATE TABLE users ( id SERIAL PRIMARY KEY, name TEXT NOT NULL ); SQL cat > migrations/*_create_users_table/down.sql <<SQL DROP TABLE IF EXISTS users; SQL npx pg-bump up

Debug

Known issues

breakingv4 dropped CommonJS support; switched from `pg` to `@porsager/postgres`.

fix

Ensure your environment supports ESM. Update connection logic if you relied on `pg` defaults (e.g., `DATABASE_URL` env var).

affects: >=4.0.0

gotchaMigration files must be named with a Unix timestamp prefix (e.g., `1617000000_create_users_table/up.sql`).

fix

Use `npx pg-bump make <name>` to generate the correct directory structure.

affects: >=0.0.0

gotchaTransactions wrap all migrations by default; DDL statements like CREATE/DROP may behave differently in transactions depending on PostgreSQL version.

fix

Use `--no-transaction` flag if issues arise with transactional DDL.

affects: >=0.0.0

breakingv3 was CommonJS; v4+ is ESM-only.

fix

Update to Node.js >=14. If you relied on importing pg-bump programmatically as CJS, you must migrate to ESM or use dynamic import().

affects: >=4.0.0

Errors

Common errors & fixes

Error: Cannot find module '@porsager/postgres'

Missing dependency after upgrading to v4+ without reinstalling.

fix

Run `npm install @porsager/postgres`

Error: Must use import to load ES Module

Attempting to require('pg-bump') in a CommonJS file.

fix

Use `import('pg-bump')` dynamic import or switch to ESM.

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

@porsager/postgresrequiredPostgreSQL client library used for all database connections (replaced 'pg' in v4)

commanderrequiredCommand-line argument parser

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/thebearingedge/pg-bump ↗

packagepg-bump ↗

homepagehttps://github.com/thebearingedge/pg-bump#readme ↗