# Backup, restore and transfer

[Wiki](../README.md) / [Operations](README.md)

**On this page**

- [Backup & durability maintenance](#backup--durability-maintenance)
- [Dumps while the database is busy](#dumps-while-the-database-is-busy)
- [Restore with Explorer](#restore-with-explorer)

## 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](licensing.md).

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](../integrations/bolt.md).
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.storage()` | `engine, format, writtenBy, minimumReader, server, generation, pageBytes, livePageBytes, logBytes, cacheCapacityBytes, cacheBytes, pinnedBytes, cacheHitRatio` | The 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)` | `path` | Remove a hand-over dump once the client has it. Same path policy as `gdb.dumpChunk`. |

```cypher
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:

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

Restore deliberately replaces the selected database. Run it alone:

```cypher
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](README.md)
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.

## Related articles

[Server configuration](configuration.md) · [Commit durability and recovery](durability.md)

## 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](authentication.md).

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.
