docs: document the graphman copy commands - #6717
Open
cargopete wants to merge 2 commits into
Open
Conversation
…equence that replaces it
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.
docs/graphman.mddocuments Info, Remove, Unassign, Unused Record, Unused Remove, Drop, Check Blocks and Chain Call Cache Remove, but notcopy. This adds Copy Create, Copy Activate, Copy List and Copy Status in the same format as the existing sections, and adds them to the index.Moving a deployment between database shards is a routine operation for anyone running more than one shard, and
graphman copyis the supported way to do it, but at the moment the only way to find that out is--helpor the source. The behaviour that makes it the right tool rather than a hand-rolled dump and restore is also the least discoverable part of it: batching to avoid long-running transactions, adaptive batch size, backing off on replication lag, and resuming after an interrupted run.Content is derived from the command definitions in
node/src/bin/manager.rs, the pre-flight checks innode/src/manager/commands/copy.rs, the copy machinery and its module documentation instore/postgres/src/copy.rs, and theOnSyncvariants instore/postgres/src/deployment.rs. The SYNOPSIS blocks reproduce the clap definitions, in the style of the existing sections.Second commit: the Drop section documents a removed command
While checking the existing sections against the CLI I found that
docs/graphman.mdcarries a full⌘ Dropsection, synopsis and options and all, for a command that no longer exists. There is noDropvariant inpub enum Command, and the stringDelete a deployment and all its indexed dataappears in exactly one file in the repository: the doc itself.NEWS.mdrecords it:So an operator following the docs to delete a deployment and its data is told to run a command that was removed, while the replacement is documented on the same page and not connected to it. The second commit keeps the section and its anchor, so existing links still resolve, marks it removed, and points at the five-step sequence the section itself already listed as what
dropwrapped. Happy to split this into its own PR if you would rather keep the two changes separate.Points I would particularly like checked by someone who has run this:
--offsetguidance. I have described the default of 200 as being there so that only final blocks are copied, and warned against setting it below the chain's reorg threshold. That follows the wording of the existing doc comment, but if there is a better rule of thumb in practice it belongs here.create_inner. The third, that a source pruned past the copy point cannot be used, seems the most valuable to document and the most likely to catch people out, so it is worth confirming I have read it correctly.unused record/unused removefor reclaiming the source after activating a copy, including that a deployment is not eligible while it is the source of a running copy. That condition is already documented under Unused Record; the cross-reference seemed worth making explicit.For what it is worth,
copyanddropare not the only gaps.pub enum Commanddeclares 24 top-level commands and the docs cover five of them;dump,restore,prune,rewind,index,statsand a dozen others have no section at all. This PR is not attempting all of that, but I am happy to keep going if the format here is what you want.Docs only. No code changes.