Skip to content

backups.verify(): open every backed-up table file so an unsupported format_version fails before restore #920

Description

@cb1kenobi

Summary

Add a check to backups.verify() that opens every table file in a backup, one at a time, so a backup this build can't read fails verification before anything is restored.

Today, backups.verify() checks file sizes, optionally checksums, and the transaction-log snapshot. None of those catches an SST written with a format_version this build doesn't support. A checksum-valid table in a newer format passes verify, and RocksDB only rejects it when something opens that table.

Why Harper needs this

harper#2965: restore_backup purges the destination before anything verifies the backup can be read. backups.restore(…, { mode: 'purgeAllFiles' }) deletes the database before it copies, so an unreadable backup destroys the database it was meant to restore.

harper#3121: Verify a backup can be read before restore_backup replaces the database is moving from stage-then-swap, which needs disk for a third copy, to checking the backup repository in place before the purge:

Failure Caught in place today?
Corrupt file Yes: backups.verify with verifyWithChecksum: true
Unreadable transaction-log header or framing Yes: backups.verify validates transaction_logs/<id>/ by default
Table file in an unsupported format_version, e.g. a backup from a newer build restored on an older one after a downgrade No. This issue.

Opening the restored database is not enough either. As Kris noted in the #3121 review, a database open can leave table files outside the table cache unopened, so a single unsupported SST can pass the open and fail on the first cold read.

Proposal

Add an option to backups.verify, for example verifyTables: true, that:

  1. Lists the backup's files with BackupEngine::GetBackupInfo(id, &info, /*include_file_details=*/true).
  2. Opens each .sst sequentially with rocksdb::SstFileReader::Open, then closes it before opening the next. File-descriptor use stays bounded no matter how many tables the backup has.
  3. Fails with a message that names the file and RocksDB's status, then stops. An unsupported version fails at footer decode (table/format.cc: Corrupt or unsupported format_version N for magic M), so Open alone proves the footer is readable by this build. Calling GetTableProperties() also checks the properties block.

Open questions for the implementer:

  • Should SstFileReader get the same Options a database open uses (comparator, table factory)? Defaults may be enough for an open-and-footer check.
  • Do blob files need the same treatment? The binding configures blob compression, so a backup can contain .blob files whose header carries a version.
  • Is SstFileReader::VerifyChecksum() (block-level checksums) worth offering? Harper already runs the whole-file checksum through verifyWithChecksum, so it isn't needed for this use.
  • Should the option be on by default? Harper will pass it explicitly either way.

Acceptance

  • A backup with one SST whose footer format_version is patched to an unsupported value fails verify(…, { verifyTables: true }), and the error names that file. (The format_version is the 4 bytes just before the 8-byte magic number.)
  • In a backup with more SSTs than the table cache or max_open_files holds, the patched file is still caught, and open file descriptors stay bounded during the check.
  • A healthy backup passes. Existing verifyWithChecksum and verifyTransactionLogs behavior is unchanged.
  • Types and docs for the new option.

Harper will bump to the release that ships this and call it from restore_backup before the purge.

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

Activity

  1. changed the title [-]backups.verify: open every backed-up table file so an unsupported format_version fails before restore[/-] [+]`backups.verify`: open every backed-up table file so an unsupported format_version fails before restore[/+] on Oct 12, 2026
  2. changed the title [-]`backups.verify`: open every backed-up table file so an unsupported format_version fails before restore[/-] [+]`backups.verify`: open every backed-up table file so an unsupported `format_version` fails before restore[/+] on Oct 12, 2026
  3. changed the title [-]`backups.verify`: open every backed-up table file so an unsupported `format_version` fails before restore[/-] [+]`backups.verify()`: open every backed-up table file so an unsupported `format_version` fails before restore[/+] on Oct 12, 2026
  4. self-assigned this
    on Oct 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Fields

Priority

P1

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions