Backup, restore and transfer
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. Personal and Developer do not include native backup or restore. Checkpoints and logical exports/imports are available in the free editions; 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.
| Procedure | Yields | Description |
|---|---|---|
gdb.checkpoint() | walBytesReclaimed | Run 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 data | Hot-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 bytesRestored | Replace 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, firstError | Replay 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, bytes | Hot-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, total | Read 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.dumpDelete(path) | path | Remove 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.
Restore with Explorer
- Connect to the target instance and select the database you intend to replace.
- Choose the native database import/upload action and select your
.gdbsnapshot. - 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.
Related articles
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.