sqlite-up

library0.6.0jsnpmunverified

A lightweight TypeScript-first SQLite migration system for Node.js (24+) and Bun. Version 0.6.0 supports multiple SQLite clients (node:sqlite, bun:sqlite, Bun SQL, better-sqlite3) with concurrency-safe database locking, transaction-safe migrations, and rollbacks. Key differentiators: modern API, zero configuration beyond db and migrationsDir, built-in lock table to prevent concurrent migration runs, and TypeScript types included. Released under MIT license.

database

npm install sqlite-up

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQLITE-UP

sqlite-up

databasejavascriptv0.6.0

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.

Migrator

✓ import { Migrator } from 'sqlite-up'

✗ const Migrator = require('sqlite-up')

ESM-only package; requires Node 24+ with --experimental-strip-types or ts-node for .ts migrations.

MigratorDatabase

✓ import type { MigratorDatabase } from 'sqlite-up'

✗ import { MigratorDatabase } from 'sqlite-up'

TypeScript users should use type-only import for MigratorDatabase, as it is not a runtime export.

MigratorOptions

✓ import type { MigratorOptions } from 'sqlite-up'

✗ import { MigratorOptions } from 'sqlite-up'

TypeScript users should use type-only import for MigratorOptions, as it is not a runtime export.

Create a node:sqlite database instance and apply all pending migrations.

import { DatabaseSync } from 'node:sqlite'; import { Migrator } from 'sqlite-up'; async function main() { const db = new DatabaseSync('myapp.db'); const migrator = new Migrator({ db, migrationsDir: './migrations', }); const result = await migrator.apply(); if (result.success) { console.log('Applied migrations:', result.appliedMigrations); } else { console.error('Migration failed:', result.error); } } main().catch(console.error);

Debug

Known issues

breakingNode.js >=24 is required; older versions are not supported.

fix

Upgrade Node.js to v24 or later, or use Bun as runtime.

affects: >=0.1.0

deprecatedThe package is ESM-only. CJS require() will fail.

fix

Use import syntax or update tsconfig.json with "module": "ESNext".

affects: >=0.1.0

gotchabetter-sqlite3 is not a peer dependency and must be installed separately.

fix

Install better-sqlite3: npm install better-sqlite3.

affects: >=0.1.0

gotchaMigration files must export up and down as named async functions. Default exports are ignored.

fix

Ensure migration files use export const up = async (db) => { ... }; export const down = async (db) => { ... };

affects: >=0.1.0

gotchaThe migrationsDir must exist; sqlite-up does not create it automatically.

fix

Create the migrations directory (e.g., mkdir migrations) before running migration.apply().

affects: >=0.1.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Using require() on an ESM-only package in a CommonJS project.

fix

Switch to import syntax or set "type": "module" in package.json.

TypeError: db.exec is not a function

The db instance passed to Migrator is not a compatible SQLite database.

fix

Use one of: node:sqlite DatabaseSync, bun:sqlite Database, Bun SQL, or better-sqlite3 instance.

Error: Migration directory does not exist: ./migrations

The specified migrationsDir does not exist on disk.

fix

Create the directory (e.g., mkdir ./migrations) before running the migrator.

Upgrade

Version history

0.6.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node