Backup, restore and transfer

Wiki / Operations

On this page

Backup & durability maintenance

Native backup exports require a Commercial licence with the backup/restore entitlement. They remain available after that licence expires, so you can retrieve your data. Native restore also requires a valid licence that permits writes. Native backup and restore come with Commercial and Enterprise. Checkpoints and logical exports/imports are available in Community too; imports require write access. See licensing.

Run the following procedures over Bolt or through Explorer. Each is a whole-database operation, so it must be the entire statement (no trailing YIELD … RETURN, no surrounding pipeline). gdb.checkpoint runs the selected policy (hybrid seal/compact or resident snapshot/reset), while gdb.restore replaces the durable generation, which cannot be rolled back, so they must run as an auto-commit statement and not inside an explicit BEGIN/COMMIT transaction. With a native Galactus driver, call execute_query / executeQuery / ExecuteQuery on a connection with no open transaction. Do not call begin first. gdb.dump is read-only and needs no such handling. See driver setup. File paths resolve on the server's filesystem.

ProcedureYieldsDescription
gdb.checkpoint()walBytesReclaimedRun the selected engine's maintenance policy. Hybrid seals the active segment in O(1) and compacts at most one worthwhile stale-property segment; resident writes a full snapshot then crash-safely resets the log. The yielded count is commit-log bytes actually removed (rotation alone reports zero). No-op for an in-memory database.
gdb.dump([path])path or dataHot-dump the whole database — dictionaries, all nodes & relationships, and schema (indexes/constraints). With a server-side path, writes the self-contained file and returns that path. With no argument, returns the native snapshot as Bolt Bytes, which powers Explorer's browser download. Read-only; does not touch the commit log.
gdb.restore(path_or_bytes)path or bytesRestoredReplace the active database's entire contents in place from either a server-side dump path or native snapshot Bytes supplied as a Bolt parameter. For a durable database the restored state becomes the new baseline (snapshot rewritten, commit log crash-safely reset); destructive — the prior contents are discarded. Explorer uses the byte form for browser uploads.
gdb.cypher.import(path)statementsRun, failed, firstErrorReplay a .cypher script file at path straight from the server — the job cypher-shell -f does client-side. Splits the file into statements (honouring strings, backtick identifiers and // comments), runs each as its own autocommit unit, and applies it additively to the current database (it does not clear existing data). :begin/:commit/:rollback directives are accepted and ignored (every statement is its own unit); :param name => value binds a parameter for later statements. Fail-at-end: a failing statement is counted in failed (with the first message in firstError) and skipped rather than aborting the run.
gdb.dumpToBackup()path, bytesHot-dump the whole database to a fresh file under <storage dir>/backup/ (streamed one mutation at a time — the server never holds a second copy of the graph) and return its path and size. The memory-bounded way to move a large snapshot over Bolt; pair with gdb.dumpChunk and gdb.dumpDelete. Durable databases only.
gdb.dumpChunk(path, offset, length)data, offset, totalRead length bytes (capped at 32 MiB) of a hand-over dump starting at offset, with the file's total size. Empty data once offset reaches the end. Only .gdb files directly inside the backup directory are readable.
gdb.storage()engine, format, writtenBy, minimumReader, server, generation, pageBytes, livePageBytes, logBytes, cacheCapacityBytes, cacheBytes, pinnedBytes, cacheHitRatioThe storage this database is in: engine, format (1.x or orion), the release that last opened a Paged database and the oldest that may, its size on disk and how the page cache is serving it. From version 2.0.0
gdb.dumpDelete(path)pathRemove a hand-over dump once the client has it. Same path policy as gdb.dumpChunk.
CALL gdb.checkpoint();
CALL gdb.dump('/data/backup.gdb');
CALL gdb.dumpToBackup();

Use the actual path returned by dumpToBackup as a parameter for subsequent calls; do not invent a backup filename. Continue fetching until the returned data is empty, then delete the completed transfer file:

CALL gdb.dumpChunk($path, $offset, 8388608);
CALL gdb.dumpDelete($path);

Restore deliberately replaces the selected database. Run it alone:

CALL gdb.restore('/data/backup.gdb');

gdb.dump(path) streams to the file (a counting pass, then one mutation at a time), so a 200 MB graph dumps without a second copy of itself in RAM; gdb.dump() with no path still has to build the whole value to return it, which is why the backup exporter uses the hand-over trio instead.

A dump is a logical image (the mutation stream that rebuilds the database), not a raw page image, so it is a portable binary logical snapshot, not a text file or a byte-for-byte copy of the live directory. See Operations for the segmented commit/property-log model.

gdb.cypher.import imports a supported Cypher script, including statement-based APOC exports: copy the .cypher onto the server and CALL gdb.cypher.import('…'). It is additive — import into a fresh database, or MATCH (n) DETACH DELETE n first if you mean to replace. Because it drives its own sequence of autocommit statements it must run auto-commit (execute the query without calling begin in a native driver), and it is a single whole statement (no trailing YIELD … RETURN). The relationship form APOC emits — MATCH (s:Label {id: row.id}) over an UNWIND … AS row batch — uses the unique-constraint index per row, so a large import stays fast.

Dumps while the database is busy

From version 1.6.4, gdb.dump(), gdb.dump(path) and gdb.dumpToBackup() run alongside reads and writes. Before, a dump took the database for itself and every reader and writer waited until it finished.

  • What the file holds: the database exactly as it was when the dump started. It leaves out other connections' uncommitted changes and anything committed after it began.
  • How it shares: the dump reads 1,024 nodes or relationships at a time and lets writes in between batches.
  • Memory and writers: while a dump runs, each change to data it has not read yet keeps the old value in memory, counted against GDB_SNAPSHOT_MAX_BYTES (64 MiB per database by default). From half that limit, writers pause briefly after each commit, for longer as it fills; at the limit, writes wait until the dump ends. A single pause is at most 5 seconds.
  • One at a time: a second dump of the same database waits for the first, then starts from a fresh snapshot.
  • Cost: dumps are slower than before, and the database is somewhat slower while one runs.
  • Stopping one: dbms.killQuery stops a dump between batches. The query time limit does not apply to dumps. A restore during a dump fails the dump; run it again.
  • Still exclusive: a dump inside an explicit transaction, a dump with YIELD or WHERE, and any dump with GDB_SNAPSHOT_READS=false still take the database for themselves. A dump inside a write transaction includes that transaction's own changes.

gdb.dumpChunk and gdb.dumpDelete only touch the dump file, so they never hold up the database.

Restore with Explorer

  1. Connect to the target instance and select the database you intend to replace.
  2. Choose the native database import/upload action and select your .gdb snapshot.
  3. Confirm the replacement, then verify node counts, relationships and schema.

Restore replaces the selected database's contents. The snapshot includes topology, property values and schema declarations; indexes are rebuilt on restore. Native Galactus DB restore does not accept another database engine's binary store format.

Explorer accepts uploads up to 512 MiB, while the server's default incoming-message limit is 64 MiB. Both limits apply. For a larger backup, place the file in a volume readable by the server and call gdb.restore('/data/backup.gdb') as a standalone auto-commit statement.

Server configuration · Commit durability and recovery

Security state and permissions

RBAC applies in addition to licensing. Native exports need database access, graph read privileges, EXECUTE ADMIN PROCEDURES ON DBMS and LOAD ON ALL DATA. Restore/script replay also needs target graph write and index/constraint management rights. The built-in administrator has these privileges. Grant host file and backup access only to trusted operators; see permissions.

A user-database dump does not include users, roles or grants. Restoring data in place retains the target's policy. The protected system database cannot be exported or restored with graph procedures. For full recovery, stop the server and preserve the complete instance data directory, including system, with filesystem permissions appropriate for credential hashes. This release has no online security-catalog export or offline password-reset CLI. Keep a second administrator and a recoverable instance backup.

Planning a deployment? Review compatibility and licence setup for your instance.