Registry / database / bun-sqlite-migrations

bun-sqlite-migrations

library1.0.2jsnpmunverified

A minimal migration helper for bun:sqlite. Version 1.0.2 provides a single function to apply SQL file migrations in sorted order and tracks progress via PRAGMA user_version. Designed exclusively for Bun's built-in SQLite driver, it is not compatible with other SQLite libraries. Works only in the Bun runtime with TypeScript peer dependency ^5.0.0. No other dependencies. Simpler than alternatives like Knex or Umzug, but limited to file-based migrations and numeric versioning via file name order.

database

npm install bun-sqlite-migrations

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BUN-SQLITE-MIGRATI

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

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

Package is ESM-only; require() will throw.

getMigrations

✓ import { getMigrations } from 'bun-sqlite-migrations'

getMigrations reads migration files from a directory and returns them sorted by filename. It does NOT track execution; it only provides the file list.

Database

✓ import { Database } from 'bun:sqlite'

✗ import { Database } from 'bun-sqlite-migrations'

Database must be imported from bun:sqlite, not from this package.

Shows how to create a bun:sqlite Database, read migrations from a folder, and apply them using migrate().

import { Database } from 'bun:sqlite'; import { migrate, getMigrations } from 'bun-sqlite-migrations'; const db = new Database('data.db'); migrate(db, getMigrations('./migrations')); console.log('Migrations applied');

Debug

Known issues

gotchaMigrations are applied in filename order, not by content. Leading zeros are recommended.

fix

Name files like '0001_init.sql', '0002_add_users.sql' to ensure correct order.

affects: all

gotchaTracking uses PRAGMA user_version, which is limited to 64-bit signed integer. May overflow with >9e18 migrations.

fix

Do not exceed 9,223,372,036,854,775,807 migrations.

affects: all

gotchaDoes not support rollbacks or partial failure recovery. If a migration fails, the database may be left in an inconsistent state.

fix

Wrap each migration in a transaction manually, or use a library with rollback support.

affects: all

gotchagetMigrations does not validate file contents or track already-executed migrations. It simply returns a sorted list of SQL files.

fix

Ensure files contain valid SQL. Use migrate() to apply only new ones.

affects: all

Errors

Common errors & fixes

error: Cannot find module 'bun:sqlite'

Running the script outside Bun (e.g., Node.js).

fix

Run with 'bun run script.ts' instead of 'node script.ts'.

TypeError: migrate is not a function

Importing incorrectly, e.g., using require() or destructuring incorrectly.

fix

Use ESM import: import { migrate } from 'bun-sqlite-migrations'

ENOENT: no such file or directory, scandir './migrations'

The migrations folder does not exist or path is wrong.

fix

Create the folder or provide a correct absolute/relative path to getMigrations().

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Bingbot

Resources

githubhttps://github.com/patwoz/bun-sqlite-migrations ↗

packagebun-sqlite-migrations ↗

homepagehttps://patwoz.dev ↗