Back up and restore
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'});
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
targetevery server can reach, or say which server withon: 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. createAllbacks up every database of the cluster andsystem, 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.
replicassays 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.
- Set
GDB_CLUSTER_ARCHIVEon 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. - Take
fullandincrementalbackups as usual. - 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});
untilis 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. Thepositioncolumn 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
- Start a new cluster, with
GDB_CLUSTER_INIT=trueon one server. - Restore each database from its backup with
gdb.backup.restore. - Create the users, roles and privileges on the new cluster.