---
title: "Replication and catch-up"
description: "Follow a replica from live page delivery through local DBH catch-up, ring-pressure eviction, and rsync replacement."
section: "Architecture"
source_url: "https://sqlstyle.com/docs/replication"
---
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.