pg-patcher

library0.5.2jsnpmunverified

A transaction-based PostgreSQL schema migration helper for node-postgres (pg). Current stable version is 0.5.2, with no active release cadence (last update years ago). Unlike file-based patch trackers, pg-patcher stores the patch level inside a database table, ensuring consistency across multiple servers. Patch files are plain SQL with a naming convention (patch-{from}-{to}.sql), and migrations can go forward or backward. Notable: first patch must create the property table and set the initial level. Cannot be used with pool connections—requires a single client with an open connection.

database

npm install pg-patcher

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-PATCHER

pg-patcher

databasejavascriptv0.5.2

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.

default

✓ import pgpatcher from 'pg-patcher'

✗ const pgpatcher = require('pg-patcher')

Package uses CommonJS; both import and require work in Node ESM/CJS, but ESM import requires the module to have a default export.

require

✓ const pgpatcher = require('pg-patcher')

✗ import { pgpatcher } from 'pg-patcher'

Named import does not exist; only default export is provided.

cli

✓ npx pg-patcher --host localhost --database mydb --user myuser --level 2

✗ pg-patcher --host localhost --database mydb --user myuser --patch-level 2

CLI flag is --level, not --patch-level. Also requires PG environment variables or command-line args.

Connects to PostgreSQL and applies patch files to migrate database to version 2.

const pg = require('pg') const pgpatcher = require('pg-patcher') const client = new pg.Client({ user: process.env.DB_USER ?? 'postgres', database: process.env.DB_NAME ?? 'mydb', }) client.connect(err => { if (err) { console.error('Connection error:', err) return } // Patch to level 2 (expects db/patch-0-1.sql, patch-1-2.sql exist) pgpatcher(client, 2, { dir: 'db', prefix: 'patch' }, err => { if (err) { console.error('Patch error:', err) } else { console.log('Patched to level 2') } client.end() }) })

Debug

Known issues

gotchaYou must create a property table and set patch level in the first forward patch (patch-0-1.sql); otherwise the system track will be broken.

fix

In patch-0-1.sql: CREATE TABLE property (key TEXT PRIMARY KEY, value TEXT); INSERT INTO property(key, value) VALUES('patch', 1);

affects: >=0.0.0

gotchapg-patcher uses a single client connection; it does not work with pg.Pool. You must pass a connected client instance.

fix

Create a pg.Client, call client.connect() before passing to pgpatcher.

affects: >=0.0.0

gotchaPatch files must follow the naming pattern 'patch-{from}-{to}.sql' (e.g., patch-0-1.sql). Files with different prefixes or extensions are ignored.

fix

Name files exactly as expected, or set custom prefix via options.

affects: >=0.0.0

deprecatedThe package is no longer actively maintained; last release 0.5.2 (circa 2017). No updates for modern pg versions or ES module support.

fix

Consider alternatives like node-pg-migrate or postgrator for active development.

affects: >=0.0.0

Errors

Common errors & fixes

Uncaught Error: property table does not exist

The first forward patch (patch-0-1.sql) did not create the property table.

fix

Ensure db/patch-0-1.sql contains CREATE TABLE property (...) and INSERT INTO property VALUES('patch', 1).

Error: connect ECONNREFUSED

PostgreSQL server is not running or connection details are incorrect.

fix

Start PostgreSQL or correct host/port/user/database in client configuration.

Error: Cannot find module 'pg-patcher'

pg-patcher is not installed or node_modules is missing.

fix

Run npm install pg-patcher (or yarn add pg-patcher).

Upgrade

Version history

0.5.2latest on npm

Audit

Dependencies

pgrequiredPeer dependency: interacts with node-postgres client

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/chilts/pg-patcher ↗

packagepg-patcher ↗

homepagehttps://github.com/chilts/pg-patcher/ ↗