Operations

Driver options

Choose a SQLite driver and check its connection, backup, encryption, and row-count capabilities.

Choose the driver for the runtime that opens the database. The database API is shared, while connection pooling, extensions, file backups, encryption, and row counts depend on the underlying SQLite engine.

Choose a driver

Every import below starts with @delali/sirannon-db/.

RuntimeImport and factoryRequired peer
Node.jsdriver/better-sqlite3, betterSqlite3()Install better-sqlite3 for the default engine.
Node.js with built-in SQLitedriver/node, nodeSqlite()Use Node.js 22.13 or later.
Browserdriver/wa-sqlite, waSqlite()Install wa-sqlite.
Bun, experimentaldriver/bun, bunSqlite()Use Bun's built-in SQLite.
React Native with Expo, experimentaldriver/expo, expoSqlite()Install expo-sqlite.

On Node, rowCounts: true or encryption: true selects the engine in @delali/sirannon-sqlite. Install that package at the same version as Sirannon. For the 0.4.1 release, both packages must be 0.4.1.

Check capabilities before using a feature

driver.capabilities contains multipleConnections, extensions, steppedCopy, rowCounts, and encryption. The table describes the released drivers:

DriverMultiple connectionsExtensionsStepped copyRow countsEncryption
better-sqlite3The driver supports them.The driver supports them.The driver supports it.Enable rowCounts.Enable encryption.
Node built-inThe driver supports them.The driver supports them.The Node build must export backup.The driver omits counts.The driver refuses keyed opens.
BunThe driver supports them.The driver supports them.The driver offers none.The driver omits counts.The driver refuses keyed opens.
wa-sqliteThe driver shares one connection.The driver offers none.The driver offers none.The driver omits counts.The driver refuses keyed opens.
ExpoThe driver shares one connection.The driver offers none.The driver offers none.The driver omits counts.Build the app with SQLCipher enabled.

db.backupCapabilities() provides the open database's more detailed backup capabilities. A missing stepped-copy implementation fails a file backup with BACKUP_UNSUPPORTED. Device snapshots transfer rows for runtimes that cannot copy a database file.

Configure better-sqlite3

Pass BetterSqlite3Options to betterSqlite3(options).

OptionDefaultBehaviour
busyTimeout5000SQLite waits this many milliseconds for a database lock.
vfsExtensionPathSirannon uses the installed platform extension when available.Supply a compiled extension for streamed backups.
rowCountsfalseThe driver opens through @delali/sirannon-sqlite and reports measured rows through query metrics.
encryptionfalseThe driver opens through Sirannon's encrypting SQLite build. An individual database also needs a key loader.
sqliteBindingPathSirannon locates the installed platform build.Supply another native binding when rowCounts or encryption is enabled.

The native package provides platform packages for Linux, macOS, and Windows on x64 and arm64. A platform name alone does not guarantee a compatible build; a binary can fail to load, for example when a glibc build meets a musl host. The driver reports ROW_COUNTS_UNSUPPORTED or ENCRYPTION_UNSUPPORTED for the requested feature.

For a platform without a usable published build, compile the native module from the release's native/sqlite directory and supply its path as sqliteBindingPath. See usage metering and encryption for complete examples.

Configure the other drivers

NodeSqliteOptions, passed to nodeSqlite, accepts busyTimeout, which defaults to 5000 milliseconds, and vfsExtensionPath for streamed backups. BunSqliteOptions, passed to bunSqlite, accepts busyTimeout with the same default.

WaSqliteOptions, passed to waSqlite, accepts vfs: 'IDBBatchAtomicVFS' or 'AccessHandlePoolVFS'. It defaults to IndexedDB through IDBBatchAtomicVFS.

expoSqlite() accepts no driver options. Encrypted opens require expo-sqlite 15.0.0 or later with SQLCipher enabled in the rebuilt app. Key changes also require expo-file-system 19.0.0 or later, which later app builds must retain for interrupted-change recovery.

Open separate connections with the right settings

sirannon.open accepts DatabaseOptions, while a direct driver.open accepts OpenOptions. The former uses readOnly, and the latter uses readonly.

For encryption, DatabaseOptions.encryption.key is a loader, while OpenOptions.encryption.key is the raw 32-byte Uint8Array. A replication writer and its snapshot connections must receive that key too. A Node driver without encryption: true refuses a keyed open even when the native package is installed.

Use file databases for Node registry examples that need separate readers. The registry creates at least one reader for a driver that supports multiple connections, even when readPoolSize is zero; separate :memory: connections do not share the same database.

Update a custom driver for 0.4

The public driver contract in 0.4 includes the rowCounts and encryption capability flags. Set them to reflect what the driver can provide, and refuse unsupported keyed opens with ENCRYPTION_UNSUPPORTED.

A driver that reports row counts provides the counted statement methods and includes counts in write results and failures. A driver that encrypts applies the key before accessing the database and preserves encryption when copying backups. The released driver contract specifies those obligations.