SQLite (node:sqlite)

Owners: @nodejs/sqlite. Public docs at doc/api/sqlite.md.

Purpose

Expose SQLite as a built-in Node module. The intent is to give scripts a zero-dependency local store: synchronous prepared statements, transactions, ATTACH, custom functions, blobs, and basic backup support.

Directory layout

lib/sqlite.js                  // public re-export
src/node_sqlite.{cc,h}         // the entire binding (~134K LOC)
deps/sqlite/                   // amalgamated SQLite source

lib/sqlite.js is essentially module.exports = internalBinding('sqlite');. All implementation lives in src/node_sqlite.cc and the vendored amalgamation.

Key abstractions

Type / file	Role
DatabaseSync (node_sqlite.cc)	Synchronous SQLite database handle.
StatementSync (node_sqlite.cc)	Prepared statement; iterators, .get(), .all(), .iterate().
Session (node_sqlite.cc)	Session-extension support (changesets/patchsets).
BackupJob (node_sqlite.cc)	Async backup using ThreadPoolWork.

The synchronous nature is deliberate: SQLite operations are typically very fast and the runtime cost of dispatching to a worker thread per query is high. For long-running queries, BackupJob and the future async query support live in node_sqlite.cc.

Permission model

Access to the file system flows through the FS permission domain — opening a database file at /tmp/foo.db requires --allow-fs-read=/tmp/foo.db --allow-fs-write=/tmp/foo.db.

Integration points

• Streams: db.backup returns a Promise that surfaces progress events; not stream-shaped.
• Diagnostics channel: node:sqlite.statementCreated and similar channels are published for tracing.
• Vendored SQLite: tools/dep_updaters/update-sqlite.sh bumps deps/sqlite/.

Entry points for modification

• Bug in API surface? src/node_sqlite.cc is the single source. The functions are grouped: connection, statement, session, backup.
• Add a feature flag? lib/sqlite.js is too thin — add it to src/node_sqlite.cc (the constructor accepts an options object) and document in doc/api/sqlite.md.
• Tests live at test/parallel/test-sqlite*.js and the larger fixture suites at test/sqlite/.