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`	-	Before and after hooks for queries, connections, and subscriptions.
`metrics`	`MetricsConfig`	-	Callbacks for query timing, connection events, and change-capture activity.
`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 every database this registry opens inherits.

`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 applied to every tenant 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 change history stays available to replay.
`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.

`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 move no pages 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 at step resolution 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 move no pages.
`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 an idle device cursor lasts, 30 days by default.
`maxUnacknowledgedChanges`	`number`	`1000`	How far a device may run past its acknowledged sequence 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.
`acceptSql`	`boolean`	`false`	Whether the server accepts SQL statements over the network.
`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`.
`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.