> Complete content index: https://sirannon.sondelali.com/llms.txt

# Driver options

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

URL: https://sirannon.sondelali.com/docs/drivers
Section: Operations
Version: 0.4 (@delali/sirannon-db@0.4.1, latest)

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/`.

| Runtime | Import and factory | Required peer |
| --- | --- | --- |
| Node.js | `driver/better-sqlite3`, `betterSqlite3()` | Install `better-sqlite3` for the default engine. |
| Node.js with built-in SQLite | `driver/node`, `nodeSqlite()` | Use Node.js 22.13 or later. |
| Browser | `driver/wa-sqlite`, `waSqlite()` | Install `wa-sqlite`. |
| Bun, experimental | `driver/bun`, `bunSqlite()` | Use Bun's built-in SQLite. |
| React Native with Expo, experimental | `driver/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:

| Driver | Multiple connections | Extensions | Stepped copy | Row counts | Encryption |
| --- | --- | --- | --- | --- | --- |
| better-sqlite3 | The driver supports them. | The driver supports them. | The driver supports it. | Enable `rowCounts`. | Enable `encryption`. |
| Node built-in | The driver supports them. | The driver supports them. | The Node build must export `backup`. | The driver omits counts. | The driver refuses keyed opens. |
| Bun | The driver supports them. | The driver supports them. | The driver offers none. | The driver omits counts. | The driver refuses keyed opens. |
| wa-sqlite | The driver shares one connection. | The driver offers none. | The driver offers none. | The driver omits counts. | The driver refuses keyed opens. |
| Expo | The 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](/docs/device-sync-recovery) transfer rows for runtimes that cannot copy a database file.

## Configure better-sqlite3

Pass `BetterSqlite3Options` to `betterSqlite3(options)`.

| Option | Default | Behaviour |
| --- | --- | --- |
| `busyTimeout` | `5000` | SQLite waits this many milliseconds for a database lock. |
| `vfsExtensionPath` | Sirannon uses the installed platform extension when available. | Supply a compiled extension for streamed backups. |
| `rowCounts` | `false` | The driver opens through `@delali/sirannon-sqlite` and reports measured rows through query metrics. |
| `encryption` | `false` | The driver opens through Sirannon's encrypting SQLite build. An individual database also needs a key loader. |
| `sqliteBindingPath` | Sirannon 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](/docs/usage-metering) and [encryption](/docs/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](https://github.com/assetcorp/sirannon-db/blob/v0.4.1/packages/spec/01-driver.md) specifies those obligations.
