feat: on-disk DB format-version guard (txpool + blockchain)#4
Open
orrinfrazier wants to merge 1 commit into
Open
feat: on-disk DB format-version guard (txpool + blockchain)#4orrinfrazier wants to merge 1 commit into
orrinfrazier wants to merge 1 commit into
Conversation
Persist a `format_version` marker (u64 little-endian under `b"format_version"`) in the `metadata` keyspace of both the txpool and blockchain fjall databases, and verify it on open: a fresh DB is stamped, a matching version proceeds, and a mismatched or malformed version is refused with `DbFormatVersionMismatch` (never panics), leaving room for a future migration step. - txpool: activate the previously-unused `metadata` keyspace (drop the `#[expect(dead_code)] // TODO: version?`), add `DATABASE_FORMAT_VERSION`, and change `open_with_database` to return `Result<Self, TxPoolError>`. - blockchain: check/stamp the existing `DATABASE_VERSION` before `Tapes::open` so an incompatible database is refused without creating any tape files. Resolves the S04-1 beta blocker: without this marker, a future tapes/keyspace schema change on a shipped v0.1.0 database could not be detected and would silently misread or panic instead of refusing.
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
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.
Closes #14
Summary
Adds an on-disk schema/format-version marker to both fjall databases (txpool + blockchain) and a guard that refuses to start on mismatch — closing the S04-1 beta blocker. Without a persisted version, any future tapes/keyspace schema change on a shipped v0.1.0 database could not be detected, and a newer binary would silently misread or panic instead of refusing/migrating.
What changed
A
format_versionvalue (u64little-endian) is persisted underb"format_version"in each DB'smetadatakeyspace at creation, and verified on every open:DbFormatVersionMismatch { expected, found }(returned, never panics), leaving room for a future migration stepPer piece:
storage/txpool/src/txpool.rs,error.rs): activate the previously-unusedmetadatakeyspace (dropped#[expect(dead_code)] // TODO: version?), addDATABASE_FORMAT_VERSION, add the error variant, and changeopen_with_database→Result<Self, TxPoolError>(sole callerinit_with_poolalready returnsTxPoolError, so no caller change).storage/blockchain/src/database.rs,error.rs): reuse the existingconstants::DATABASE_VERSION; check/stamp it beforeTapes::openso an incompatible DB is refused without creating any tape files. Added the error variant +tempfiledev-dep.Open question (resolved)
Fjall 3.0.4's internal
FormatVersion(V1/V2/V3) guards only fjall's own LSM disk format per major release — not the application schema (keyspace layout, value encodings, tapes layout). So an app-level marker is still required.How to test
10 new tests cover all branches in both crates: fresh-stamp, reopen-with-match, mismatch → error, and malformed-value → error (no panic), plus a
db_version()sanity check.Notes
cuprate-typesdead-code warnings (PoolTxInfo,default_zero) andcargo auditadvisories in transitive deps (rsa,rustls-webpki,lz4_flex,bincode,paste).