Skip to main content
Graphman is a powerful command-line tool included with Graph Node for managing subgraph deployments, performing maintenance operations, and troubleshooting issues.

​
Getting Started

Graphman is included in the official Graph Node containers. You can access it by running:
Graphman requires a configuration file to connect to your Graph Node infrastructure. If you don’t have one, follow the basic setup instructions to create a minimal configuration.

​
Environment Variables

Graphman respects the GRAPH_LOG environment variable for logging output. To disable logs:

​
Verifying Setup

Test that graphman is configured correctly:
If successful, this will display basic information about the deployment, including its database namespace.

​
Core Commands

​
Info

Prints detailed information about a deployment. Synopsis:
Arguments:
  • <DEPLOYMENT> - The deployment identifier (subgraph name, IPFS hash Qm.., or database namespace sgdNNN)
Options:
  • -c, --current - List only current version
  • -p, --pending - List only pending versions
  • -u, --used - List only used (current and pending) versions
  • -s, --status - Include status information
Output Fields: By default, the info command displays:
  • name - The subgraph name
  • status - Either pending or current
  • id - The Qm... IPFS identifier
  • namespace - Database schema containing deployment tables
  • shard - Database shard location
  • active - Whether this version is used for queries
  • chain - The blockchain network
  • graph node id - The assigned node instance
With --status enabled, additional fields include:
  • synced - Whether synced to current chain head
  • health - healthy, unhealthy, or failed
  • latest indexed block - Most recent processed block
  • current chain head block - Latest blockchain block
Examples:

​
Remove

Removes the association between a subgraph name and its deployment. Synopsis:
Arguments:
  • <NAME> - The name of the subgraph to remove
This command does not delete indexed data. It only removes the name mapping, stopping query traffic to that name and freeing it for reuse.
Example:

​
Unassign

Stops Graph Node from indexing a deployment permanently. Synopsis:
Arguments:
  • <DEPLOYMENT> - The deployment identifier
No indexed data is lost. The deployment remains in the database but stops receiving updates. See Maintenance Operations for more details on assignment management.
Examples:

​
Drop

Completely deletes a deployment and all its indexed data. Synopsis:
Arguments:
  • <DEPLOYMENT> - The deployment identifier
Options:
  • -c, --current - Search only for current versions
  • -p, --pending - Search only for pending versions
  • -u, --used - Search only for used versions
  • -f, --force - Skip confirmation prompt
This operation is irreversible. The drop command executes these steps in sequence:
1

Query deployment info

Runs graphman info <deployment> to identify the deployment
2

Unassign deployment

Runs graphman unassign <deployment> to stop indexing
3

Remove name mapping

Runs graphman remove <name> to free the subgraph name
4

Mark as unused

Runs graphman unused record to register for deletion
5

Delete data

Runs graphman unused remove <deployment> to purge all data
Examples:

​
Cleanup Commands

​
Unused Record

Scans all shards for unused deployments and registers them for removal. Synopsis:
Description: Identifies deployments that meet all these criteria:
  1. Not assigned to any node
  2. Either not marked as active, or neither current nor pending version of a subgraph
  3. Not the source of a currently running copy operation
Recorded deployments are stored in the unused_deployments table in the primary shard.
This command does not delete any data. It only marks deployments for future removal.
Example:

​
Unused Remove

Deletes deployments previously marked as unused. Synopsis:
Options:
  • -c, --count <COUNT> - How many unused deployments to remove (default: all)
  • -d, --deployment <DEPLOYMENT> - Remove a specific deployment
  • -o, --older <OLDER> - Remove only deployments recorded at least this many minutes ago
This operation is irreversible. All indexed data for removed deployments is permanently deleted.
Deployments are removed in descending order by entity count (smaller deployments first). Examples:

​
Chain Management

​
Check Blocks

Validates cached blocks against fresh data from the JSON RPC provider. Synopsis:
Arguments:
  • <chain-name> - Chain name (must be configured in your config file)
Subcommands:
  • by-hash <hash> - Check a single block by hash
  • by-number <number> - Check a single block by number
  • by-range [--from <n>] [--to <n>] - Check a range of blocks
Options for by-number and by-range:
  • --delete-duplicates - Automatically remove duplicate blocks at the same height
Description: JSON RPC providers sometimes send invalid block data to Graph Node. This command compares cached blocks with fresh data from the provider and removes any mismatches. When multiple blocks exist for the same block number, graphman will abort unless --delete-duplicates is specified, which removes all duplicates for that block number. Examples:

​
Call Cache Remove

Removes call cache entries for a specified chain. Synopsis:
Options:
  • --from <FROM> - Starting block number
  • --to <TO> - Ending block number
  • --remove-entire-cache - Remove the complete cache
  • --ttl-days <TTL_DAYS> - Remove contracts not accessed for this many days
  • --ttl-max-contracts <MAX> - Limit number of contracts removed with TTL
Removing the entire cache can significantly reduce indexing performance and should generally be avoided.
Block Range Options: When using --from and --to:
  • Omitting --from starts from the first cached block
  • Omitting --to extends to the last cached block
TTL-Based Removal: The --ttl-days option removes stale contracts based on the call_meta.accessed_at field. For example, --ttl-days 7 removes all calls to contracts not accessed in the last 7 days. Use --ttl-max-contracts to limit how many contracts are removed in a single operation. Examples:

​
Workflow Examples

​
Typical Cleanup Workflow

When you need to free up disk space by removing old deployments:
1

Identify unused deployments

This scans all shards and marks unused deployments.
2

Review what will be removed

Inspect the list of deployments marked for removal.
3

Remove unused deployments

Permanently delete the indexed data for unused deployments.

​
Migrating a Deployment

To stop serving a subgraph and free its name for a new version:
1

Remove the name mapping

This stops query traffic to the old version.
2

Record as unused

Mark the old deployment for cleanup.
3

Deploy new version

Deploy your new subgraph version. It can now use the freed name.
4

Clean up old data

Remove the old deployment data after confirming the new version works.

​
Best Practices

Before running destructive commands like drop or unused remove, use info and unused list to verify which deployments will be affected.
The --force flag skips confirmation prompts. Only use it in automated scripts after thorough testing.
Use --older with unused remove to ensure deployments have been unused for a safe period (e.g., 24 hours) before deletion.
Regularly run check-blocks on critical block ranges to ensure data integrity, especially after RPC provider changes.
Use TTL-based removal instead of clearing the entire cache to maintain indexing performance.

​
Troubleshooting

​
Graphman can’t connect to database

Ensure your config file has correct database connection strings and that the database is accessible from the container.

​
Deployment not found

Verify the deployment identifier using:
Try different identifier formats (name, IPFS hash, namespace).

​
Check-blocks finds mismatches

This indicates your RPC provider sent incorrect data. The command automatically removes bad cached blocks. Consider switching to a more reliable RPC provider.

​
Unused remove doesn’t delete a deployment

Ensure the deployment was marked as unused with graphman unused record first. Check that it’s not currently assigned to a node.