Backup and Restore

Backing up the database is essential to protect data integrity, prevent data loss, and ensure disaster recovery in case of hardware failure, accidental deletion, or corruption. It also enables database migration, replication, and rollback to a previous state if needed.

You can create a backup from a running database using either UQL or the ultipa_backup_client tool. The backup includes user-created graphs on Shard servers and system global graphs on both Shard and Meta servers. To restore a backup, you can only use the ultipa_backup_client.

Using UQL

Create a Backup

Create a backup named backup-20250101:

UQL
db.backup.create("backup_20250101")

The backup creation is executed as a global job, you may run show().job().global() afterward to verify the success of the creation.

If the specified backup name already exists, differential backup is performed; otherwise, a full backup is created.

View Backups

Retrieves all backups created for the database:

UQL
db.backup.show()

Or retrieves a specific backup, such as the one named backup_20250101:

UQL
db.backup.show("backup_20250101")

It returns a table _backupList with the following fields:

Using the Client

Ultipa Backup Client (ultipa_backup_client) is a cross-platform (Windows/Mac/Linux) command line interface designed for managing and restoring backups for Ultipa graph databases.

Prerequisites

• A command line terminal.
  • Linux or MacOS: Bash, Zsh, TCSH
  • Windows: PowerShell
• Download Ultipa Backup Client from here. No installation is required.

NOTE

The following examples are demonstrated using a Bash shell on Linux.

Navigate to the directory containing the ultipa_backup_client. Ensure it has the appropriate execute permissions by running:

Bash
chmod +x ultipa_backup_client

Generate Configuration File

Run the command to generate a sample configuration file:

bash
./ultipa_backup_client -sample

A file named example.backup.config will be generated in the same directory as ultipa_backup_client. If the file already exists, it will be overwritten.

Create a Backup

To create a backup, modify the [server] section in the example.backup.config file based on your environment.

Example:

example.backup.config
[server]
; database host (name server address)
host     = 192.168.189.129:61060
; database username
username = root
; database password
password = <password>
; backup name (supports only letters, numbers, and underscores)
name     = backup_1

Other settings in example.backup.config are not used when creating a backup.

Run the command to create a backup:

Bash
./ultipa_backup_client -mode backup -config example.backup.config

If the specified backup name already exists, differential backup is performed; otherwise, a full backup is created.

View Backups

Run the command to view the information of all backups:

Bash
./ultipa_backup_client -mode backup_info -config example.backup.config

The backup_info column is omitted here. To view detailed backup information, run the UQL statement db.backup.show() in the database.

Restore a Backup

A backup artifact can be restored within the same database.

To restore a backup, you need to further modify the example.backup.config file based on your environment.

Notes:

• The name in [server] section must match the uuid in [restore] section to correctly identify the backup.
• The shard-data in [restore] section must match the dbpath of your Shard servers (default: shard_data).
• The meta-data in [restore] section must match the dbpath of your Meta servers (default: data).
• For Shard, Meta, Name, or HDC clusters, the order of server addresses and daemon addresses must correspond exactly. All replicas in a shard must be included.
• Daemon Address Configuration:
  • Each server's daemon address is configured in backup.config file located in the container's config directory. This file is automatically generated during first startup with the default setting listen = :50051, and it uses the machine's primary IP address.
  • Modify backup.config to resolve port conflicts (format: ip:port or :port) if needed.
• Omit the [hdc] section entirely if no HDC servers are deployed.

Example:

example.backup.config
[server]
; database host (name server address)
host     = 192.168.189.129:61060
; database username
username = root
; database password
password = <password>
; backup name (supports only letters, numbers, and underscores)
name     = backup_1

[restore]
; backup uuid for restore (must match the specified backup name)
uuid       = T20250514031515_N1_158_6
; shard server dbpath
shard-data = shard_data
; meta server dbpath
meta-data  = data

; shard config for restore
[shard]
; all replica addresses for shard-1
shard1-address  = 192.168.189.131:41061,192.168.189.132:41063
; all daemon addresses for shard-1
daemon1-address = 192.168.189.131:50051,192.168.189.132:50051
; all replica addresses for shard-2
shard2-address  = 192.168.189.133:41065
; all daemon addresses for shard-2
daemon2-address = 192.168.189.133:50051

; meta config for restore
[meta]
; all meta addresses
meta-address   = 192.168.189.130:51060
; all daemon addresses for meta server
daemon-address = 192.168.189.130:50051

; name config for restore
[name]
; all name server addresses
name-address   = 192.168.189.129:61060
; all daemon addresses for name server
daemon-address = 192.168.189.129:50051

; hdc config for restore, if exists
[hdc]
; all hdc addresses
hdc-address    = 192.168.189.128:56555
; all daemon addresses for hdc sever
daemon-address = 192.168.189.128:50051

Run the command to restore the database to the specified backup:

Bash
./ultipa_backup_client -mode restore -config example.backup.config

NOTE

Note: All servers will be stopped and restarted as part of the restoration process.

All Flags

ultipa_backup_client supports the following flags: