Skip to content
Tutorials Center
My learning

Topics

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.

NODE
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

Node.js Replicating changes to a second database

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.

Node.js Choosing tables and handling conflicts

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

NODE
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.