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}

kriszyp · 2026-10-14T03:11:21Z

 From the CLI with the server stopped, `target_database=<name>` restores into a separate database instead of overwriting the source. The target must not already exist, or must be an empty directory; Harper picks the new database up on the next start.

-If a restore is interrupted before it completes (crash, power loss), Harper marks the database as incompletely restored and refuses to load it on the next start, logging an incomplete-restore error. Recover by rerunning `restore_backup` for the same database and `backup_id` — do not try to load or hand-repair the directory.
+If a restore is interrupted (crash, power loss) after it has started replacing the database's files, Harper marks the database as incompletely restored and refuses to load it on the next start, logging an incomplete-restore error. Recover by rerunning `restore_backup` for the same database and `backup_id` — do not try to load or hand-repair the directory. As of v5.4.0, an interruption while the backup is still being checked leaves the database untouched and unmarked, and it loads normally on the next start.


Please limit the final sentence's restart guarantee to a database that was not already marked incomplete. For example, after one restore fails during replacement, rerun restore_backup and interrupt it during verification: the earlier marker remains, so the database still cannot load on restart. The core feature branch preserves that marker when claiming a recovery attempt; verification does not clear it. This is code-trace evidence, not an executed crash test.

Suggested wording: “An interruption during verification leaves the destination's files and any preexisting incomplete-restore marker unchanged; a previously healthy database loads normally on the next start.” Apply the same qualification to the interruption sentence in release-notes/v5-lincoln/5.4.md:65, so both pages agree with the recovery exception already described in reference/backups/operations.md:119.

Addressed in 17ea4eabb093.

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.

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

Open

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

Address review feedback on #721

17ea4ea

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

View deployment

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 wants to merge 10 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!

kriszyp Oct 14, 2026

Uh oh!

cb1kenobi Oct 14, 2026

Uh oh!

github-actions Bot commented Oct 14, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 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!

kriszyp Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

cb1kenobi Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Oct 14, 2026

🚀 Preview Deployment

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cb1kenobi commented Oct 8, 2026 •

edited

Loading