postgres-migrate

library1.1.2jsnpmunverified

PostgreSQL migration tool using advisory locks for safe concurrent execution. Version 1.1.2 is the latest stable release with low maintenance cadence. Executes .sql migration files sequentially with automatic locking to prevent race conditions. Minimal configuration, supports custom reporters and connection strings. Differentiates from alternatives like node-pg-migrate by its simplicity and reliance on PostgreSQL advisory locks.

database

npm install postgres-migrate

package ↗

INSTALL

IMPORT

SIG · POSTGRES-MIGRATE

postgres-migrate

databasejavascriptv1.1.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 (migrate)

✓ import migrate from 'postgres-migrate'

✗ const { migrate } = require('postgres-migrate')

The module exports a default function. Named export does not exist.

default (migrate) with require

✓ const migrate = require('postgres-migrate')

CommonJS require works as default import.

TypeScript usage

✓ import migrate from 'postgres-migrate'

✗ import * as migrate from 'postgres-migrate'

Type definitions may not be bundled; use @types/postgres-migrate if available, or declare module.

Default export (ESM)

✓ import migrate from 'postgres-migrate'

✗ import { default as migrate } from 'postgres-migrate'

Direct default import is the intended pattern.

Shows minimal setup to run SQL migrations from a directory against a PostgreSQL database using connection string from environment variables.

Debug

Known issues

gotchamigrationsDir must contain only .sql files; non-.sql files may cause errors or be ignored.

fix

Ensure all migration files have .sql extension and no other files in the directory.

affects: >=0.0.0

deprecatedThe 'conString' option is deprecated in favor of using 'pg' client's connection configuration.

fix

Use an existing pg client instance or switch to 'client' option if supported.

affects: >=1.0.0

gotchaAdvisory lock requires PostgreSQL 9.4+; older versions will fail silently.

fix

Upgrade PostgreSQL to 9.4 or later.

affects: >=0.0.0

gotchaPromise rejection on migration failure may not include full stack trace due to internal error handling.

fix

Check the 'reporter' function logs for detailed error messages.

affects: >=0.0.0

gotchaMultiple workers will wait indefinitely if the lock is held by a crashed worker (no timeout).

fix

Implement a manual timeout or use a monitoring tool to release stale locks.

affects: >=0.0.0

Errors

Common errors & fixes

Error: connect ECONNREFUSED <host>:<port>

PostgreSQL server not running or incorrect host/port.

fix

Start PostgreSQL service and verify connection string.

error: relation "migrations" does not exist

Migrations table not created automatically; package expects it to exist.

fix

Create the migrations table manually: CREATE TABLE IF NOT EXISTS migrations (id SERIAL PRIMARY KEY, name VARCHAR(255) UNIQUE, run_on TIMESTAMP DEFAULT NOW());

TypeError: migrate is not a function

Using named import instead of default import.

fix

Use const migrate = require('postgres-migrate') (not destructured).

Error: ENOENT: no such file or directory, scandir '...'

migrationsDir path does not exist or is incorrect.

fix

Check that the migrations directory path is absolute or relative to working directory.

error: permission denied for schema public

Database user lacks CREATE TABLE permissions.

fix

Grant necessary privileges: GRANT CREATE ON SCHEMA public TO <user>;

Upgrade

Version history

1.1.2latest on npm

Audit

Dependencies

pgrequiredPostgreSQL client for database connection

Agent activity

4 hits · last 30 days

node

Resources

packagepostgres-migrate ↗