pgmg

library0.0.11jsnpmunverified

pgmg is a forward-only, idempotent PostgreSQL migration tool that focuses on minimal magic and simplicity. Version 0.0.11 (pre-1.0) uses postgres.js to run migrations defined as ES modules exporting a transaction function. It stores migration metadata in a pgmg.migration table within the target database, enabling easy reset for development. Unlike tools like node-pg-migrate or db-migrate, pgmg avoids complex configuration and ordering, relying on glob order and idempotent execution. The package is experimental and has sparse documentation.

database

npm install pgmg

package ↗

INSTALL

IMPORT

SIG · PGMG

pgmg

databasejavascriptv0.0.11

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.

transaction

✓ export async function transaction(sql) { ... }

The exported function receives a tagged template literal SQL instance from postgres.js. Must be named exactly 'transaction'.

action

✓ export async function action(sql) { ... }

Alternative to transaction; does NOT wrap in a transaction. Use only for migrations that cannot be transactional.

name

✓ export const name = 'Migration Name'

Required export; unique identifier for tracking whether migration has run. Should be descriptive.

description

✓ export const description = `...`

Optional but recommended; stored in metadata table for reference.

Creates a migration file with a named transaction function. The CLI runs it against a PostgreSQL connection string.

// migrations/001-create-users.mjs export const name = 'Create users table'; export const description = `Creates the users table with id, email, and created_at.`; export async function transaction(sql) { await sql` CREATE TABLE users ( id SERIAL PRIMARY KEY, email TEXT NOT NULL UNIQUE, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW() ); `; } // Run in terminal: // npx pgmg postgres://user:pass@localhost/mydb migrations/001-create-users.mjs

Debug

Known issues

gotchaMigration files must use .mjs extension or have "type": "module" in package.json. Otherwise Node.js will treat them as CommonJS and fail to parse ESM export syntax.

fix

Rename migration files to .mjs or set "type": "module" in package.json.

affects: >=0.0.1

gotchaThe CLI accepts files as arguments after the connection string. If you use a glob like migrations/*, the shell expands it. On Windows or when passing via npm scripts, quotes may be needed.

fix

Use npx pgm "$DATABASE_URL" ./migrations/*.mjs (quotes around glob if needed).

affects: >=0.0.1

gotchapgmg stores metadata in a schema named 'pgmg'. If you drop that schema, all migration history is lost. Be careful in production.

fix

Do not drop schema pgmg in production unless you intend to re-run all migrations.

affects: >=0.0.1

breakingVersion 0.0.11 is pre-1.0. The API may change without major version bump. Pin an exact version in package.json.

fix

Specify "pgmg": "0.0.11" in dependencies to avoid unintended upgrades.

affects: >=0.0.11

Errors

Common errors & fixes

SyntaxError: Unexpected token 'export'

Node.js does not recognize ES module syntax because the file is .js and package.json lacks "type": "module".

fix

Rename migration file to .mjs or add "type": "module" to package.json.

Error: listen EADDRINUSE :::5432

A PostgreSQL instance is already running on port 5432, migration cannot connect.

fix

Stop the existing PostgreSQL service or change the port in the connection string.

pgmg: no files found matching migrations/*.mjs

The glob pattern does not match any files (e.g., directory is empty or extension mismatch).

fix

Verify the migration directory exists and contains .mjs files; try using absolute paths.

Upgrade

Version history

0.0.11latest on npm

Audit

Dependencies

postgresrequiredRuntime dependency for connecting to and querying PostgreSQL; pgmg passes a preconfigured postgres.js instance to migration files.

Agent activity

2 hits · last 30 days

node

Resources

packagepgmg ↗