lean-pg-migrate

library0.9.1jsnpmunverified

A simple PostgreSQL migration tool using postgres.js (porsager/postgres). Version 0.9.1 (alpha) with CLI and programmatic API. Released as a spin-off from a larger project; WIP status and low release cadence. Supports up/down migrations, dry runs, pg-monitor integration. Differentiator: lightweight, no ORM, relies on postgres.js instead of pg. TypeScript types included.

database

npm install lean-pg-migrate

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LEAN-PG-MIGRATE

lean-pg-migrate

databasejavascriptv0.9.1

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.

migrate

✓ import { migrate } from 'lean-pg-migrate'

✗ const migrate = require('lean-pg-migrate').migrate

TypeScript/ESM: package is ESM-only as of v0.9.1. Named export, not default.

rollback

✓ import { rollback } from 'lean-pg-migrate'

Same pattern as migrate; named export.

createMigration

✓ import { createMigration } from 'lean-pg-migrate'

✗ require('lean-pg-migrate/createMigration')

Not a separate file; all exports from main package.

Shows programmatic usage: connecting to PostgreSQL with postgres.js, then calling migrate() to run all pending migrations.

import { migrate, rollback, createMigration } from 'lean-pg-migrate'; import postgres from 'postgres'; const sql = postgres({ host: process.env.PGHOST ?? 'localhost', port: process.env.PGPORT ?? 5432, username: process.env.PGUSER ?? 'postgres', password: process.env.PGPASSWORD ?? '', database: process.env.PGDATABASE ?? 'postgres', }); // Run all pending migrations async function run() { try { const result = await migrate({ sql, dir: './migrations' }); console.log(`Migrated ${result.count} migrations`); } catch (e) { console.error('Migration failed:', e); } } run();

Debug

Known issues

breakingPackage is ESM-only from v0.9.0 onwards. CommonJS require() will not work.

fix

Use import syntax or dynamic import(). Ensure Node.js >=18.

affects: >=0.9.0

gotchaThe 'rollback all' command drops all migrations; it is irreversible and dangerous.

fix

Use 'rollback group' to rollback only the last batch unless you intend to reset the database.

affects: *

deprecatedThe 'up' and 'down' alias commands may be removed in future versions.

fix

Use 'migrate' and 'rollback' instead.

affects: *

gotchaDefault passwords are hardcoded as 'postgres' if not set via env or CLI argument. This is insecure for production.

fix

Always set PGPASSWORD environment variable or use --password.

affects: *

gotchaMigrations are written as JS files with exports, not .sql or .ts. TypeScript not natively supported.

fix

Write migrations as CommonJS or ESM JS files exporting up and down functions.

affects: *

Errors

Common errors & fixes

Cannot find module 'postgres'

postgres.js is a peer dependency that must be installed separately.

fix

Run: npm install postgres

SyntaxError: Unexpected token 'export'

Node.js version <18 does not support ESM, or package is being required() instead of imported.

fix

Ensure Node.js >=18 and use import instead of require.

Error: No migration directory found at ./migrations

Default directory does not exist or LPGM_DIR not set.

fix

Create the directory or use --dir to specify an existing one.

Upgrade

Version history

0.9.1latest on npm

Audit

Dependencies

postgresrequiredRequired: postgres.js is the database driver used for all queries.

commanderrequiredRequired: CLI argument parsing.

Agent activity

6 hits · last 30 days

node

Resources

githubgit://github.com/dmitrythaler/lean-pg-migrate ↗

packagelean-pg-migrate ↗

homepagehttps://github.com/dmitrythaler/lean-pg-migrate#readme ↗