Replication and catch-up

Physical replication connects each replica directly to the current primary. The controller supplies topology and authority state, but it does not relay the page stream. The replica writes the received transactions into the SQLite database on its own disk and serves reads from that local database.

Acknowledgements track committed replica state

A replication session is bound to the database, both node identities, the current primary token, and a session generation. It begins with the transaction after the replica’s last authenticated local commit.

For each page, the replica either applies a difference to the expected predecessor or decompresses a self-contained LZ4 payload. It commits the pages with the primary’s transaction boundary and database size, then acknowledges the transaction. Progress from a replaced session, a stale primary token, or a position that does not end at a commit cannot advance the replica’s durable frontier.

The acknowledgement is not part of the primary’s commit. A primary transaction may return before any replica has made it durable; replication durability is a later fact recorded by the session.

Catch-up uses ring, DBH, then rsync

The primary satisfies a replica’s next required transaction from three sources, in order:

1. Retained capture-ring records for the current live tail.
2. Local DBH segments for older transactions still present on the primary.
3. One rsync replacement when neither local source contains the required point.

The transition from DBH to live capture uses a short overlap. Capture pins the live edge, the replica commits everything before that edge, and only then does the session release its DBH claim and attach to live delivery. The two sources do not need a shared sequence number, but the handoff cannot leave a transaction gap.

Uploaded DBH objects are not fetched into a live replication session. Object storage remains a restore and promotion-recovery source; replica catch-up depends only on history local to the current primary before it falls back to rsync.

Slow replicas lose their live cursor

The capture ring is bounded, and a live replica does not hold a ring position while it is catching up through DBH or rsync. If a new reservation would overtake an attached replica’s cursor, capture revokes that attachment, retires any locally borrowed transport buffers, and reclaims the ring space. The session then resumes from its last acknowledged transaction through DBH.

Ring reclamation does not wait for a remote acknowledgement or for the replica to complete its catch-up. If the required DBH has also expired, the session requires snapshot replacement.

Rsync installs an exact replacement image

For a missing or history-stale replica, the primary pins an exact SQLite read snapshot and runs the existing sqlite3-rsync protocol over the replication session. The replica stages the snapshot transaction before replacement and publishes it as durable only after SQLite commits the new image.

Streaming then resumes at the transaction after the snapshot. A session performs at most one automatic rsync replacement; subsequent progress uses DBH and live capture. A lost final acknowledgement may cause the primary to retry session work, but it cannot make the replica discard a replacement image SQLite already committed.

A primary change creates new sessions

When authority moves, the replacement primary creates sessions bound to its new token and recovered state. The former primary’s connections and session generations cannot publish progress into that lineage. A replica may become the replacement only when it is promotion-capable and covers the controller’s required recovery transaction.

Trusted-network mode removes transport protection

SQLStyle’s trusted-network transport disables encryption and authentication for post-handshake QUIC 1-RTT application traffic. It provides no confidentiality, integrity, or peer authentication for replication records and must be confined to a private, access-controlled network in which on-path traffic manipulation is an accepted risk.

Deployments crossing a public, shared, or otherwise untrusted network must use SQLStyle’s TLS transport mode with the configured CA, peer certificate, and controller-published database certificate fingerprint. That mode retains encrypted and authenticated 1-RTT traffic.