Registry / database / node-pg-migrate-custom

node-pg-migrate-custom

library5.6.0-patch.6jsnpmunverified

A PostgreSQL-specific database migration tool for Node.js, built as a fork of the original node-pg-migrate with two extensions: prioritization of DATABASE_URL environment variable over JSON config, and a flag to skip tracking applied migrations (useful for migrating stored functions). Current stable version is 5.6.0-patch.6, released as a patch fork. The library provides a programmatic API and CLI to create and run migrations using a fluent builder pattern for SQL operations, automatically inferring down migrations. It supports ES modules and TypeScript types, and requires the pg peer dependency (>=4.3.0 <9.0.0). Unlike generic migration tools, it is built exclusively for PostgreSQL, offering full-featured PostgreSQL-specific operations without sacrificing simplicity.

database

npm install node-pg-migrate-custom

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NODE-PG-MIGRATE-CU

node-pg-migrate-custom

databasejavascriptv5.6.0-patch.6

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.

MigrationBuilder

✓ import { MigrationBuilder } from 'node-pg-migrate-custom'

✗ const MigrationBuilder = require('node-pg-migrate').MigrationBuilder

Since v5, library is ESM-first. TypeScript definitions are shipped. For CommonJS, use dynamic import or check compatibility.

default export

✓ import nodePgMigrate from 'node-pg-migrate-custom'

✗ const nodePgMigrate = require('node-pg-migrate')

The default export is the main function for programmatic usage. CommonJS require works but may cause issues with some bundlers.

ColumnDefinition

✓ import type { ColumnDefinition } from 'node-pg-migrate-custom'

✗ import { ColumnDefinition } from 'node-pg-migrate'

This is a type import. Use 'import type' for type-only imports to avoid runtime errors.

Migration

✓ export const up = (pgm: MigrationBuilder) => { ... }

✗ module.exports = { up: (pgm) => { ... } }

Migration files should use ES module syntax (export) rather than CommonJS module.exports. This is consistent with ESM-first approach.

Creates a migration file and runs it against a PostgreSQL database using DATABASE_URL environment variable.

// Install: npm install node-pg-migrate-custom pg // Create migration: npx node-pg-migrate create my_first_migration // Then edit the generated file (e.g., 001_my-first-migration.js): export const up = (pgm) => { pgm.createTable('users', { id: 'id', name: { type: 'varchar(1000)', notNull: true }, createdAt: { type: 'timestamp', notNull: true, default: pgm.func('current_timestamp'), }, }); pgm.createTable('posts', { id: 'id', userId: { type: 'integer', notNull: true, references: '"users"', onDelete: 'cascade' }, body: { type: 'text', notNull: true }, createdAt: { type: 'timestamp', notNull: true, default: pgm.func('current_timestamp'), }, }); pgm.createIndex('posts', 'userId'); }; // Run: DATABASE_URL=postgres://user:pass@localhost:5432/db npx node-pg-migrate up

Debug

Known issues

breakingIn version 5, migrations must be ES modules (export const up) instead of CommonJS (module.exports).

fix

Update migration files to use export const up = (pgm) => { ... } and ensure package.json has "type": "module" or use .mjs extension.

affects: >=5.0.0

gotchaThe library prioritizes DATABASE_URL environment variable over JSON config. If both are set, DATABASE_URL wins, which may cause unexpected connection strings.

fix

Ensure DATABASE_URL is set to the desired connection string or unset it to use JSON config.

affects: >=5.6.0-patch.6

breakingPeer dependency pg must be >=4.3.0 and <9.0.0. Incompatible versions may cause runtime errors.

fix

Install a compatible pg version: npm install pg@^8 (or appropriate version within range).

affects: >=5.0.0

deprecatedThe original node-pg-migrate v3 docs are separate. This fork may not include all v3 features.

fix

Refer to the docs at https://salsita.github.io/node-pg-migrate for the custom fork.

affects: >=5.0.0

gotchaWhen using the skip-tracking flag, applied migrations are not recorded in the database, which can lead to duplicate execution if not managed carefully.

fix

Only use skip-tracking for migrations that are idempotent (e.g., stored function definitions) to avoid data corruption.

affects: >=5.6.0-patch.6

Errors

Common errors & fixes

Error: Cannot find module 'node-pg-migrate-custom'

Package not installed or not in node_modules.

fix

Run: npm install node-pg-migrate-custom pg

TypeError: pgm.createTable is not a function

Using CommonJS module.exports in migration file while library expects ES module export.

fix

Change to export const up = (pgm) => { ... } and ensure 'type': 'module' in package.json.

Error: pg library is required as a peer dependency

pg package not installed or version incompatible.

fix

Install a compatible version: npm install pg@^8

Migration file does not export 'up' function

Migration file is not exporting up function correctly (e.g., using module.exports instead of export).

fix

Use export const up = (pgm) => { ... } in migration files.

Upgrade

Version history

5.6.0-patch.6latest on npm

Audit

Dependencies

pgrequiredPeer dependency - library uses pg to connect to PostgreSQL

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/tonkonogov/node-pg-migrate ↗

packagenode-pg-migrate-custom ↗

homepagehttps://github.com/tonkonogov/node-pg-migrate#readme ↗