Introducing litevolve: versioned SQLite migrations for Bun, Node, and Deno

#sqlite #bunjs #node #deno

Just published litevolve, a small migration runner for SQLite that works as a library or a CLI.

Right now it's early (v0.2.1), but I'm using it in real Bun projects, so it's time to make people juggle with it.

What's addressing?

Most SQLite migration tools in the JS ecosystem ask you to either hand-roll up/down functions in JS, or generate migrations from a schema-diff tool.

Both work, but both add a layer between you and the SQL you're actually running. litevolve skips that layer: you write plain, numbered .sql files, and it applies them in order.

What is it today?

Plain SQL files, no DSL. Migrations are just 0001_create_initial_schema.sql. No JS functions to write, no schema file to keep in sync, no code generation step.
Up, down, and seeds as first-class files. 0001_create_initial_schema.down.sql rolls it back. And 0001_create_initial_schema.seed.sql optionally seeds it. Down migrations are explicit SQL you control, not an auto-generated inverse.
Transactional by version. Each migration step (schema + its seed) runs inside one BEGIN IMMEDIATE transaction. If the seed fails, the schema change it belongs to rolls back too.
No shadow migrations table. The current version lives in SQLite's own PRAGMA user_version. Seed preference (init_seeds) is tracked in a tiny internal _db_meta table and is sticky — once a database is seeded or not at v0, that choice sticks for every future migration on it.
Zero runtime dependencies. Bun uses bun:sqlite directly; Node and Deno use node:sqlite (DatabaseSync) through a small adapter. No better-sqlite3, nothing to compile.
Library or CLI. Call migrate_db(...) from code, or run bunx litevolve-bun / npx litevolve-node with no install.
One core, shared everywhere. All the migration logic lives in a single src/core that's mirrored byte-for-byte across the three runtime packages, so a fix or a feature in one place reaches all of them.

What's not here yet — being upfront about it

Deno support is not tested yet. litevolve-deno is published to npm to reserve the name, but the adapter isn't finished. If you're on Deno, use litevolve-node via an npm: specifier until this lands. (Or litevolve-node becomes official for Deno)
No Docker image yet. The multi-arch Dockerfile exists and is smoke-tested in CI, but nothing is pushed to a registry yet.
No standalone binaries in releases. They're built and tested in CI, just not attached to GitHub releases yet.
No package-manager listings beyond npm, no Homebrew, no Snap.

What's coming next

Fix and ship Deno support
Docker image
Homebrew / other package managers. Once binaries are released, tap a formula.

Try it

bun add litevolve-bun
# or
npm install litevolve-node

import { migrate_db } from "litevolve-bun"

const db = migrate_db(
  2,                 // target schema version, or undefined for "latest"
  "./migrations",
  "./data/app.db",
  true,              // init_seeds — only honored on a fresh database
)

Source, docs, and the full runtime comparison are on GitHub official page. It's MIT licensed. Issues and feedback are welcome.

DEV Community