--- title: "Backup and recovery history" description: "Follow captured transactions from local DBH segments through object storage, controller acceptance, retention, and restore planning." section: "Architecture" source_url: "https://sqlstyle.com/docs/backup-and-recovery-history" --- SQLStyle's backup path begins with the same captured page records used for replication. DBH workers persist those records locally, and a separate storage owner validates, catalogs, and uploads finalized history to customer-owned S3-compatible storage. Network storage is not part of the database commit path. ## DBH becomes durable before it becomes remote The active DBH worker appends complete transactions from the capture ring. At a segment boundary, the second worker takes over ring consumption while the first finalizes the preceding file. Rotation occurs only between transactions. The storage owner hashes and syncs the finalized bytes, then records the exact local artifact in the durable catalog. This `sealed local` state is the boundary between DBH continuity and remote upload. Losing the only valid copy threatens continuity; an unavailable object store does not. Failed uploads remain cataloged and retry with bounded backoff while capture and later DBH rotation continue. Local DBH has two uses before upload: finalized segments extend replica catch-up beyond the capture ring, while the active prefix gives a same-host capture successor an exact continuation boundary. That active prefix is same-boot handoff state, not machine-crash durability. Live replication never downloads an uploaded DBH object to recreate local catch-up history. ## The catalog advances only through continuous history Each DBH object identifies its database, authority token, transaction range, size, and checksum. Uploads may finish out of transaction order, but the catalog's uploaded transaction advances only through the highest continuous prefix. A later segment in the bucket cannot conceal a missing earlier range. On successful upload, the catalog atomically changes the local record to uploaded before the file becomes eligible for local eviction. Inventory refresh reconciles remote presence, size, checksums, and object metadata without holding the catalog lock during network I/O. ## Full snapshots provide recovery bases Incremental DBH needs a compatible full snapshot from which replay can begin. SQLStyle takes an exact SQLite read view and stores it either as a full DBH snapshot or as a SQLite snapshot object. Scheduled and manual snapshots use the same serialized snapshot path. If neither the local nor uploaded copy of an incremental segment validates, the catalog records a lineage break and schedules a new full snapshot. Capture and incremental upload may continue while that snapshot is produced, but restore does not bridge the missing range by assumption. ## The controller fences authoritative storage progress Object storage can contain valid bytes beyond the recovery point the controller has published. This is expected: normal uploads do not require a controller write for every segment, and a former primary may finish an upload after its token has become stale. Before a restore or other non-primary reader selects authoritative objects, it requests an object-storage read fence from the controller. If the current primary is connected, the controller asks it for the cached highest contiguous uploaded transaction for the current token. That request does not flush SQLite, seal DBH, create a snapshot, start an upload, or pause writes. The controller accepts the response only from the current holder, durably advances its recovery frontier, and returns the fenced value to the reader. Advancing that frontier counts as one [controller-state write](/docs/controller-state-writes). Returning the frontier already held by the controller does not. If authority changes while the request is in flight, the stale response cannot advance the frontier. If no primary is connected, the controller returns the last durable frontier it already holds. Once a reader has received a fenced frontier, later recovery and promotion may advance it but cannot roll it back. Objects beyond that frontier remain speculative. Recovery may validate and propose a later continuous frontier, but the data becomes authoritative only through the controller's recovery transition and the next fencing token. ## Restore builds one verified chain Restore combines the controller's accepted frontier with the object inventory. It selects an exact snapshot base and continuous DBH replay range, then validates object identity, size, checksum, transaction coverage, and commit boundaries before materializing SQLite. Latest restore may begin from a raw SQLite snapshot or a full DBH snapshot. Point-in-time restore uses a DBH snapshot base so replay can stop at the selected commit timestamp. Neither path trusts an object merely because its key or modification time makes it appear newest. ## Retention preserves recovery plans, not just ages The retention schedule selects recovery intervals, but deletion is governed by recoverability. SQLStyle waits for a newer uploaded snapshot generation, removes candidate objects from a trial inventory, and reruns the recovery obligations before deleting anything. Shared DBH ranges remain protected when any retained plan still needs them. Connected replica watermarks and active catch-up leases add local-history floors, preventing retention or eager eviction from removing DBH still required by a live session. See [object storage](/docs/object-storage) for configuration and [point-in-time recovery](/docs/restore-and-recovery) for inventory, verification, and restore commands.