Repository navigation
Conversation
…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>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
🚀 Preview DeploymentYour 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>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-721 This preview will update automatically when you push new commits. |
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>
cb1kenobi
changed the title
restore_backup checks a backup before replacing the database
…un exception Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
🚀 Preview DeploymentYour 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
marked this pull request as ready for review
October 14, 2026 03:05
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-721 This preview will update automatically when you push new commits. |
dawsontoth
approved these changes
Oct 19, 2026
|
|
||
| As of v5.3.1, subscriptions opened before a restore do not carry over to the restored data. When Harper reloads the database, each one ends, and its last message is a `DatabaseGenerationChangedError` (status code 409, code `DATABASE_GENERATION_CHANGED`). Resubscribe to resynchronize against the restored state. A restore that fails before it changes anything reloads the database as it was; those subscriptions end instead with a retryable `DatabaseClosingError` (status code 503, code `DATABASE_CLOSING`); resubscribe to continue. | ||
|
|
||
| As of v5.4.0, a restore checks the backup before it deletes anything. It verifies the checksum of every database file in the backup (not blob files), checks the backup's transaction logs, and opens each of its table files to confirm this version of Harper can read their format and compression. For a backup that captured blobs, it also checks that the blob snapshot is present. A backup that fails any of these is refused: the restore fails with an error saying it did not modify the database, followed by the cause, and the database keeps its data and its blobs. Previously the restore deleted the database first, so a backup this version could not read, such as one taken by a newer version of Harper, destroyed the database it was meant to restore. A rerun over an earlier restore that did not finish is the exception: that database is already incomplete, so it stays blocked until a restore succeeds, and the error says so. [`verify_backup`](#verify_backup) does not open the table files, so a backup it reports as valid can still be refused here for a format this version cannot read. |
Contributor
There was a problem hiding this comment.
Any way we could tuck "Previously the restore..." a bit more? It'll quickly become dated information, and unnecessary knowledge. Sticking it somehow under a collapsed < 5.4 section or something would let us identify it as old knowledge, and avoid communicating it to new users, you know?
Member
Author
There was a problem hiding this comment.
Addressed in 09082ba675bb.
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-721 This preview will update automatically when you push new commits. |
dawsontoth
approved these changes
Oct 19, 2026
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
⊙ Problem
HarperFast/harper#3121: Verify a backup can be read before restore_backup replaces the database changes
restore_backupin 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.verify_backupdoes not open tables.reference/backups/overview.md.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 buildpasses andnpm run format:checkis clean.dataLayer/rocksdbBackup.ts, marker timing indataLayer/restoreMarker.ts, and the design note indataLayer/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