Registry / database / pg-migration-manager

pg-migration-manager

library1.0.12jsnpmunverified

A minimal migration manager for PostgreSQL using the pg driver. Version 1.0.12 is the latest stable release. It reads SQL files from a specified directory and runs them sequentially based on file creation dates, tracking executed migrations in a database table. Unlike heavier tools (e.g., node-pg-migrate), it stays simple with no dependency on query builders or complex configuration. Ships TypeScript types, ESM-only. Ideal for projects that need bare-bones SQL migration management.

database

npm install pg-migration-manager

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-MIGRATION-MANAG

pg-migration-manager

databasejavascriptv1.0.12

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 (MigrationManager)

✓ import MigrationManager from 'pg-migration-manager';

✗ const MigrationManager = require('pg-migration-manager');

Package is ESM-only; CommonJS require will fail.

MigrationManager type

✓ import type MigrationManager from 'pg-migration-manager';

✗ import { MigrationManager } from 'pg-migration-manager';

The default export is the class; named import does not exist. Use 'import type' for type-only usage.

Configuration type

✓ import MigrationManager from 'pg-migration-manager'; type Config = ConstructorParameters<typeof MigrationManager>[1];

✗ import { Config } from 'pg-migration-manager';

Configuration type is not exported; extract from constructor parameters.

Connects to PostgreSQL using pg Pool, runs pending SQL migrations from a directory, then closes the pool.

import { Pool } from 'pg'; import MigrationManager from 'pg-migration-manager'; const pool = new Pool({ connectionString: process.env.DATABASE_URL ?? '' }); const manager = new MigrationManager(pool, { pathToMigrations: './migrations', migrationTableName: 'migrations' }); async function run() { await manager.runMigrations(); console.log('Migrations applied successfully'); await pool.end(); } run().catch(err => { console.error(err); process.exit(1); }); /* Migration SQL files (e.g., 001_create_users.sql) should be placed in the specified directory. They are executed sequentially based on file creation date. */

Debug

Known issues

breakingPackage is ESM-only (no CommonJS support). Use dynamic import or set type: 'module' in package.json.

fix

Use ESM imports: import MigrationManager from 'pg-migration-manager'; or wrap in dynamic import().

affects: >=1.0.0

gotchaMigrations are run sequentially based on file creation dates, not alphabetical or version order. Changing file creation dates may cause unexpected migration order.

fix

Ensure file creation dates reflect desired order (e.g., touch files in order).

affects: >=1.0.0

gotchaChanging migration file names after they have been run will cause them to be re-run, potentially causing duplicate or conflicting changes.

fix

Never rename migration files after they have been applied. Mark changes with new files.

affects: >=1.0.0

gotchaMigration runner does not wrap each migration in a transaction by default. If a migration fails, partial changes may remain.

fix

Write each migration file as a single transactional SQL statement (BEGIN/COMMIT) to ensure atomicity.

affects: >=1.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module /path/to/node_modules/pg-migration-manager/index.js from /path/to/app.js not supported. Instead change the require of index.js in /path/to/app.js to a dynamic import() which is available in all CommonJS modules.

Using CommonJS require() on an ESM-only package.

fix

Use import MigrationManager from 'pg-migration-manager'; or convert your file to ES module.

TypeError: MigrationManager is not a constructor

Importing the package as a named export (e.g., import { MigrationManager }), but it only exports a default.

fix

Use import MigrationManager from 'pg-migration-manager'; without destructuring.

Error: Connection terminated unexpectedly

Pool is closed before runMigrations completes or no pool/client passed.

fix

Ensure a valid pg Pool or Client is passed, and don't close the pool until after runMigrations resolves.

Upgrade

Version history

1.0.12latest on npm

Audit

Dependencies

pgrequiredPeer dependency: required for database connection pool/client.

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/AlekseyKowalsky/pg-migration-manager ↗

packagepg-migration-manager ↗

homepagehttps://github.com/AlekseyKowalsky/pg-migration-manager#readme ↗