Configuration reference

This page lists every option Sirannon accepts, grouped by the object that takes it. The guides explain what each one is for; this page is where you check a name, a type, or a default without reading a guide first.

An option marked required has no default and the call fails without it. An option with a dash for its default is absent unless you set it, and the description says what Sirannon does in its absence.

Opening databases

`SirannonOptions`

Passed to new Sirannon(options). See getting started.

Option	Type	Default	Description
`driver`	`SQLiteDriver`	required	The driver adapter for your runtime.
`hooks`	`HookConfig`	-	Hooks that Sirannon calls around queries and connections, and that the server calls before a subscription, a snapshot, or a device push.
`metrics`	`MetricsConfig`	-	Callbacks for query timing with the rows that each statement returns or changes, for database open and close, and for each change event that Sirannon delivers to a subscriber.
`lifecycle`	`LifecycleConfig`	-	Automatic opening, idle timeout, and a cap on databases open at once.
`migrations`	`MigrationSource`	-	A migration set, or a function returning one, applied to every writable database before it registers.
`writerWorker`	`boolean \| WriterWorkerOptions`	-	The writer-worker setting that every database in this registry inherits.
`cdcRetention`	`number`	-	The change-log retention in milliseconds for every database that this registry opens without its own.
`deviceCursorRetention`	`number`	-	The device-cursor retention in milliseconds for every database that this registry opens without its own.
`maxChangesHeldForDevice`	`number`	-	The limit on changes that one device's cursor holds back, for every database that this registry opens without its own.

`LifecycleConfig`

See hooks, metrics, and lifecycle.

Option	Type	Default	Description
`autoOpen.resolver`	`(id: string) => { path, options? } \| undefined`	-	Resolves an unknown identifier to a file path, which is how a tenant opens on first access.
`idleTimeout`	`number`	`0`	Milliseconds before an idle database closes. Zero disables the timer.
`maxOpen`	`number`	`0`	Databases open at once before the least recently used one closes. Zero leaves the count unbounded.

createTenantResolver builds a resolver from a basePath, an optional file extension, and defaultOptions that it applies to every tenant that it opens.

`DatabaseOptions`

Passed to sirannon.open(id, path, options).

Option	Type	Default	Description
`readOnly`	`boolean`	`false`	Open the database read-only, which refuses every write.
`readPoolSize`	`number`	`4`	Read connections the pool holds, on a driver that supports several connections.
`walMode`	`boolean`	`true`	Whether to enable write-ahead logging.
`synchronous`	`'off' \| 'normal' \| 'full' \| 'extra'`	`'normal'`	Writer durability through `PRAGMA synchronous`. A bulk load restores this level when it finishes.
`cdcPollInterval`	`number`	`50`	Milliseconds between change capture polls.
`cdcRetention`	`number`	`3600000`	Milliseconds that change history stays available to replay.
`deviceCursorRetention`	`number`	`2592000000`	Milliseconds that a device's cursor may hold changes back, 30 days by default. Sirannon deletes the cursor once the device's last acknowledgement, or the oldest change that the cursor holds back, is older than this, and that device then resyncs from a snapshot.
`maxChangesHeldForDevice`	`number`	`0`	Most changes that one device's cursor may hold back before Sirannon deletes the cursor, counting only changes that other writers made. Zero sets no limit.
`writerWorker`	`boolean \| WriterWorkerOptions`	`false`	Run writes on a dedicated thread. See writer worker.
`backups`	`BackupCycleOptions`	-	Capture this database's write-ahead log to a destination on an interval. See continuous backups.

`WriterWorkerOptions`

Option	Type	Default	Description
`maxPendingWrites`	`number`	`1024`	Writes in flight before new writes are refused with `WRITE_OVERLOADED`.
`writeTimeoutMs`	`number`	`30000`	Per-operation deadline in milliseconds. Zero disables it.
`maxRestarts`	`number`	`5`	Respawns allowed after the worker crashes, before writes fail with `WRITER_WORKER_FATAL`.

`OpenOptions`

Passed to driver.open(path, options) and to ConnectionPool.create, which application code reaches only when it opens a connection outside a Sirannon registry.

Option	Type	Default	Description
`readonly`	`boolean`	`false`	Open the connection read-only.
`walMode`	`boolean`	`true`	Whether to enable write-ahead logging.
`synchronous`	`SynchronousLevel`	`'normal'`	Writer durability the connection runs at.
`walAutoCheckpoint`	`number`	-	Frames the log may reach before SQLite checkpoints it on its own. Zero turns that off, which a database capturing its own log needs, and `sirannon.open` sets it to zero for you whenever `backups` is present.

Running statements

`QueryOptions`

Passed per call to query, execute, executeBatch, and a registered operation.

Option	Type	Default	Description
`readConcern`	`{ level: 'local' \| 'majority' \| 'linearizable' }`	-	How current the read must be. Coordinator mode enforces it and static mode ignores it.
`writeConcern`	`{ level, timeoutMs? }`	a local commit in static mode, `'majority'` in coordinator mode	How many nodes must acknowledge the write. `timeoutMs` defaults to 5,000. A replica that forwards the write sends this concern with it, and the primary waits for it.

`BulkLoadOptions`

Option	Type	Default	Description
`durability`	`'off' \| 'normal'`	`'off'`	Durability in force while the load runs.
`checkpoint`	`boolean`	`true`	Whether the load ends with a checkpoint. A database opened with `backups` runs none whatever you set.

`LiveQueryOptions`

Option	Type	Default	Description
`rereadJitterMs`	`number`	`25`	Upper bound on the random delay before a second read starts.
`maxTransactionChanges`	`number`	`10000`	Buffered changes in one transaction before the query reads a second time.

Both options reach a local db.live only, because a remote subscription sends no options and the server opens the query with these defaults. UseLiveQueryOptions in the React entry adds enabled, which holds a query closed while it is false.

Backups

`BackupCycleOptions`

Passed as backups in DatabaseOptions. See continuous backups.

Option	Type	Default	Description
`destination`	`BackupDestination`	required	Where the full copy, the change pieces, and the chain records go.
`intervalMs`	`number`	`60000`	Milliseconds between captures. Zero means the cycle takes a turn only when you call `captureBackupChanges`.
`fullCopyIntervalMs`	`number`	`86400000`	Milliseconds a chain runs before a fresh full copy starts a new one.
`chainName`	`string`	`'sirannon-backup-chain'`	Name the destination stores the list of chains under.
`namePrefix`	`string`	`'sirannon-backup'`	What each backup is named after at the destination.
`pieceBytes`	`number`	`16777216`	Bytes one whole piece holds. A streamed copy needs a multiple of 512.
`fingerprint`	`boolean`	`true`	Whether each backup records a SHA-256 of what it wrote.
`stagingDir`	`string`	a directory beside the database file	Where a capture waits before it goes out.
`maxUncapturedLogBytes`	`number`	unbounded	Bytes the write-ahead log may reach across turns that capture nothing.
`replicationGroup`	`BackupGroupSource`	-	Where this node reads its group's membership. See backups in a replication group.
`preferredNode`	`'replica' \| 'primary' \| { nodeId }`	`'replica'`	Which node of that group takes the backups.
`pagesPerStep`	`number`	`256`	Pages SQLite moves in one step of the full copy.
`restartLimit`	`number`	`3`	Restarts the full copy absorbs before it fails with `BACKUP_RESTARTED`.
`noProgressStepLimit`	`number`	`256`	Steps the copy may take without reaching a page it had not already copied.
`stallTimeoutMs`	`number`	`30000`	Milliseconds the copy may go without completing a step before it fails with `BACKUP_STALLED`.
`destinationTimeoutMs`	`number`	`600000`	Milliseconds one call to the destination may take. Zero leaves the calls unbounded.
`onRun`	`(report: BackupRunReport) => void`	-	Called with the report of every backup the cycle finishes.
`onProgress`	`(progress: BackupProgress) => void`	-	Called after each copy step and after each stored piece while a turn proceeds.
`onSkip`	`(skip: BackupSkip) => void`	-	Called with every turn the cycle passed over, and what it passed it over for.
`onError`	`(error: Error) => void`	-	Called when a capture, a transfer, or a checkpoint fails. Set it.

`BackupToDestinationOptions`

Passed to db.backupTo(options). See backup destinations.

Option	Type	Default	Description
`destination`	`BackupDestination`	required	Where the pieces go and where a restore reads them from.
`name`	`string`	`backup-{ISO timestamp}.db`	Name the pieces are stored under.
`chainId`	`string`	an identifier the run mints	The chain this copy begins.
`pieceBytes`	`number`	`16777216`	Bytes one whole piece holds.
`fingerprint`	`boolean`	`true`	Whether the run folds a SHA-256 over what it wrote.
`pagesPerStep`	`number`	`256`	Pages SQLite moves in one step.
`restartLimit`	`number`	`3`	Restarts the copy absorbs before it fails.
`noProgressStepLimit`	`number`	`256`	Steps the copy may take without reaching a new page.
`stallTimeoutMs`	`number`	`30000`	Milliseconds the copy may go without completing a step.
`destinationTimeoutMs`	`number`	`600000`	Milliseconds one call to the destination may take.
`stagingDir`	`string`	the host temporary directory	Directory the staged route writes its local file in.
`onProgress`	`(progress: BackupProgress) => void`	-	Called during the copy and once per piece during the transfer.

`BackupScheduleOptions`

Passed to db.scheduleBackup(options). See backups.

Option	Type	Default	Description
`cron`	`string`	required	Five fields for minute resolution, or six to add seconds at the front.
`destDir`	`string`	required	Directory each copy is written into.
`maxFiles`	`number`	`5`	Copies matching `backup-*.db` to keep, by modification time.
`timezone`	`string`	the host zone	IANA name the cron expression is read in.
`onBackup`	`(report: BackupFileReport) => void \| Promise<void>`	-	Called after every finished copy, before the older files are cleared.
`onBackupTimeoutMs`	`number`	`600000`	Milliseconds Sirannon waits for `onBackup`. Zero leaves the wait unbounded.
`onError`	`(error: Error) => void`	-	Called with every failure. Set it.

`BackupRestoreOptions`

Passed to restoreBackup(options) from @delali/sirannon-db/backup. See restoring a database.

Option	Type	Default	Description
`destination`	`BackupDestination`	required	Where the backups and their records are stored.
`driver`	`SQLiteDriver`	required	Driver the restore opens the rebuilt database through.
`destPath`	`string`	required	Path the rebuilt database is written to.
`moment`	`number`	now	Epoch milliseconds you want back.
`chainName`	`string`	`'sirannon-backup-chain'`	Name the list of chains is stored under.
`replaceExisting`	`boolean`	`false`	Whether to replace a database already at that path.
`batchSize`	`number`	`16`	Change pieces replayed between one checkpoint and the next, up to 4,096.
`destinationTimeoutMs`	`number`	`600000`	Milliseconds one call to the destination may take.
`onProgress`	`(progress: BackupRestoreProgress) => void`	-	Called after every piece the restore fetches.

Serving over the network

`ServerOptions`

Passed to createServer(sirannon, options). See server.

Option	Type	Default	Description
`host`	`string`	`'127.0.0.1'`	Bind address.
`port`	`number`	`9876`	Listen port.
`cors`	`boolean \| CorsOptions`	`false`	Cross-origin configuration.
`maxBodyBytes`	`number`	`1048576`	Largest HTTP body and WebSocket message, as a positive integer no larger than 4,294,967,295.
`maxWebSocketBackpressureBytes`	`number`	the larger of `16777216` and `maxBodyBytes`	Bytes buffered per connection before the server closes it.
`cdcRetentionMs`	`number`	`3600000`	Milliseconds change events stay available, which bounds how far back `sinceSeq` resumes.
`deviceCursorRetentionMs`	`number`	`2592000000`	Milliseconds that a device's cursor may hold changes back before the server deletes it, 30 days by default. A database's own `deviceCursorRetention` overrides it.
`maxChangesHeldForDevice`	`number`	`0`	Most changes that one device's cursor may hold back before the server deletes it. Zero sets no limit, and a database's own option overrides it.
`maxUnacknowledgedChanges`	`number`	`1000`	How far past its acknowledged sequence a device may get before delivery pauses.
`authenticate`	`AuthenticateHook<Identity>`	-	Runs before every database route and WebSocket upgrade.
`operations`	`OperationRegistry<Identity>`	-	Reads and writes this server serves by name, keyed by database identifier.
`sharedOperations`	`DatabaseOperations<Identity>`	-	Reads and writes this server serves by name on every database, including one that the registry opens after the server starts. A database's own entry in `operations` takes precedence over a shared operation of the same name.
`acceptSql`	`boolean`	`false`	Whether the server accepts SQL statements over the network, and subscriptions to a table's changes on a registry with no `onBeforeSubscribe` hook.
`acceptBackupRestore`	`boolean`	`false`	Whether the server rebuilds a database from its backups over the network. A server that sets it without `authenticate` refuses to start, with `INVALID_BACKUP_RESTORE`.
`acceptDeviceSync`	`boolean`	`false`	Whether the server serves device sync. A server that sets it without `authenticate` refuses to start, with `INVALID_DEVICE_SYNC`.
`resolveExecutionTarget`	`ServerExecutionTargetResolver`	-	Resolves the target each database runs against, which is how replication enforces authority.
`getReplicationStatus`	`() => ReplicationStatusInfo \| null`	-	Feeds `GET /health/ready` with replication state.
`getClusterStatus`	`(databaseId: string) => ClusterStatusInfo \| null`	-	Feeds `GET /db/{id}/cluster` with routing metadata.
`authorizeClusterStatus`	`ClusterStatusAuthorizer`	-	Your check for whether a request may read cluster status, which names every node address.

`ClientOptions`

Passed to new SirannonClient(url, options). See client SDK.

Option	Type	Default	Description
`transport`	`'websocket' \| 'http'`	`'websocket'`	Transport the client uses.
`headers`	`Record<string, string>`	-	Headers on HTTP requests, and on the WebSocket upgrade under Node and Bun. A browser client that sets it without `webSocketProtocols` on the WebSocket transport fails with `INVALID_ARGUMENT`.
`webSocketProtocols`	`string \| string[]`	-	Subprotocols offered during the upgrade, which is how a browser sends a credential. The client offers `sirannon.v1` ahead of them.
`autoReconnect`	`boolean`	`true`	Whether to reconnect after a WebSocket disconnect.
`reconnectInterval`	`number`	`1000`	Reconnect delay in milliseconds.
`requestTimeout`	`number`	`30000`	Per-request timeout in milliseconds on the WebSocket transport. Zero waits indefinitely.

`TopologyAwareClientOptions`

Accepted by TopologyAwareClient from @delali/sirannon-db/client/topology, alongside every ClientOptions field. SirannonClient refuses each of these with INVALID_ARGUMENT. See topology-aware routing.

Option	Type	Default	Description
`endpoints`	`string[]`	-	Starter list that coordinator mode queries for routing metadata.
`primary`	`string`	-	Primary endpoint used directly in static mode.
`replicas`	`string[]`	-	Replica endpoints used directly in static mode.
`readPreference`	`'primary' \| 'replica' \| 'nearest'`	`'primary'`	Which node serves a read.
`discovery`	`'static' \| 'coordinator'`	`'static'`	Whether routing comes from your configuration or from `GET /db/{id}/cluster`.
`readConcern`	`'local' \| 'majority' \| 'linearizable'`	`'majority'` in coordinator mode	Client-wide read concern applied to node selection.

`LoadAllOptions`

Option	Type	Default	Description
`batchSize`	`number`	`1000`	Rows per request. Each batch has to fit under the server's `maxBodyBytes`.
`durability`	`'off' \| 'normal'`	`'off'`	Durability in force on the server while each batch loads.

Device sync

`SyncControllerOptions`

Passed to new SyncController(db, options). See device sync.

Option	Type	Default	Description
`url`	`string`	required	Base URL of the server.
`databaseId`	`string`	required	Database to sync against, under the identifier the server opened it with.
`tables`	`readonly string[]`	required	Tables the device syncs.
`headers`	`Record<string, string>`	-	Headers on push, snapshot, and migration requests, and on the pull upgrade under Node and Bun.
`webSocketProtocols`	`string \| string[]`	-	Subprotocols offered on the pull upgrade, which is how a browser device sends a credential.
`batchSize`	`number`	`100`	Changes per push request.
`pushIntervalMs`	`number`	`1000`	Push loop interval, which is also the base for retry backoff.
`ackIntervalMs`	`number`	`2000`	Milliseconds between the device's acknowledgements of applied changes.
`maxPushRetryDelayMs`	`number`	`30000`	Ceiling for push and pull retry backoff.
`requestTimeout`	`number`	`30000`	HTTP request timeout in milliseconds.
`autoResync`	`boolean`	`true`	Whether to download a snapshot on start, on a server resync signal, and after a failed download.
`snapshotRetryDelayMs`	`number`	`5000`	First delay before retrying a failed snapshot.
`maxSnapshotRetryDelayMs`	`number`	`300000`	Ceiling for snapshot retry backoff.
`snapshotPageSize`	`number`	`500`	Rows per snapshot page.
`immediateAckAfterChanges`	`number`	half the server's window	Outstanding changes that trigger an immediate acknowledgement.
`resolver`	`ConflictResolver \| ((table: string) => ConflictResolver)`	`LWWResolver`	Conflict resolution for pulled changes.
`onChange`	`(event: ChangeEvent) => void`	-	Called for each pulled change after it commits locally.
`onStatusChange`	`(status: SyncStatus) => void`	-	Called with the device's status on a state change, a push, an applied pull batch, a required resync, and an error recorded or cleared.
`onResyncRequired`	`() => void`	-	Called before a snapshot replaces local data.
`onSnapshotProgress`	`(progress: SnapshotProgress) => void`	-	Table and row progress during a snapshot.
`onSnapshotComplete`	`(outcome: SnapshotOutcome) => void`	-	Called once a snapshot load ends, reporting whether the local database is usable again.

`SnapshotDownloadOptions`

Accepted by downloadDatabaseSnapshot(db.deviceSync(), options), which copies a server database into a local one outside a SyncController. See device sync recovery.

Option	Type	Default	Description
`url`	`string`	required	Base URL of the server.
`databaseId`	`string`	required	Database to copy.
`headers`	`Record<string, string>`	-	Headers sent on the manifest and page requests.
`pageSize`	`number`	`500`	Rows per snapshot page.
`requestTimeoutMs`	`number`	`30000`	Per-request timeout in milliseconds.
`onProgress`	`(progress: SnapshotProgress) => void`	-	Table and row progress during the copy.

Replication

`ReplicationOptions`

Passed to new ReplicationEngine(db, writerConn, options). See distributed replication.

Option	Type	Default	Description
`nodeId`	`string`	generated in static mode	Node identifier. Coordinator mode needs a stable, persisted value.
`topology`	`Topology`	required	The topology this node runs under, such as `PrimaryReplicaTopology`.
`transport`	`ReplicationTransport`	required	Transport for node-to-node traffic.
`transportConfig`	`TransportConfig`	`{}`	Peer endpoints and transport metadata.
`writeForwarding`	`boolean`	`false`	Whether a replica forwards writes to the primary.
`defaultConflictResolver`	`ConflictResolver`	`LWWResolver`	Default conflict resolution.
`conflictResolvers`	`Record<string, ConflictResolver>`	-	Per-table conflict resolution overrides.
`batchSize`	`number`	`100`	Changes per replication batch.
`batchIntervalMs`	`number`	`100`	Sender loop interval in milliseconds.
`maxClockDriftMs`	`number`	`60000`	Largest clock gap between two nodes this node accepts before it rejects a batch.
`maxPendingBatches`	`number`	`10`	In-flight batches per peer before back-pressure.
`maxBatchChanges`	`number`	`1000`	Changes accepted in one inbound batch.
`ackTimeoutMs`	`number`	`5000`	Batch acknowledgement timeout in milliseconds.
`initialSync`	`boolean`	`true`	Whether to pull a full snapshot when joining a cluster.
`syncBatchSize`	`number`	`10000`	Rows per batch during first sync.
`maxConcurrentSyncs`	`number`	`2`	Simultaneous sync sessions the source serves.
`maxSyncDurationMs`	`number`	`1800000`	Milliseconds before the source abandons a sync.
`maxSyncLagBeforeReady`	`number`	`100`	Catch-up lag, in sequences, at which a node reaches ready.
`syncAckTimeoutMs`	`number`	`30000`	Per-batch acknowledgement timeout during sync.
`catchUpDeadlineMs`	`number`	`600000`	Milliseconds in catch-up before a node moves to ready.
`resumeFromSeq`	`bigint`	-	Sequence to start replication from, for an out-of-band sync.
`snapshotConnectionFactory`	`() => Promise<SQLiteConnection>`	-	Opens the read-only connections a source serves a sync from.
`changeTracker`	`ChangeTracker`	-	Change-capture trigger manager, which first sync needs.
`flowControl`	`{ maxLagSeconds?, onLagExceeded? }`	-	Replication lag monitoring callbacks.
`onBeforeForwardedQuery`	`(sql, params?) => void`	-	Validation hook the primary runs before each forwarded statement.
`coordinator`	`CoordinatorModeConfig`	-	Turns on coordinator-backed authority and failover.

`CoordinatorModeConfig`

Option	Type	Default	Description
`clusterId`	`string`	required	Coordinator namespace for the cluster.
`groupId`	`string`	required	Replication group holding copies of one database.
`endpoint`	`string`	-	Application endpoint advertised for client discovery.
`votingDataBearingNodeIds`	`string[]`	-	Voter set used to create an unregistered group and to calculate write concerns.
`coordinator`	`ClusterCoordinator`	required	Coordinator adapter, such as the etcd one.
`sessionTtlMs`	`number`	`10000`	Node-session lease lifetime in milliseconds.
`controller`	`boolean \| CoordinatorControllerConfig`	enabled	Turns the controller loop on, or configures its lease holder, lifetime, and tick interval.
`compatibility`	`CoordinatorCompatibilityMetadata`	-	Package, specification, and protocol versions checked before promotion.

CoordinatorControllerConfig accepts enabled, holderId, leaseTtlMs (10,000 milliseconds by default), and tickIntervalMs (1,000 milliseconds by default).

`EtcdClusterCoordinatorOptions`

Accepted by createEtcdCoordinator from @delali/sirannon-db/replication/coordinator/etcd.

Option	Type	Default	Description
`hosts`	`string \| string[]`	required	etcd endpoints. Each has to use `https` unless you set `allowInsecure`.
`keyPrefix`	`string`	required	Key namespace this cluster writes under.
`credentials`	etcd credentials	-	Root certificate, private key, and certificate chain for mutual TLS.
`auth`	etcd auth	-	Username and password authentication.
`grpcOptions`	`Record<string, unknown>`	-	Options passed through to the etcd gRPC channel.
`dialTimeoutMs`	`number`	the etcd client's own default	Connection timeout in milliseconds.
`defaultCallTimeoutMs`	`number`	-	Deadline applied to each coordinator call, in milliseconds.
`allowInsecure`	`boolean`	`false`	Allows plain `http` endpoints, so keep it to tests.
`onWatcherError`	`(error: Error) => void`	-	Called when a coordinator watcher fails.

`TransportConfig`

ReplicationEngine.start() fills in the role, the group, the term, and the protocol version. Set them yourself only when you use a ReplicationTransport without the engine.

Option	Type	Description
`endpoints`	`string[]`	Peer addresses replication connections are made to.
`localRole`	`'primary' \| 'replica'`	Local topology role.
`groupId`	`string`	Replication group named in coordinator-mode handshakes.
`primaryTerm`	`bigint`	Current fencing term, taken from coordinator state.
`protocolVersion`	`string`	Replication protocol version advertised to peers.
`metadata`	`Record<string, unknown>`	Custom transport metadata.

`GrpcReplicationOptions`

Accepted by GrpcReplicationTransport from @delali/sirannon-db/transport/grpc.

Option	Type	Default	Description
`host`	`string`	`'0.0.0.0'`	Address this node listens on for replication traffic.
`port`	`number`	`0`	Listen port. Zero takes an ephemeral one.
`tlsCert`	`string`	-	Path to this node's certificate.
`tlsKey`	`string`	-	Path to this node's private key.
`tlsCaCert`	`string`	-	Path to the certificate authority that signs every peer.
`insecure`	`boolean`	`false`	Runs without TLS, so keep it to local development.
`forwardDeadlineMs`	`number`	`30000`	Deadline in milliseconds for a write forwarded to the primary, including the time that the primary waits for the write concern.