Document that `restore_backup` checks a backup before replacing the database by cb1kenobi · Pull Request #721 · HarperFast/documentation

cb1kenobi · 2026-10-08T20:31:29Z

⊙ Problem

HarperFast/harper#3121: Verify a backup can be read before restore_backup replaces the database changes restore_backup in 5.4. The backup reference still describes the old close-purge-restore order, and this PR's earlier text described a staging design the core PR has since dropped.

💡 Solution

Document the shipped behavior as of v5.4.0: a restore checks the backup in place before it deletes the database, needs no extra disk, and refuses a backup this version can't read with the database left as it was. An online restore's check runs inside its downtime, and a crash during the check leaves the database loadable.

🔧 Changes

reference/backups/operations.md, restore_backup.
- A v5.4.0 "changed" badge and the new order: close, check, restore, reload.
- What the check covers: checksums of every database file (not blob files), the transaction logs, each table file's format and compression, and a declared blob snapshot's presence. Also what a refusal says, the exception for a rerun over an incomplete restore, and that verify_backup does not open tables.
- What it costs: one extra read of the backup, inside the downtime for an online restore, with no extra disk. Writes during that time fail rather than being lost. Blob contents are not checked.
- Interruptions: only an interruption after the restore has started replacing files leaves the database blocked. One during the check leaves it loadable.
reference/backups/overview.md.
- A Limitations bullet for the check, including the incomplete-rerun exception, and the interrupted-restore bullet scoped to after replacement begins.
- The worked example names the check in the online order.
release-notes/v5-lincoln/5.4.md. A "Restore Checks a Backup Before Deleting the Database" entry under a new Backups section. The 5.3 entry this PR used to add is removed.

✅ Verification

npm run build passes and npm run format:check is clean.
Every behavior claim was checked against the core branch at its current head: verification order and coverage in dataLayer/rocksdbBackup.ts, marker timing in dataLayer/restoreMarker.ts, and the design note in dataLayer/DESIGN.md. The core branch's unit tests cover each claim (refusals online and offline, check-after-close, a loadable database after a claim that never reached the purge).

_{🤖 Generated by Anthropic Claude (Opus); posted via @cb1kenobi.}

Related PRs: none found
Complexity: easy

_{Review-Coverage: authored=claude; ran=gemini,cursor-composer,codex,cursor-muse; adjudicated=domain; declined=cursor-grok,cursor-kimi; rounds=5; full=3 @ 7fb257e}

_{Review-Attention: skim ~2m (decisions: summary-brevity) @ 7fb257e}

…base Documents HarperFast/harper#3121: restore stages and opens the backup first, refuses one it cannot read with the database untouched, needs free space for a second copy, and cannot restore a database whose directory is a symlink. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…unt points and 5.3.2 Docs review round 1: blobs are neither staged nor checked, so the guarantee is stated for the database files only; the refusal message is quoted by its phrase rather than as a suffix; staging space is the backup's restored size and a rerun after an interrupted swap can need one more copy; mount-point database directories are refused like symlinks (core change in the same PR); and the 5.3 release notes record the behavior change. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…fit, and when the aside copy goes Docs review round 2: an online restore stages while the database keeps serving, and writes made then are replaced; a staging copy without headroom is refused with 507 (core change in the same PR); an uninterrupted restore removes the set-aside copy itself; a crash during staging leaves the files untouched but blocked; the refusal comes from "the restore", which offline has no job; and the release note counts transaction logs in the space needed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…hind Docs review round 3: a refused rerun over an unfinished restore leaves the database blocked, not untouched; a rerun needs no more room than the first attempt (core drops the stale candidate first); repointing a symlinked path after an interrupted restore needs an offline rerun before the next start; the overview's worked example describes staging; and a restore refused before the database closes leaves its subscriptions running (verified against the branch). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…efore-replace

github-actions · 2026-10-08T20:36:29Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-721

This preview will update automatically when you push new commits.

Gemini review on #721: per the docs guidelines, a patch-level behavior change to an existing operation carries a `changed` VersionBadge, under the heading and inline in the Limitations item. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-08T20:42:43Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-721

This preview will update automatically when you push new commits.

…efore-replace

The restore no longer stages a copy. It verifies the backup in place (checksums, transaction logs, every table file's format and compression, and the presence of a declared blob snapshot) before it deletes the database, needs no extra disk space, and checks after an online restore has closed the database. Moves the release note from 5.3 to 5.4 to match the harper PR's milestone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…un exception Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-10-14T02:55:22Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-721

This preview will update automatically when you push new commits.

kriszyp

_{🤖 Reviewed with Codex}

github-actions · 2026-10-14T20:35:13Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-721

This preview will update automatically when you push new commits.

github-actions · 2026-10-19T18:47:41Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-721

This preview will update automatically when you push new commits.

github-actions · 2026-10-20T07:33:24Z

🧹 Preview Cleanup

The preview deployment for this PR has been removed.

cb1kenobi and others added 5 commits October 8, 2026 13:59

Merge remote-tracking branch 'origin/main' into docs/restore-verify-b…

b91aaf3

…efore-replace

cb1kenobi mentioned this pull request Oct 8, 2026

Verify a backup can be read before restore_backup replaces the database HarperFast/harper#3121

Merged

This comment was marked as resolved.

Sign in to view

github-actions Bot temporarily deployed to pr-721 October 8, 2026 20:36 Inactive

github-actions Bot temporarily deployed to pr-721 October 8, 2026 20:42 Inactive

cb1kenobi and others added 2 commits October 13, 2026 16:24

Merge remote-tracking branch 'origin/main' into docs/restore-verify-b…

80ec9a1

…efore-replace

cb1kenobi changed the title ~~Document that restore_backup checks a backup before replacing the database~~ Document that restore_backup checks a backup before replacing the database Oct 13, 2026

Scope the restore check to database files and note the incomplete-rer…

7fb257e

…un exception Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions Bot temporarily deployed to pr-721 October 14, 2026 02:55 Inactive

cb1kenobi marked this pull request as ready for review October 14, 2026 03:05

cb1kenobi requested a review from a team as a code owner October 14, 2026 03:05

kriszyp approved these changes Oct 14, 2026

View reviewed changes

Comment thread reference/backups/operations.md Outdated

Address review feedback on #721

17ea4ea

github-actions Bot temporarily deployed to pr-721 October 14, 2026 20:35 Inactive

dawsontoth approved these changes Oct 19, 2026

View reviewed changes

Comment thread reference/backups/operations.md Outdated

Address review feedback on #721

09082ba

github-actions Bot temporarily deployed to pr-721 October 19, 2026 18:47 Inactive

dawsontoth approved these changes Oct 19, 2026

View reviewed changes

cb1kenobi mentioned this pull request Oct 20, 2026

verify_backup passes a backup that restore_backup then refuses, because it doesn't check that tables are readable HarperFast/harper#3318

Open

4 tasks

cb1kenobi merged commit 9a6c408 into main Oct 20, 2026
13 checks passed

cb1kenobi deleted the docs/restore-verify-before-replace branch October 20, 2026 07:31

Navigation Menu

Repository navigation

Document that `restore_backup` checks a backup before replacing the database - #721

Document that `restore_backup` checks a backup before replacing the database#721
cb1kenobi merged 11 commits into
mainfrom
docs/restore-verify-before-replace

cb1kenobi commented Oct 8, 2026 •

edited

Loading

Uh oh!

This comment was marked as resolved.

Uh oh!

github-actions Bot commented Oct 8, 2026

Uh oh!

github-actions Bot commented Oct 8, 2026

Uh oh!

github-actions Bot commented Oct 14, 2026

Uh oh!

kriszyp left a comment

Uh oh!

Uh oh!

github-actions Bot commented Oct 14, 2026

Uh oh!

Uh oh!

github-actions Bot commented Oct 19, 2026

Uh oh!

Uh oh!

github-actions Bot commented Oct 20, 2026

Uh oh!

This branch was previously deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

cb1kenobi commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⊙ Problem

💡 Solution

🔧 Changes

✅ Verification

Uh oh!

This comment was marked as resolved.

Uh oh!

github-actions Bot commented Oct 8, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Oct 8, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Oct 14, 2026

🚀 Preview Deployment

Uh oh!

kriszyp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Oct 14, 2026

🚀 Preview Deployment

Uh oh!

Uh oh!

github-actions Bot commented Oct 19, 2026

🚀 Preview Deployment

Uh oh!

Uh oh!

github-actions Bot commented Oct 20, 2026

🧹 Preview Cleanup

Uh oh!

This branch was previously deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cb1kenobi commented Oct 8, 2026 •

edited

Loading