@dolthub/doltlite
Node.js native bindings for DoltLite — a SQLite fork that adds Git-style version control (branches, commits, merges, diffs, blame) to your SQL database.
Install
npm install @dolthub/doltlite
# or
bun add @dolthub/doltlite
Prebuilt binaries are provided for Linux x64/arm64, macOS x64/arm64, and Windows x64. On unsupported platforms the package builds from source via node-gyp, which requires a C/C++ toolchain and Python 3.
Drop-in compatibility with node:sqlite
DatabaseSync and StatementSync match the Node.js node:sqlite API exactly. Switch by changing one import line:
-import { DatabaseSync } from "node:sqlite"
+import { DatabaseSync } from "@dolthub/doltlite"
Basic usage
import { DatabaseSync } from "@dolthub/doltlite"
const db = new DatabaseSync("myapp.db")
db.exec(`CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)`)
const insert = db.prepare("INSERT INTO users (name) VALUES (?)")
insert.run("Alice")
insert.run("Bob")
const all = db.prepare("SELECT * FROM users")
console.log(all.all())
// [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
db.close()
Version control
All Dolt features are methods on DatabaseSync under dolt* names:
const db = new DatabaseSync("versioned.db")
db.exec(`CREATE TABLE orders (id INTEGER PRIMARY KEY, amount REAL)`)
db.exec(`INSERT INTO orders VALUES (1, 99.99)`)
// Commit the current state
const hash = db.doltCommit("initial data")
// Branch and make changes
db.doltBranch("experiment")
db.doltCheckout("experiment")
db.exec(`INSERT INTO orders VALUES (2, 49.99)`)
db.doltCommit("add order 2")
// See what changed
console.log(db.doltStatus())
console.log(db.doltLog({ limit: 5 }))
// Merge back to main
db.doltCheckout("main")
const result = db.doltMerge("experiment")
console.log(result) // { fast_forward: 0, conflicts: 0 }
// Inspect history
console.log(db.doltDiff("HEAD~1", "HEAD", "orders"))
console.log(db.doltHistoryOf("orders"))
console.log(db.doltBlameOf("orders"))
// Tag a release
db.doltTag("v1.0.0")
db.close()
You can also call Dolt SQL functions directly if you prefer:
db.exec("SELECT dolt_commit('-Am', 'my message')")
API
new DatabaseSync(path, options?)
| Option | Type | Default | Description |
|---|---|---|---|
open | boolean | true | Open immediately |
readOnly | boolean | false | Read-only mode |
node:sqlite-compatible methods
| Method | Description |
|---|---|
exec(sql) | Run SQL, no return value |
prepare(sql) | Compile a StatementSync |
close() | Close the connection |
open(path) | (Re-)open at path |
location() | Filesystem path, or null for :memory: |
createFunction(name, fn) | Register a scalar UDF |
.isOpen | true if connection is open |
.inTransaction | true if inside a transaction |
StatementSync
| Method | Returns |
|---|---|
run(...params) | { changes, lastInsertRowid } |
get(...params) | First row object, or undefined |
all(...params) | All row objects |
iterate(...params) | IterableIterator |
columns() | Column metadata array |
.sourceSQL | Original SQL text |
.expandedSQL | SQL with parameters expanded |
Dolt methods
| Method | Returns | Description |
|---|---|---|
doltCommit(message) | string (hash) | Stage all and commit |
doltBranch(name, from?) | void | Create a branch |
doltCheckout(branch) | void | Switch branch |
doltMerge(branch) | { fast_forward, conflicts } | Merge a branch |
doltReset(flag?) | void | Reset HEAD; pass "--hard" for hard reset |
doltAdd(table?) | void | Stage a table, or all tables |
doltStatus() | DoltStatusEntry[] | Working-set status |
doltLog(opts?) | DoltCommit[] | Commit history, newest first |
doltBranches() | DoltBranchInfo[] | All branches |
doltActiveBranch() | string | Currently checked-out branch |
doltDiff(from, to, table) | DoltDiffRow[] | Row-level diff between two refs |
doltHashOf(ref?) | string | Content hash of the DB at a ref |
doltVersion() | string | DoltLite version string |
doltTag(name) | void | Create a tag at HEAD |
doltTags() | DoltTagInfo[] | All tags |
doltHistoryOf(table) | object[] | Full row history across all commits |
doltBlameOf(table) | object[] | Per-row blame |
doltCherryPick(hash) | void | Cherry-pick a commit onto HEAD |
doltRevert(ref?) | void | Revert a commit (default: HEAD) |
binPath()
Returns the absolute path to the bundled doltlite CLI binary for the current platform. Useful when a consumer wants to spawn the shell directly — e.g. for an interactive db subcommand — rather than driving everything through the Node bindings.
import { binPath } from "@dolthub/doltlite"
import { spawn } from "child_process"
const child = spawn(binPath(), ["mydata.db"], { stdio: "inherit" })
Throws if no CLI build is bundled for the current platform/arch. (Upstream currently ships CLI tools for linux-x64, darwin-arm64, and win32-x64; the .node addon covers more platforms than the shell.)
Building from source
git clone https://github.com/dolthub/doltlite-node
cd doltlite-node
npm install # downloads amalgamation + compiles
bun test # run the test suite
Requirements: Python 3, and a C/C++ compiler (gcc/clang on Linux/macOS, MSVC Build Tools on Windows).
Versioning
The package version tracks the DoltLite version. @dolthub/[email protected] ships the DoltLite 0.11.8 amalgamation.
License
Apache-2.0. See DoltLite for the underlying library.