pg-differ

library3.5.1jsnpmunverified

pg-differ is a Node.js migration tool for PostgreSQL that compares database schemas (tables and sequences) against a metadata definition and generates SQL migration scripts. It supports updating columns without data loss, synchronizing indexes/constraints, and auto-generating schemas from existing database objects. The current stable version is 3.5.1, with releases following semantic versioning. Ships TypeScript types. Requires Node >=10.4.0. Key differentiator: declarative schema definition rather than imperative migration steps, offering both a CLI and programmatic API for safe, reversible database migrations.

database devops

npm install pg-differ

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-DIFFER

pg-differ

databasejavascriptv3.5.1

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.

differ

✓ import { differ } from 'pg-differ'

✗ const differ = require('pg-differ')

ESM import is recommended since v3.0.0; CommonJS require still works but ESM is the primary way.

Schema

✓ import { Schema } from 'pg-differ'

✗ var Schema = require('pg-differ').Schema

Named export for defining schemas. TypeScript-compatible.

SyncOptions

✓ import type { SyncOptions } from 'pg-differ'

✗ import { SyncOptions } from 'pg-differ' (if using as type only, use 'import type')

Type export, available in TypeScript definitions.

Connects to PostgreSQL, compares current database against a declared schema (table 'users'), and logs generated migration SQL.

import { differ } from 'pg-differ'; import pg from 'pg'; const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL ?? 'postgres://user:pass@localhost/mydb' }); const client = await pool.connect(); try { const changes = await differ(client, { schema: [ { type: 'table', name: 'users', columns: [ { name: 'id', type: 'serial', primaryKey: true }, { name: 'email', type: 'varchar(255)', notNull: true, unique: true }, { name: 'created_at', type: 'timestamp', default: 'now()' } ]} ] }); if (changes.length > 0) { console.log('Pending migrations:'); changes.forEach(change => console.log(change.sql)); } else { console.log('Schema is up to date.'); } } finally { client.release(); }

Debug

Known issues

breakingIn v3, the differ function signature changed from (client, schema, options) to (client, options). The 'schema' property is now inside the options object.

fix

Update call: const changes = await differ(client, { schema: [ ... ] });

affects: >=3.0.0 <3.0.0

deprecatedThe `options.preserve` option was deprecated in v3.2.0. Use `options.strategy` instead.

fix

Replace `preserve: true` with `strategy: 'preserve'`.

affects: >=3.2.0

gotchaWhen using CommonJS require, TypeScript types may not be resolved correctly. Use ESM imports and set `"module": "ESNext"` in tsconfig.

fix

Use `import { differ } from 'pg-differ'` and enable ESM resolution in tsconfig.

affects: >=3.0.0

gotchaThe CLI command `pg-differ sync` requires a database URL in the environment variable `DATABASE_URL`. If not set, it will fail silently.

fix

Set `DATABASE_URL` environment variable or use `--url` flag.

affects: all

Errors

Common errors & fixes

Cannot find module 'pg-differ' when using require

CJS/ESM compatibility issue: package.json does not export a CommonJS entry point correctly

fix

Use import syntax instead: import { differ } from 'pg-differ'

TypeError: differ is not a function

Default import used instead of named import (pg-differ exports named exports only)

fix

Use named import: import { differ } from 'pg-differ'

Error: connect ECONNREFUSED 127.0.0.1:5432

PostgreSQL is not running or not accessible via default host/port

fix

Start PostgreSQL or configure connection using DATABASE_URL or pool options.

Upgrade

Version history

3.5.1latest on npm

Audit

Dependencies

pgrequiredProvides PostgreSQL client for connecting to the database

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/multum/pg-differ ↗

packagepg-differ ↗

homepagehttps://multum.github.io/pg-differ ↗