pgm

library1.0.8jsnpmunverified

pgm is a simple command-line migration tool for PostgreSQL that only tracks and applies .sql files without generating any SQL. Current stable version is 1.0.8 (last updated 2021). It requires Node 8.2+ and PostgreSQL 9.1+. Key differentiators: no down migrations, no SQL generation, all pending migrations applied in a transaction, supports both JSON and .env configuration, lightweight with minimal dependencies.

database devops

npm install pgm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PGM

pgm

databasejavascriptv1.0.8

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.

pgm

✓ import pgm from 'pgm'

✗ const pgm = require('pgm')

pgm is a CLI tool not a library, but if imported programmatically it has limited API. ESM-only for programmatic use? Check docs.

Shows setup, configuration, creating a migration, applying it, and checking status using pgm CLI.

// Initialize project mkdir my-migrations && cd my-migrations npm init -y npm i pgm --save-dev // Create pgm.json configuration cat > pgm.json <<EOF { "host": "localhost", "port": "5432", "database": "mydb", "user": "postgres", "password": "", "migrationsDirectory": "migrations", "migrationsTable": "public.migrations" } EOF // Create first migration npx pgm make create users table # Creates migrations/001.sql // Edit migration (example SQL) echo "CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT NOT NULL);" > migrations/001.sql // Run migration npx pgm up // Check status npx pgm stat

Debug

Known issues

breakingNo down migrations supported. Reverting requires manual SQL.

fix

Manually write and execute down migrations outside pgm, or use a tool that supports rollbacks.

affects: >=1.0.0

gotchaTwo migrations cannot start with the same sequence number.

fix

Ensure each migration filename begins with a unique numeric prefix (e.g., 001, 002).

affects: >=1.0.0

gotchaDo not modify or rename migrations after they have been applied.

fix

If you need to change a migration, create a new migration that alters the schema.

affects: >=1.0.0

deprecatedNode 8.2+ required; older versions unsupported.

fix

Upgrade Node.js to version 8.2 or later.

affects: >=1.0.0

gotchaConfiguration via .env requires specific prefix: POSTGRES_* and PGM_*.

fix

Use correct env var names: POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, PGM_MIGRATIONS_DIRECTORY, PGM_MIGRATIONS_TABLE.

affects: >=1.0.0

Errors

Common errors & fixes

Error: connect ECONNREFUSED 127.0.0.1:5432

PostgreSQL server is not running or not accessible on the specified host/port.

fix

Start PostgreSQL service (sudo systemctl start postgresql or brew services start postgresql) and verify connection settings in pgm.json or .env.

Error: password authentication failed for user "postgres"

Incorrect password for the database user.

fix

Update the password field in pgm.json or POSTGRES_PASSWORD in .env. Ensure the PostgreSQL user has the correct password set.

Error: relation "public.migrations" does not exist

The migrations tracking table has not been created yet.

fix

Run pgm up to create the migrations table automatically, or create it manually with SQL.

Error: migration 001.sql already applied

A migration with the same sequence number (001) has already been applied.

fix

Do not reuse migration numbers. Use a new sequence number for each migration (e.g., 002).

Upgrade

Version history

1.0.8latest on npm

Audit

Dependencies

commanderrequiredCLI command parsing

dotenvoptionalLoad .env configuration files

pgrequiredPostgreSQL client for Node.js

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/dejangeci/pgmjs ↗

packagepgm ↗

homepagehttps://github.com/dejangeci/pgmjs#readme ↗