pomp

library0.2.16jsnpmunverified

Pomp is a minimal, one-way PostgreSQL migration tool (v0.2.16) that executes SQL files from a `migrations` folder sequentially by timestamp prefix. It uses standard psql environment variables or `POSTGRES_URL` for connection, providing a CLI (`npx pomp new/run/pending/skip`) and a programmatic API (`Pomp` class). Designed for simplicity with no framework dependencies, it differs from tools like `node-pg-migrate` or `knex` by focusing solely on unidirectional migrations without down/rollback support. Ships TypeScript types and works via ESM imports. Release cadence is irregular; check changelog.

database

npm install pomp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · POMP

pomp

databasejavascriptv0.2.16

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.

Pomp

✓ import { Pomp } from 'pomp'

✗ const Pomp = require('pomp')

Library is ESM-only; CommonJS require will fail.

Pomp (CLI usage)

✓ npx pomp new migration-name

✗ npx pomp new --name migration-name

CLI flags are not supported; just positional arguments.

PompOptions (type)

✓ import type { PompOptions } from 'pomp'

✗ import { PompOptions } from 'pomp' (without type keyword)

Types should be imported with `type` for tree-shaking in ESM.

Initializes Pomp with a postgres connection, reads migration files from './migrations', and runs all pending migrations.

import { Pomp } from 'pomp'; import postgres from 'postgres'; import { readdir, readFile } from 'fs/promises'; const conn = postgres(process.env.POSTGRES_URL ?? 'postgres://localhost'); const pomp = new Pomp({ async runSqlQuery(text) { return await conn.unsafe(text); }, async listLocalMigrations() { return await readdir('migrations'); }, }); // Run all pending migrations await pomp.runMigrations(async (name) => { return await readFile(`migrations/${name}`, 'utf-8'); }); console.log('Migrations applied successfully.');

Debug

Known issues

breakingPomp was originally exported as default; named export `Pomp` is required since v0.2.0.

fix

Use `import { Pomp } from 'pomp'` instead of `import Pomp from 'pomp'`.

affects: >=0.2.0

gotchaCLI command `npx pomp run` requires a 'migrations' folder in the working directory or `POMP_WD` environment variable; otherwise it silently exits.

fix

Ensure migrations directory exists or set `POMP_WD` before running.

affects: *

gotchaMigration version numbers must be unique integers; non-numeric prefix or duplicate numbers cause undefined behavior.

fix

Use timestamps (e.g., 1699000000) for version numbers.

affects: *

deprecatedThe `runSqlQuery` method signature changed between v0.1.x and v0.2.x – it now expects an array of result rows.

fix

Update your implementation to return an array (even if empty) from `runSqlQuery`.

affects: >=0.2.0

Errors

Common errors & fixes

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'pomp'

Project uses CommonJS require() but pomp is ESM-only.

fix

Switch to ESM ("type": "module" in package.json) or use dynamic import: `import('pomp')`.

TypeError: Pomp is not a constructor

Default import used instead of named import in v0.2+.

fix

Change `import Pomp from 'pomp'` to `import { Pomp } from 'pomp'`.

Error: Cannot find module '/path/to/migrations'

Missing migrations directory or POMP_WD not set.

fix

Create a 'migrations' folder in the working directory or set `POMP_WD` environment variable.

error: relation "public._pomp_migrations" does not exist

Pomp creates a table `_pomp_migrations` but first run may have failed or insufficient permissions.

fix

Ensure the connected database user has CREATE TABLE privileges, or manually create the table: `CREATE TABLE public._pomp_migrations (version bigint);`

Upgrade

Version history

0.2.16latest on npm

Audit

Dependencies

@types/nodeoptionalRequired for TypeScript development; ships types for Node.js APIs like `readdir`, `readFile`.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/sciolist/pomp ↗

packagepomp ↗

homepagehttps://github.com/sciolist/pomp#readme ↗