refactor: DB snapshot copy specs into descriptors#7375
Open
francesco-stacks wants to merge 9 commits into
Open
refactor: DB snapshot copy specs into descriptors#7375francesco-stacks wants to merge 9 commits into
francesco-stacks wants to merge 9 commits into
Conversation
francesco-stacks
requested review from
benjamin-stacks,
Copilot,
cylewitruk-stacks and
federico-stacks
July 2, 2026 08:27
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refactors snapshot DB copying so each snapshot DB defines a DbSnapshotSpec descriptor that owns its static table-copy specs (including schema-only tables) and any runtime bind requirements, making the copy-spec list the single source of truth for table classification and copy behavior.
Changes:
- Introduces descriptor-driven snapshot specs (
DbSnapshotSpec) plusTableCopySpec/TableCopySource/TableCopyBindandTableCopySpecshelpers to centralize table sets and runtime bind handling. - Refactors SPV, sortition, index, burnchain, and Nakamoto staging snapshot copy code to use static SQL templates with
?Nbinds instead of runtime-formatted SQL strings. - Moves snapshot-only helper reads out of DB impls into snapshot-scoped extension traits and updates snapshot drift/guard tests accordingly.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| stackslib/src/chainstate/stacks/db/snapshot/tests/spv.rs | Updates SPV copy-spec well-formedness guard to use TableCopySpecs and schema-only assertions. |
| stackslib/src/chainstate/stacks/db/snapshot/tests/sortition.rs | Updates sortition copy-spec guards and adds boundary invariance tests for spec table sets/ordering. |
| stackslib/src/chainstate/stacks/db/snapshot/tests/index.rs | Simplifies index copy-spec guard to focus on duplicate detection with descriptor-derived tables. |
| stackslib/src/chainstate/stacks/db/snapshot/tests/burnchain.rs | Updates burnchain copy-spec guard to use TableCopySpecs and clarifies schema-only overrides. |
| stackslib/src/chainstate/stacks/db/snapshot/tests/blocks.rs | Updates Nakamoto staging copy-spec guard to use TableCopySpecs and schema-only assertions. |
| stackslib/src/chainstate/stacks/db/snapshot/spv.rs | Introduces SpvDbSnapshotSpec, converts SPV specs to static templates with explicit bind kinds. |
| stackslib/src/chainstate/stacks/db/snapshot/sortition.rs | Introduces SortitionDbSnapshotSpec, adds snapshot extension trait reads, and refactors boundary-sensitive memo SQL to static templates with binds. |
| stackslib/src/chainstate/stacks/db/snapshot/index.rs | Introduces IndexDbSnapshotSpec, makes schema-only tables explicit in specs, and refactors reward-cycle filtering to use binds. |
| stackslib/src/chainstate/stacks/db/snapshot/common.rs | Adds TableCopySource/TableCopyBind/TableCopySpecs and DbSnapshotSpec; updates copy execution to support runtime binds. |
| stackslib/src/chainstate/stacks/db/snapshot/burnchain.rs | Introduces BurnchainDbSnapshotSpec, moves snapshot-only reads into extension traits, and makes overrides schema-only via specs. |
| stackslib/src/chainstate/stacks/db/snapshot/blocks.rs | Introduces NakamotoStagingDbSnapshotSpec and refactors staging/microblock copy-spec definitions to static slices. |
| stackslib/src/chainstate/burn/db/sortdb.rs | Removes snapshot-only helper methods from SortitionDB impl (moved to snapshot extension traits). |
| stackslib/src/burnchains/db.rs | Removes snapshot-only helper from BurnchainDB impl (moved to snapshot extension traits). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
francesco-stacks
marked this pull request as ready for review
July 2, 2026 11:09
| let spec_set: HashSet<&str> = specs.iter().copied().collect(); | ||
| assert_eq!(specs.len(), spec_set.len(), "duplicate spec tables"); | ||
| assert_eq!(spec_set, copied); | ||
| fn test_index_copy_specs_well_formed() { |
Contributor
There was a problem hiding this comment.
sanity-check: do we need test coverage for schema_only tables? (for index and burnchain)?
Contributor
Author
There was a problem hiding this comment.
yeah they were not properly covered (only for the microblocks) 44329be
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.
Description
This PR refactors the DB snapshot copy logic so each snapshot DB owns a
DbSnapshotSpecdescriptor. Copy specs now act as the single source of truth for row-copied tables, schema-only tables, table classification, and runtime SQL bind requirements.TableCopySource,TableCopySpecs,TableCopyBind, and per-DBDbSnapshotSpecimplementations.The change was motivated by these suggestions:
Applicable issues
Additional info (benefits, drawbacks, caveats)
Checklist
docs/property-testing.md)changelog.d/README.md)rpc/openapi.yamlfor RPC endpoints,event-dispatcher.mdfor new events)clarity-benchmarkingrepo