# Back up and restore

[Wiki](../README.md) / [Nebula Cluster](README.md)

**On this page**

- [Taking a backup](#taking-a-backup)
- [Checking a backup](#checking-a-backup)
- [Restoring](#restoring)
- [Restoring to a moment](#restoring-to-a-moment)
- [After the loss of every server](#after-the-loss-of-every-server)

A backup is a database's whole state at one position, written to a directory while the
database goes on being used. A server that does not lead takes it, so the work stays off
the server that takes the writes.

## Taking a backup

```cypher
CALL gdb.backup.create('orders', {target: '/backups'});
CALL gdb.backup.create('orders', {target: '/backups', kind: 'incremental'});
CALL gdb.backup.createAll({target: '/backups'});
```

| `kind` | Holds | Restoring it |
|---|---|---|
| `full` (the default) | The database's pages as they are, indexes included | Puts the pages in place; nothing is rebuilt |
| `incremental` | What the pages have gained since an earlier backup, its base | The base first, then this. `restore` does both when given the incremental one |
| `logical` | Every node, relationship, row and definition | Rebuilds every store |

- The server you ask passes the request to a server that holds a copy and does not lead,
  and the result names the server that took it. The backup is written to a directory on
  that server: give a `target` every server can reach, or say which server with `on: 2`.
- A backup holds every write acknowledged before it was asked for, and none made after.
- An incremental backup continues the newest backup of the database's pages that the same
  server took under the same `target`; `base:` names another. The cluster finds the server
  that took the base. Keep a base as long as any backup that continues it.
- `createAll` backs up every database of the cluster and `system`, which holds the users,
  roles and the cluster's record of itself.

Each backup is a directory named for the database, the time and the position:
`/backups/orders-20261120T101500Z-48211`.

## Checking a backup

```cypher
CALL gdb.backup.verify('/backups/orders-20261120T101500Z-48211');
```

`verify` reads the whole backup: its length and checksum, then every page's own checksum,
or every record of a logical one. For an incremental backup it checks the backups it
continues as well.

## Restoring

```cypher
CALL gdb.backup.restore('/backups/orders-20261120T101500Z-48211',
     {database: 'orders_copy', replicas: 3});
```

- **A restore makes a new database** and leaves the ones you have alone. To replace a
  database, restore under another name, check it, and drop the old one.
- The database is built on the server that is asked, which must be able to read the
  directory. The cluster then makes its other copies.
- `replicas` says how many copies, three by default.

## Restoring to a moment

With a **log archive**, a backup can be restored to any position or time after it was
taken.

1. Set `GDB_CLUSTER_ARCHIVE` on every server to a directory outside the data directory, on
   storage that outlives the server. Each server writes what its databases commit to
   `<archive>/<database>/<node id>/` within a second.
2. Take `full` and `incremental` backups as usual.
3. Restore with `until`:

```cypher
CALL gdb.backup.restore('/backups/orders-20261120T101500Z-48211',
     {database: 'orders_0915', until: datetime('2026-11-20T09:15:00Z')});
CALL gdb.backup.restore('/backups/orders-20261120T101500Z-48211',
     {database: 'orders_at', until: 48390});
```

- `until` is a time, by the clock of the server that led when each write was committed, or
  a position. The database holds every write committed at or before it and none after.
  The `position` column of the result says where it stopped.
- The server that restores reads the backup and the archive of the server that took it.
  `archive:` names the archive when it is somewhere other than that server's own setting.
- Start the archive before the backup you mean to restore from. A restore that asks for a
  position the archive does not hold is refused and makes nothing.
- Files in the archive older than the oldest backup you keep can be deleted.

## After the loss of every server

1. Start a new cluster, with `GDB_CLUSTER_INIT=true` on one server.
2. Restore each database from its backup with `gdb.backup.restore`.
3. Create the users, roles and privileges on the new cluster.

## Related articles

[Backup, restore and transfer](../operations/backups.md) · [Servers](servers.md) · [Property shards](property-shards.md)
