Installation of gpbackup and gprestore

Pavel Semyonov

Contents

Prerequisites
Build from sources
Verify the installation

This topic describes how to install the Greengage DB backup and restore utilities gpbackup and gprestore on supported Linux systems.

To start using these utilities, you need to build them from source code and deploy the resulting binaries on the master host of the cluster. Their source code is available in the GreengageDB/gpbackup repository.

The backup and restore utilities are written in the Go programming language. To build them, Go 1.20 or later must be installed on the master host, and the GOPATH environment variable must be defined.

To check these requirements, run these commands on behalf of the gpadmin user:

$ go version
$ echo $GOPATH

Their output may look as follows:

go version go1.25.1 linux/amd64
/home/gpadmin/go

Instructions on Go installation are available at the official Go website.

To build Greengage DB’s backup and restore utilities:

Ensure you are logged in as gpadmin and in the home directory.

Clone the GreengageDB/gpbackup repository:

$ git clone https://github.com/GreengageDB/gpbackup.git

Change the current directory to gpbackup:
```
$ cd gpbackup
```
(Optional) Checkout a tag to build and install a specific version:
```
$ git checkout <tag_name>
```
where <tag_name> matches the version number.
Install build dependencies:
```
$ make depend
```
Compile the utilities:
```
$ make build
```
Install the utility binaries:
```
$ make install
```
This command requires a running Greengage DB cluster. It copies gpbackup and gprestore to $GPHOME/bin on the master host. When successful, the output includes a line similar to:
```
cp /home/gpadmin/goproject/bin/gpbackup /home/gpadmin/goproject/bin/gprestore /usr/local/gpdb/bin
```

As a result, gpbackup and gprestore are available on the master:

$ gpbackup --version
$ gprestore --version

Example output:

gpbackup version 1.30.6+dev.1.g108659cb
gprestore version 1.30.6+dev.1.g108659cb

After installation, verify that gpbackup and gprestore are working correctly. To do this, use an existing database or create a new one for testing.

To back up and restore a database in a Greengage DB cluster:

Connect to the database that you have selected for testing via psql, for example:
```
$ psql marketplace
```

Pick a table for testing. Inspect its row count, distribution across segments, and a few sample rows:

SELECT COUNT(*) FROM products;

SELECT gp_segment_id, COUNT(*)
FROM products
GROUP BY gp_segment_id;

SELECT * FROM products ORDER BY id LIMIT 5;

The output looks like the following:

 count
-------
 50000
(1 row)

 gp_segment_id | count
---------------+-------
             2 | 12421
             3 | 12493
             0 | 12605
             1 | 12481
(4 rows)

 id |   name    |           description            |        created_at         | price
----+-----------+----------------------------------+---------------------------+--------
  1 | Product 1 | 0fd39bdb8dcc6c9558ba9be459ea54bd | 2025-09-08 07:46:58.20256 | 842.05
  2 | Product 2 | a04e2d69b6b391793ef2541f19e77757 | 2025-09-08 07:46:58.20256 | 545.25
  3 | Product 3 | 066dfe5e4e697bf9b85091169330f21a | 2025-09-08 07:46:58.20256 |  37.86
  4 | Product 4 | 0b176f490b912adb2da893f8606fa0b9 | 2025-09-08 07:46:58.20256 | 956.44
  5 | Product 5 | cf03c00cfb6f9ce4557da232a27e85b4 | 2025-09-08 07:46:58.20256 | 354.37
(5 rows)

Quit psql:
```
\q
```
Create a backup of the database with gpbackup:
```
$ gpbackup --dbname marketplace
```
After successful execution, the output includes the line:
```
[INFO]:-Backup completed successfully
```
The backup timestamp is also displayed:
```
[INFO]:-Backup Timestamp = 20250908074826
```
The backup files appear in the backups/YYYYDDMM/<timestamp> subdirectory of each segment’s data directories. Each segment stores the backup of its data portion.

Drop the test table and verify it no longer exists:

$ psql marketplace -c 'DROP TABLE products;'
$ psql marketplace -c 'SELECT * FROM products;'

The second command produces an error:

ERROR:  relation "products" does not exist

Restore the database using the timestamp as the backup identifier:
```
$ gprestore --timestamp 20250908074826
```
After a successful execution, the output includes the line:
```
[INFO]:-Restore completed successfully
```
Recheck the table contents and distribution by repeating steps 1 and 2. The output is the same as before the backup, showing that the table was successfully restored.

For more information about using gpbackup and gprestore, run them with the --help options:

$ gpbackup --help
$ gprestore --help

Overview

Full data backup and restore

Installation of gpbackup and gprestore

Prerequisites

Build from sources

Verify the installation