Node.js Reference ยท node:sqlite and Runtime Services
Node.js SQLite sessions and changesets
Reference for createSession() and applyChangeset() in node:sqlite: record row changes, produce changesets and patchsets, and replay them in another database.
A session records the row changes made to a database after the session was created. You can then turn those changes into a compact binary blob, a changeset, and apply it to another database with the same schema. This is how you replicate edits, ship small updates between copies of a database, or build undo and sync features.
You start a session with db.createSession(), make changes through normal SQL, and read the result with session.changeset(). The receiving database calls db.applyChangeset(changeset). Tracked tables must have a primary key, because rows are identified by it.
import { DatabaseSync } from 'node:sqlite'; const db = new DatabaseSync(':memory:'); db.exec('CREATE TABLE t (id INTEGER PRIMARY KEY, v TEXT)'); const session = db.createSession(); db.exec("INSERT INTO t (v) VALUES ('hello')"); const changeset = session.changeset(); // Uint8Array
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
db.createSession(options?: { table?: string, db?: string }): Session session.changeset(): Uint8Array session.patchset(): Uint8Array session.close(): void db.applyChangeset(changeset: Uint8Array, options?: { filter?: (tableName: string) => boolean, onConflict?: (conflictType: number) => number, }): boolean
| Name | Description |
|---|---|
options.table |
Track only this table. Without it, all tables with a primary key are tracked. |
options.db |
Name of the database to track, for attached databases. Default 'main'. |
changeset() |
Binary description of the changes: inserted rows, deleted rows (with old values) and updated columns (with old and new values). |
patchset() |
A smaller variant that omits the old values of updated and deleted rows. |
close() |
Stops tracking and frees the session. |
filter |
Called for each table in the changeset; return false to skip it. |
onConflict |
Called when a change cannot be applied cleanly; returns what to do (see below). |
Returns: applyChangeset() returns true if all changes were applied, and false if onConflict told SQLite to abort. Conflict handling returns one of the constants SQLITE_CHANGESET_OMIT (skip this change), SQLITE_CHANGESET_REPLACE (overwrite) or SQLITE_CHANGESET_ABORT (stop and roll back), exported in sqlite.constants.
Errors: tracking tables without a primary key silently records nothing for them. Applying a changeset to a database with a different schema fails or hits conflicts.
Usage notes
- Only changes after creation are recorded, and only on that connection. Changes made by other connections are not tracked.
- Rows need primary keys. A table without one is ignored by sessions.
- Changesets can be conflict-checked, because they carry the old values; patchsets cannot detect that an update clobbers a different value, so use them when you trust the target.
- Applying a changeset runs inside a transaction of its own and the call is synchronous.
- Close sessions you no longer need. An open session keeps recording and holding memory.
- A changeset is plain bytes, so you can store it in a file, send it over a socket or keep it in a BLOB column.
- Added in Node.js 23.3.0. The module is built in; the underlying SQLite is compiled with session support.