Rules: SQLite

Last updated 29 October 2026

Check these rules before you change SQLite settings or point another tool at a database: each keeps the database working with Tonbo.

The examples use the connection open() returns, a node:sqlite DatabaseSync, as Connect opens it.

Leave the journal mode and the page size alone

open() sets up WAL mode with 4 KiB pages. A transaction that leaves WAL mode, changes the page size or writes in exclusive locking mode fails with unsupported, and the database stays usable (see Requirements).

const db = await open("notes"); // WAL mode with 4 KiB pages, already set up

db.exec("PRAGMA journal_mode = DELETE"); // fails with unsupported
db.exec("PRAGMA page_size = 8192"); // fails with unsupported

Reach the data only through the connection open() returns

The files in the cache directory are not SQLite files without the package, so other tools fail with SQLITE_NOTADB and change nothing, and a copy they could open would never reach Tonbo. Run migrations in the app (see Use with Drizzle), and export a plain copy for other tools (see Export a copy).

migrate(drizzle({ client: db }), { migrationsFolder: "./drizzle" }); // in the app
db.prepare("VACUUM INTO ?").run("/exports/notes.db"); // a plain copy any tool opens

// From a shell, on the cache directory:
//   npx drizzle-kit migrate      fails with SQLITE_NOTADB
//   sqlite3 notes-cache/.../db   fails with SQLITE_NOTADB