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

# 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.

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

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](#upgrade-from-040).

## 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:

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

The [getting-started guide](/docs/getting-started) covers the driver and optional server packages. The [0.3 documentation](/docs/0.3) 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](/docs/distributed-replication) 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](/docs/distributed-replication#conflict-resolution) and [device sync](/docs/device-sync#resolve-a-row-edited-on-two-devices) 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](/docs/backups-in-a-cluster).

## 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](/docs/queries-and-transactions), [bulk loads](/docs/bulk-load), and [writer workers](/docs/writer-worker).

## 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](/docs/error-codes#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](/docs/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](/docs/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](/docs/coordinator-failover#when-the-primary-confirms-a-majority-write) 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](/docs/coordinator-failover#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](/docs/coordinator-failover#upgrade-a-group-from-040) 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](/docs/python-client) and the [Go client](/docs/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](/docs/configuration) and [error reference](/docs/error-codes) describe each field and refusal. The [release changelog](https://github.com/assetcorp/sirannon-db/blob/v0.4.1/CHANGELOG.md) lists the changes in each release.
