Skip to content

docs: document the graphman copy commands - #6717

Open
cargopete wants to merge 2 commits into
graphprotocol:masterfrom
cargopete:pete/document-graphman-copy
Open

docs: document the graphman copy commands#6717
cargopete wants to merge 2 commits into
graphprotocol:masterfrom
cargopete:pete/document-graphman-copy

Conversation

@cargopete

@cargopete cargopete commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

docs/graphman.md documents Info, Remove, Unassign, Unused Record, Unused Remove, Drop, Check Blocks and Chain Call Cache Remove, but not copy. 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 copy is the supported way to do it, but at the moment the only way to find that out is --help or 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 in node/src/manager/commands/copy.rs, the copy machinery and its module documentation in store/postgres/src/copy.rs, and the OnSync variants in store/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.md carries a full ⌘ Drop section, synopsis and options and all, for a command that no longer exists. There is no Drop variant in pub enum Command, and the string Delete a deployment and all its indexed data appears in exactly one file in the repository: the doc itself. NEWS.md records it:

graphman drop removed — Use graphman remove followed by graphman unused record && graphman unused remove (#5974)

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 drop wrapped. 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:

  • The --offset guidance. 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.
  • The refusal list. Six conditions, taken from 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.
  • The cleanup note. I have pointed at unused record / unused remove for 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, copy and drop are not the only gaps. pub enum Command declares 24 top-level commands and the docs cover five of them; dump, restore, prune, rewind, index, stats and 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant