Registry / database / bun-psql-migrations

bun-psql-migrations

library1.0.2jsnpmunverified

Lightweight PostgreSQL migration tool for Bun v1.0.2. Uses Bun's built-in SQL client, no external drivers. Features timestamp-based migration files, transaction-safe up/down SQL, CLI commands (init, create, migrate, rollback, reset), and a programmatic API. Zero-config with DATABASE_URL. Minimal dependencies (pino for logging). Suitable for Bun projects that need simple, team-friendly schema migrations without heavy ORMs.

database

npm install bun-psql-migrations

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BUN-PSQL-MIGRATION

bun-psql-migrations

databasejavascriptv1.0.2

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 'bun-psql-migrations'

✗ const { migrate } = require('bun-psql-migrations')

ESM-only; require() will throw error.

rollback

✓ import { rollback } from 'bun-psql-migrations'

CommonJS not supported. Use ESM imports.

getPendingMigrations

✓ import { getPendingMigrations } from 'bun-psql-migrations'

✗ import getPendingMigrations from 'bun-psql-migrations'

Named export, not default export.

Initialize, create, and run migrations programmatically using ESM imports.

import { migrate, rollback, createMigration, init } from 'bun-psql-migrations'; // Initialize migrations directory await init(); // Create a new migration const name = await createMigration('add_users'); console.log(`Created migration: ${name}`); // Run pending migrations (requires DATABASE_URL env) await migrate(); // Rollback last migration await rollback();

Debug

Known issues

gotchaRequires Bun runtime; does not work with Node.js or Deno.

fix

Use only with Bun (bun run script.ts).

affects: >=1.0.0

deprecatedTypeScript peer dependency is required but may change in future versions.

fix

Install typescript@^5.8.3 as devDependency.

affects: >=1.0.0

gotchaDefault migration directory is './migrations'. Must be initialized with `init` command before running migrations.

fix

Run 'bunx bun-psql-migrations init' before any migrate/rollback.

affects: >=1.0.0

gotchaAll CLI commands require DATABASE_URL environment variable or it will fail with connection error.

fix

Set DATABASE_URL in .env or prefix command: DATABASE_URL=postgres://... bunx ...

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'bun-psql-migrations'

Using CommonJS require() instead of ESM import.

fix

Replace const x = require(...) with import { x } from 'bun-psql-migrations' and run with bun.

Error: No pending migrations to run

Migrations directory not initialized or no .up.sql files found.

fix

Run 'bunx bun-psql-migrations init' then create migration with 'bunx bun-psql-migrations create your_migration_name'.

Error: connect ECONNREFUSED ::1:5432

PostgreSQL not running or DATABASE_URL missing/invalid.

fix

Ensure PostgreSQL is running and set correct DATABASE_URL (e.g., postgres://user:pass@localhost:5432/dbname).

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/iam4x/bun-psql-migrations ↗

packagebun-psql-migrations ↗

homepagehttps://github.com/iam4x/bun-psql-migrations#readme ↗