Getting started

Upgrading to 0.4

Update a 0.3.4 or 0.4.0 deployment for the metering, replication, transaction, encryption, and client changes in 0.3.5, 0.4.0, and 0.4.1.

An upgrade from 0.3.4 to 0.4.1 includes the metering and reliability changes in 0.3.5, the encryption in 0.4.0, and the replication and client changes in 0.4.1. Encryption is optional, so upgrading the package leaves a plaintext database as plaintext until your application requests encryption. A deployment on 0.4.0 needs only the changes in 0.4.1.

Update the packages used by your deployment

Update @delali/sirannon-db to 0.4.1 through your package manager. Encryption and row counts on Node also require @delali/sirannon-sqlite at 0.4.1. The latter package installs the native build for the host's operating system and architecture.

Check the installed versions before deploying:

pnpm list @delali/sirannon-db @delali/sirannon-sqlite

The getting-started guide covers the driver and optional server packages. The 0.3 documentation remains available for an application using the earlier API.

Review coordinator-mode configuration

In coordinator mode, each node publishes its client address as endpoint and its peer address as replicationEndpoint. Remove transportConfig.endpoints from coordinator-mode engines and the endpoints map passed to toClusterStatusInfo. Sirannon obtains those addresses from the members' live sessions, and configured address lists fail with TOPOLOGY_ERROR. Static mode continues to use configured addresses.

Retain the node's stable nodeId when replacing a disk or restarting a process. A restarted session replaces the earlier session under that identifier. Sirannon requires proof of the current data before admitting a rebuilt copy to the in-sync set.

Use addVoter and removeVoter for membership changes. A new voter remains pending while it copies the data, so it counts towards no majority until admission. The coordinator refuses to remove the current primary or to leave too few in-sync voters for a majority.

Coordinator-backed failover is stable. Follow the replication guide for maintenance, recovery, forwarded transactions, and the released compatibility checks. Test mixed-version operation against the safety requirements of your deployment before a rolling upgrade, because a compatible version number alone does not establish compatible safety behaviour.

Recheck conflict and backup assumptions

Last-writer-wins compares delete timestamps with update timestamps, so a later update overrides an earlier remote delete. A later insert can also recreate a deleted row. Both replication and device sync use this rule.

A backup preference of { nodeId } requires that node to be eligible in the membership returned by readMembership. A coordinator-backed source excludes nodes outside the in-sync set and nodes marked draining, repairing, or faulted. A pinned node therefore needs membership access too. See backups in a replication group.

Use transaction handles within their callback

A Transaction handle expires when its callback returns or throws. Later calls fail with TRANSACTION_CLOSED.

On wa-sqlite and Expo, use the callback's tx for reads and writes. Calls through db that need the writer fail with WRITER_HELD_BY_CALLBACK while the callback has that connection. bulkLoad inside a transaction callback fails with BULK_LOAD_IN_TRANSACTION.

A writer-worker crash rolls back an active callback transaction, and later statements in that callback fail with WRITER_WORKER_EXIT. After a failed durability restore following a bulk load, Sirannon refuses later writes until it can restore the configured durability. See transactions, bulk loads, and writer workers.

Check changes, subscriptions, and shutdown

Change capture reports rows deleted by REPLACE conflict handling before the replacement write. Watched table identifiers match ASCII letter case as SQLite does. Views and virtual tables cannot be watched. Live queries support rowid aliases where the change events contain the required rowid.

Device pushes can split one transaction across batches while preserving atomic application on the server. When the server removes a connected device's cursor, it closes that connection with 4410 so that the device reconnects and reconciles its state. A subscription cursor beyond the database's latest sequence requires a resync too.

Close the server before shutting down its registry. server.close({ timeoutMs }) drains requests within the deadline and closes WebSockets with 1001. Handle the documented WebSocket close codes, including payload and back-pressure refusals.

Enable metering or encryption explicitly

Set rowCounts: true on the better-sqlite3 driver to receive rowsRead and rowsWritten. A failed statement can consume reads, and a timed-out writer can report its counts after the caller stops waiting. Treat an absent count separately from zero. See usage metering.

For encryption, enable encryption: true on the Node driver and pass a key loader at open. Existing plaintext files need changeEncryption. Retain both keys until a rotation ends, and retain each backup chain's key while that chain exists. A completed file replacement can report done with reopenError; the new key is already in force at that point. See encryption.

Upgrade from 0.4.0

In coordinator mode, a majority write in 0.4.1 waits for every copy in the in-sync set while that set holds most of the voters. The primary removes a replica from that set when the replica leaves a change unacknowledged for longer than coordinator.maxReplicaLagMs, which defaults to 1,000 milliseconds, so keep that setting well below your write-concern timeout. Coordinator failover explains the rule.

When a former primary rejoins the group, it undoes every write that only it holds and keeps a copy of each one in _sirannon_rolled_back_changes. Read those records with rolledBackChanges(engine) from @delali/sirannon-db/replication, then decide which ones your application writes again. Reconcile history after failover describes the record.

Restart a 0.4.0 group one node at a time, then raise its feature level to 2 once every node holds a live session on 0.4.1. Upgrade a group from 0.4.0 gives the order and the refusals.

The code generator in 0.4.1 writes Python and Go references as well as TypeScript, through --python and --go, and it accepts a manifest through --from-manifest. The Python client and the Go client call the server through those references. The TypeScript output matches 0.4.0, so a regenerated --out file stays the same.

GET /db/:id/backup leaves the source path out of the last run, and it reports a fixed message for an unexpected failure. The restore report leaves out the destination path. A dashboard that shows either path has to take it from your configuration.

Read the release notes

The configuration reference and error reference describe each field and refusal. The release changelog lists the changes in each release.