Repository navigation
Description
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:
- Lists the backup's files with
BackupEngine::GetBackupInfo(id, &info, /*include_file_details=*/true). - Opens each
.sstsequentially withrocksdb::SstFileReader::Open, then closes it before opening the next. File-descriptor use stays bounded no matter how many tables the backup has. - 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), soOpenalone proves the footer is readable by this build. CallingGetTableProperties()also checks the properties block.
Open questions for the implementer:
- Should
SstFileReaderget the sameOptionsa 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
.blobfiles whose header carries a version. - Is
SstFileReader::VerifyChecksum()(block-level checksums) worth offering? Harper already runs the whole-file checksum throughverifyWithChecksum, 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_versionis patched to an unsupported value failsverify(…, { verifyTables: true }), and the error names that file. (Theformat_versionis the 4 bytes just before the 8-byte magic number.) - In a backup with more SSTs than the table cache or
max_open_filesholds, the patched file is still caught, and open file descriptors stay bounded during the check. - A healthy backup passes. Existing
verifyWithChecksumandverifyTransactionLogsbehavior 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
[-]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[/+][-]`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[/+][-]`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[/+]