bun-migrate

library1.0.9jsnpmunverified

A lightweight PostgreSQL migration tool for Bun, inspired by postgres-migrations but using Bun's built-in SQL client instead of the pg package. Current stable version is 1.0.9, released occasionally with no fixed cadence. Key differentiators: leverages Bun's native PostgreSQL client for faster startup and smaller dependencies, supports SQL-only migrations with sequential integer IDs, no rollbacks, file hash integrity checks, and PostgreSQL advisory locks for concurrency. Ideal for Bun-based projects needing simple, forward-only database migrations.

database devops

npm install bun-migrate

package ↗

INSTALL

IMPORT

SIG · BUN-MIGRATE

bun-migrate

databasejavascriptv1.0.9

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.

bun-migrate

✓ import { migrate } from 'bun-migrate';

✗ const migrate = require('bun-migrate');

Package is ESM-only; CommonJS require is not supported. Use `import` statements.

migrate

✓ import { migrate } from 'bun-migrate';

✗ import migrate from 'bun-migrate';

Named export, not default export. Do not use default import.

✓ import { up } from 'bun-migrate'; or via CLI: bunx bun-migrate up

✗ import { up } from 'bun-migrate/up';

The `up` command is available as a named export from the main package entry. There is no subpath export.

Shows how to import and call the migrate function with a connection string and default migration directory.

import { migrate } from 'bun-migrate'; // Run all pending migrations from the default 'migrations' directory await migrate({ migrationDir: 'migrations', connectionString: process.env.DATABASE_URL ?? 'postgres://user:password@localhost:5432/mydb', }); console.log('Migrations complete.');

Debug

Known issues

gotchaDatabase URL contains special characters that must be URL-encoded.

fix

Ensure user/password are URL-encoded if they contain special characters (e.g., %23 for #).

affects: >=1.0.0

breakingNode.js is not supported; requires Bun runtime.

fix

Use Bun instead of Node.js to run this package. Install via `curl -fsSL https://bun.sh/install | bash`.

affects: >=1.0.0

deprecatedNo deprecations known at this version.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'bun-migrate'

Package not installed or incorrect import path.

fix

Run `bun add bun-migrate` and ensure import statement is correct: `import { migrate } from 'bun-migrate';`

TypeError: migrate is not a function

Using default import instead of named import.

fix

Change `import migrate from 'bun-migrate'` to `import { migrate } from 'bun-migrate'`.

Error: connect ECONNREFUSED ::1:5432

PostgreSQL server not running or connection string incorrect.

fix

Ensure PostgreSQL is running and the connection string is correct. Use `process.env.DATABASE_URL ?? 'postgres://...'`

Upgrade

Version history

1.0.9latest on npm

Audit

Dependencies

bunrequiredRuntime requirement; uses Bun's built-in SQL client and works only with the Bun runtime.

postgresoptionalRequired by the underlying Bun SQL client; must have a PostgreSQL instance accessible.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

packagebun-migrate ↗