Stamp the metadata format version and check it on connect - #90
Merged
Conversation
This was referenced Jul 20, 2026
This was referenced Jul 21, 2026
A single-row meta_version table records the version of the meta_* layout. It is created and stamped by the create=True bootstrap (on fresh databases and, as an upgrade path, on existing ones), and every connection refuses to run when the stored version does not match, with messages distinguishing a database that is newer than the code from one that is older. Databases from before the stamp existed are accepted unchanged. Fixes roed314#19. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A database with meta tables but no meta_version predates the stamp, which pins its format: it is now checked as format 1 rather than accepted blindly, so a future format bump rejects it until migrated instead of letting it slip through -- and create=True stamps it as 1, the format it actually has, never as the current version as a side effect of connecting. Fresh databases still bootstrap at the current format. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This was referenced Jul 21, 2026
Merged
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
2 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.
Fixes #19.
Stacked on #89 (which stacks on #88): based on the
join-queriesbranch. Independent of the other open PRs; merge order is free (pairwise merges verified locally on the full combined tree).A single-row
meta_versiontable records the version of the metadata layout, with the code's expectation declared asMETA_VERSION = 1in base.py next to the_meta_*column definitions it describes._bootstrap_meta(thecreate=Truepath) creates and stamps the table. A fresh database is stamped with the current format; a database that already had meta tables predates the stamp and is stamped with the pre-stamp baseline (1) — moving it to a newer format is a deliberate migration, never a side effect of connecting.META_VERSIONand raisesRuntimeErroron mismatch, distinguishing a database newer than the code ("upgrade psycodict") from one older ("migrate the meta_* tables"), plus an empty-table case. A database with meta tables but no stamp is checked as format 1 (review round: previously it was accepted blindly, which would have let unstamped format-1 databases slip past a futureMETA_VERSION = 2); a completely fresh database skips the check and gets the existing "connect with create=True" diagnosis.Tests: stamp present and correct after bootstrap; both mismatch directions plus the empty-table case; a stamp-less database connects and
create=Truestamps it; and a simulated future bump (META_VERSION + 1) rejects an unstamped database and stamps it as 1, not the new version. Suite 547/26 on this branch, ruff clean.Merge-order note (with the #3150 PR): whichever merges second has one positional conflict at the
__init__tail — keep this PR's check block, thenrefresh_tables().🤖 Generated with Claude Code