{"id":43640,"library":"pomp","title":"Pomp","description":"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.","status":"active","version":"0.2.16","language":"javascript","source_language":"en","source_url":"https://github.com/sciolist/pomp","tags":["javascript","typescript"],"install":[{"cmd":"npm install pomp","lang":"bash","label":"npm"},{"cmd":"yarn add pomp","lang":"bash","label":"yarn"},{"cmd":"pnpm add pomp","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for TypeScript development; ships types for Node.js APIs like `readdir`, `readFile`.","package":"@types/node","optional":true}],"imports":[{"note":"Library is ESM-only; CommonJS require will fail.","wrong":"const Pomp = require('pomp')","symbol":"Pomp","correct":"import { Pomp } from 'pomp'"},{"note":"CLI flags are not supported; just positional arguments.","wrong":"npx pomp new --name migration-name","symbol":"Pomp (CLI usage)","correct":"npx pomp new migration-name"},{"note":"Types should be imported with `type` for tree-shaking in ESM.","wrong":"import { PompOptions } from 'pomp' (without type keyword)","symbol":"PompOptions (type)","correct":"import type { PompOptions } from 'pomp'"}],"quickstart":{"code":"import { Pomp } from 'pomp';\nimport postgres from 'postgres';\nimport { readdir, readFile } from 'fs/promises';\n\nconst conn = postgres(process.env.POSTGRES_URL ?? 'postgres://localhost');\n\nconst pomp = new Pomp({\n  async runSqlQuery(text) {\n    return await conn.unsafe(text);\n  },\n  async listLocalMigrations() {\n    return await readdir('migrations');\n  },\n});\n\n// Run all pending migrations\nawait pomp.runMigrations(async (name) => {\n  return await readFile(`migrations/${name}`, 'utf-8');\n});\n\nconsole.log('Migrations applied successfully.');","lang":"typescript","description":"Initializes Pomp with a postgres connection, reads migration files from './migrations', and runs all pending migrations."},"warnings":[{"fix":"Use `import { Pomp } from 'pomp'` instead of `import Pomp from 'pomp'`.","message":"Pomp was originally exported as default; named export `Pomp` is required since v0.2.0.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Ensure migrations directory exists or set `POMP_WD` before running.","message":"CLI command `npx pomp run` requires a 'migrations' folder in the working directory or `POMP_WD` environment variable; otherwise it silently exits.","severity":"gotcha","affected_versions":"*"},{"fix":"Use timestamps (e.g., 1699000000) for version numbers.","message":"Migration version numbers must be unique integers; non-numeric prefix or duplicate numbers cause undefined behavior.","severity":"gotcha","affected_versions":"*"},{"fix":"Update your implementation to return an array (even if empty) from `runSqlQuery`.","message":"The `runSqlQuery` method signature changed between v0.1.x and v0.2.x – it now expects an array of result rows.","severity":"deprecated","affected_versions":">=0.2.0"}],"env_vars":null,"search_vec":"'api':45 'cadenc':84 'changelog':88 'check':87 'class':47 'cli':38 'connect':35 'depend':54 'design':48 'differ':56 'down/rollback':73 'environ':29 'esm':81 'execut':14 'file':16 'focus':67 'folder':20 'framework':53 'import':82 'irregular':86 'javascript':89 'knex':65 'like':59 'migrat':10,19,63,71 'minim':5 'new/run/pending/skip':41 'node':61 'node-pg-migr':60 'npx':39 'one':7 'one-way':6 'pg':62 'pomp':1,2,40,46 'postgr':32 'postgresql':9 'prefix':24 'programmat':44 'provid':36 'psql':28 'releas':83 'sequenti':21 'ship':75 'simplic':50 'sole':68 'sql':15 'standard':27 'support':74 'timestamp':23 'tool':11,58 'type':77 'typescript':76,90 'unidirect':70 'url':33 'use':26 'v0.2.16':12 'variabl':30 'via':80 'way':8 'without':72 'work':79","created_at":"2026-06-05T17:00:46.103049+00:00","updated_at":"2026-06-05T17:00:46.103049+00:00","problems":[{"fix":"Switch to ESM (\"type\": \"module\" in package.json) or use dynamic import: `import('pomp')`.","cause":"Project uses CommonJS require() but pomp is ESM-only.","error":"Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'pomp'"},{"fix":"Change `import Pomp from 'pomp'` to `import { Pomp } from 'pomp'`.","cause":"Default import used instead of named import in v0.2+.","error":"TypeError: Pomp is not a constructor"},{"fix":"Create a 'migrations' folder in the working directory or set `POMP_WD` environment variable.","cause":"Missing migrations directory or POMP_WD not set.","error":"Error: Cannot find module '/path/to/migrations'"},{"fix":"Ensure the connected database user has CREATE TABLE privileges, or manually create the table: `CREATE TABLE public._pomp_migrations (version bigint);`","cause":"Pomp creates a table `_pomp_migrations` but first run may have failed or insufficient permissions.","error":"error: relation \"public._pomp_migrations\" does not exist"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/sciolist/pomp#readme","github":"https://github.com/sciolist/pomp","docs":null,"changelog":null,"pypi":null,"npm":"pomp","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}