Back up and restore

Wiki / Nebula Cluster

On this page

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

CALL gdb.backup.create('orders', {target: '/backups'});
CALL gdb.backup.create('orders', {target: '/backups', kind: 'incremental'});
CALL gdb.backup.createAll({target: '/backups'});
kindHoldsRestoring it
full (the default)The database's pages as they are, indexes includedPuts the pages in place; nothing is rebuilt
incrementalWhat the pages have gained since an earlier backup, its baseThe base first, then this. restore does both when given the incremental one
logicalEvery node, relationship, row and definitionRebuilds 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

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

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:
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.

Backup, restore and transfer · Servers · Property shards

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