Backup and Restore

Description

Backup exports a graph’s schema, vertices, and edges as JSON data. Restore imports that data into a target graph. These HugeGraph-Tools commands support migration, recovery after an upgrade, and graph merging.

Backup

Backup runs in any graph mode. Pausing source writes before exporting is recommended to keep schema, vertices, and edges consistent (paginated read APIs do not provide a global transactional snapshot). Note: backup -t all only exports schema and graph data, excluding deployment configurations and user permissions.

Restore

Before restoring data, switch the target graph to the appropriate mode. Normal read/write operations use NONE mode; note that LOADING mode cannot be used for restore.

In MERGING, Tools recomputes PRIMARY_KEY vertex IDs using the target label IDs and updates connected edge endpoints and IDs. It retains AUTOMATIC and custom vertex IDs. The merge reuses schema with matching names. Check that their definitions are compatible and that retained vertex IDs do not conflict. It does not resolve arbitrary schema or data conflicts. Test on a separate target before merging production data.

Instructions

Prepare HugeGraph-Tools compatible with your Server version, then run the commands from the Tools root directory. This example restores a source graph on port 8080 to an empty target on port 8081. Both Servers and the target graph must already exist and be running. Adjust the addresses and graph names for your deployment.

1SOURCE_URL=http://127.0.0.1:8080
2TARGET_URL=http://127.0.0.1:8081
3SOURCE_GRAPH=hugegraph
4TARGET_GRAPH=hugegraph
5BACKUP_DIR="$PWD/data/hugegraph-backup"

With authentication enabled, add --user <user> --password <password> before the subcommand in each Tools command. The account needs the relevant graph access and graph-mode management permissions. See the Tools reference for connection and credential options.

Backup

Pause source writes, then export all schema, vertices, and edges.

1bin/hugegraph --url "$SOURCE_URL" --graph "$SOURCE_GRAPH" \
2  backup -t all -d "$BACKUP_DIR"

An explicit -d is the backup directory itself; the graph name is not appended. Use a separate directory for each backup to avoid mixing old files. Retain the complete directory, including compressed files. Restore reads the JSON backup formats supported by Tools.

Restore

This sequence uses RESTORING. To merge, use MERGING after the compatibility checks above. Pause application writes to the target during maintenance.

1. Record the original mode, then switch it.

   1bin/hugegraph --url "$TARGET_URL" --graph "$TARGET_GRAPH" graph-mode-get
   2ORIGINAL_MODE=NONE
   3bin/hugegraph --url "$TARGET_URL" --graph "$TARGET_GRAPH" \
   4  graph-mode-set -m RESTORING

   A graph in normal use should be in NONE mode. Set ORIGINAL_MODE to the value returned by the query, such as NONE below. If another task is using RESTORING, MERGING, or LOADING, coordinate with that task before changing its mode.

2. Restore the data.

   1bin/hugegraph --url "$TARGET_URL" --graph "$TARGET_GRAPH" \
   2  restore -t all -d "$BACKUP_DIR"

   Check command output and the restore results for each type. On failure, retain the backup directory and logs to inspect target state. Restore does not automatically roll back committed writes; do not re-run on a partially restored graph without inspection.

3. Restore the original mode.

   Reset the mode using ORIGINAL_MODE, recorded in the first step.

   1bin/hugegraph --url "$TARGET_URL" --graph "$TARGET_GRAPH" graph-mode-set -m "$ORIGINAL_MODE"
   2bin/hugegraph --url "$TARGET_URL" --graph "$TARGET_GRAPH" graph-mode-get

   Regardless of whether restore succeeds or fails, always restore the graph mode back to its original state (usually NONE). On failure, preserve the logs and state, and re-prepare the target graph before resuming business writes.

After resetting the mode, compare vertex and edge counts on both graphs.

1bin/hugegraph --url "$SOURCE_URL" --graph "$SOURCE_GRAPH" gremlin-execute --script 'g.V().count()'
2bin/hugegraph --url "$TARGET_URL" --graph "$TARGET_GRAPH" gremlin-execute --script 'g.V().count()'
3bin/hugegraph --url "$SOURCE_URL" --graph "$SOURCE_GRAPH" gremlin-execute --script 'g.E().count()'
4bin/hugegraph --url "$TARGET_URL" --graph "$TARGET_GRAPH" gremlin-execute --script 'g.E().count()'

Each pair of counts should match exactly. We also recommend using the Schema API to verify metadata definitions, and sampling vertex and edge properties and endpoints to ensure complete data integrity.

Help

For additional options on compression, concurrency, and selective type backup, see the Tools reference. Before performing cross-major-version restores, verify backup file compatibility in a test environment first.

API description for Backup/Restore usage and implementation

Backup

Backup exports data through the schema, vertex, and edge list GET APIs.

Restore

Restore imports data through the schema, vertex, and edge creation APIs. See the mode table for ID behavior. RESTORING accepts schema IDs; MERGING does not. Both accept retained AUTOMATIC vertex IDs. Normal NONE mode does not accept these ID settings required for restore.

View the mode of a graph

When authentication is enabled, graph read permission is required (space_member or the graph owner).

Method & Url

1GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/mode

Response Status

1200

Response Body

1{
2    "mode": "NONE"
3}

Valid graph modes are NONE, RESTORING, MERGING, and LOADING.

Set the mode of a graph

When authentication is enabled, graph-space management permission (space) is required; administrators can satisfy it through permission inheritance.

Method & Url

1PUT http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/mode

Request Body

1"RESTORING"

Valid graph modes are NONE, RESTORING, MERGING, and LOADING.

Response Status

1200

Response Body

1{
2    "mode": "RESTORING"
3}