Overview of the gpbackup syntax

Pavel Semyonov

Contents

Options
Return codes

The gpbackup utility has the following syntax:

gpbackup --dbname <database_name>
[--backup-dir <directory>]
[--compression-level <level>]
[--compression-type <type>]
[--copy-queue-size <int>]
[--data-only]
[--debug]
[--exclude-schema <schema> [--exclude-schema <schema> ...]]
[--exclude-table <schema.table> [--exclude-table <schema.table> ...]]
[--exclude-schema-file <file_name>]
[--exclude-table-file <file_name>]
[--include-schema <schema> [--include-schema <schema> ...]]
[--include-table <schema.table> [--include-table <schema.table> ...]]
[--include-schema-file <file_name>]
[--include-table-file <file_name>]
[--incremental [--from-timestamp <backup-timestamp>]]
[--jobs <int>]
[--leaf-partition-data]
[--metadata-only]
[--no-compression]
[--no-inherits]
[--no-history]
[--plugin-config <config_file_location>]
[--quiet]
[--single-data-file]
[--single-backup-dir]
[--verbose]
[--with-stats]
[--without-globals]

gpbackup --help

gpbackup --version

Option Description

Option	Description
--dbname <dbname>	The name of the database to back up. This option is mandatory
--backup-dir <directory>	The directory for creating backup files. The value must be an absolute path. By default, backups are created in the backups directory located: inside $MASTER_DATA_DIRECTORY for the master; under segment data directories for segments. Each backup is placed in a separate subdirectory named by date and timestamp in the following format: YYYYMMDD/YYYYMMDDHHMMSS/. Learn more in Define backup location
--compression-level <level>	Compression level from `1` to `9` applied to the data files of the backup. By default, level `1` compression is used. Higher levels improve compression ratio but increase resource usage and operation time. To create a backup with uncompressed data in the CSV format, use the `--no-compression` option. Learn more in Configure backup compression
--compression-type <type>	Compression algorithm for data files: `gzip` (default) or `zstd`. `zstd` compression requires Zstandard to be installed in the system. You can check this with the following command: `$ zstd --version` Learn more in Configure backup compression
--copy-queue-size <int>	When `gpbackup` is invoked with the `--single-data-file` option, `--copy-queue-size` can be used to set the number of pre-initialized COPY commands to use for copying data to the backup. This can speed up backups with many small tables by reducing `COPY` initialization overhead. Incompatible with `--jobs`
--data-only	Backs up only table data, without metadata such as SQL commands that create tables and other database objects
--debug	Adds `debug` and `verbose` severity messages to the `gpbackup` output
--exclude-schema <schema>	Excludes the specified schema from the backup. Can be specified multiple times. If a schema name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes. Incompatible with all other options that filter schemas (`--exclude-schema-file`, `--include-schema`, `--include-schema-file`) or tables (`--include-table` and others). Partitions in excluded schemas If leaf partitions of a partitioned table are stored in a different schema than the root table, schema exclusion behavior depends on the `--leaf-partition-data` option: With `--leaf-partition-data`, leaf partition data is included even if their schema is excluded. Without `--leaf-partition-data`, leaf partition data in excluded schemas is not backed up. Regardless of `--leaf-partition-data`, metadata of all leaf partitions is included in the backup. Learn more in Partial backups
--exclude-schema-file <file_name>	Excludes the schemas listed in a file from the backup. The file must list one schema per line and have no trailing blank lines. If a schema name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes. Incompatible with all other options that filter schemas (`--exclude-schema`, `--include-schema`, `--include-schema-file`) or tables (`--include-table` and others). Learn more in Partial backups
--exclude-table <schema.table>	Excludes the specified table or other object — sequence, view, or materialized view — from the backup. Can be specified multiple times. The object name must be in the `<schema>.<table>` format. If a schema or object name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes. Incompatible with options that exclude schemas (`--exclude-schema` and `--exclude-schema-file`) and with other table filtering options (`--include-table` and others). Table exclusion and leaf partitions For partitioned tables, only root and leaf partitions can be excluded, not intermediate partitions. To exclude a leaf partition, you must also specify `--leaf-partition-data`. Learn more in Partial backups
--exclude-table-file <file_name>	Excludes the tables and other objects — sequences, views, or materialized views — listed in a file from the backup. The file must list one object per line and have no trailing blank lines. Each object name must be in the `<schema>.<table>` format. If a schema or object name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes. Incompatible with schema filtering options `--exclude-schema` and `--exclude-schema-file` and with other table filtering options (`--include-table` and others). Learn more in Partial backups
--include-schema <schema>	Backs up only the specified schema. Can be specified multiple times. If a schema name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes. Incompatible with other options that filter schemas (`--exclude-schema`, `--exclude-schema-file`, `--include-schema-file`) or include tables (`--include-table` and `--include-table-file`). Learn more in Partial backups
--include-schema-file <file_name>	Backs up only schemas listed in a file. The file must list one schema per line and have no trailing blank lines. If a schema name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes. Incompatible with other options that filter schemas (`--exclude-schema`, `--exclude-schema-file`, `--include-schema-file`) or include tables (`--include-table` and `--include-table-file`). Learn more in Partial backups
--include-table <schema.table>	Backs up only the specified table or other object — sequence, view, or materialized view. Can be specified multiple times. The object name must be in the `<schema>.<table>` format. If a schema or object name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes. Incompatible with other options that filter schemas (`--exclude-schema` and others) or tables (`--exclude-table` and others). Note that `gpbackup` does not automatically include objects on which the specified object depends. For example: If a table specified in `--include-table` uses a sequence, include this sequence explicitly. To back up a materialized view, include the tables that it uses. Partitioned table inclusion For partitioned tables, only root and leaf partitions can be included, not intermediate partitions. To include a leaf partition, you must also specify `--leaf-partition-data`. This includes the partition data and the root table’s metadata. Learn more in Partial backups
--include-table-file <file_name>	Backs up only tables or other objects — sequences, views, or materialized views — listed in a file. The object name must be in the `<schema>.<table>` format. The file must list one object per line and have no trailing blank lines. If a schema or object name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes. Incompatible with other options that filter schemas (`--exclude-schema` and others) or tables (`--exclude-table` and others). Note that `gpbackup` does not automatically include objects on which the specified object depends. For example: If a table specified in the file uses a sequence, include this sequence explicitly. To back up a materialized view, include the tables that it uses. Learn more in Partial backups
--incremental	Creates an incremental backup to append to an incremental backup set. Such a set includes one full backup and one or more incremental backups. When invoked with `--incremental`, `gpbackup` locates the most recent compatible backup and bases a new incremental backup on it. Alternatively, you can specify a timestamp to base the backup on using the `--from-timestamp` option. This option requires `--leaf-partition-data` to be specified and cannot be combined with `--data-only` or `--metadata-only`. Learn more in Incremental backups
--from-timestamp <backup-timestamp>	Specifies the timestamp of an existing backup to use as the base for an incremental backup. That backup must be compatible with the incremental backup being created. Can be used only with `--incremental`. Learn more in Incremental backups
--jobs <int>	The number of jobs to use for parallel backup. By default, `gpbackup` uses one job with a database connection and backs up objects one by one. When the number of jobs is increased, each of them backs up tables in a separate transaction, speeding up the operation. This leads to an increased number of table locks acquired by the backup operation. If the utility cannot acquire a lock on a table being backed up, it will exit. Thus, it is recommended to create backups with multiple jobs during low-activity periods. Incompatible with `--metadata-only` or `--single-data-file`. Learn more in Parallel backup and restore
--leaf-partition-data	Creates a separate data file per leaf partition of a partitioned table. Without `--leaf-partition-data` (the default), the entire table is saved to one data file per segment. Required for partition-level inclusion or exclusion with schema and table filtering options such as `--include-table` Learn more in Partitioned tables
--metadata-only	Backs up only object metadata, such as SQL commands that create database objects, without actual table data
--no-compression	Does not compress data files of the backup. Learn more in Configure backup compression
--no-inherits	When using table inclusion options `--include-table` or `--include-table-file`, inheritance-related tables are also included into the backup. With `--no-inherits`, all inheritance relationships from these tables to other tables are ignored and only the specified tables are backed up
--no-history	Skips recording information about the backup operation in the backup history service database (`gpbackup_history.db` in the master data directory)
--plugin-config <config_file_location>	The location of a `gpbackup` plugin configuration file to use for the backup. `gpbackup` plugins extend its functionality and enable custom backup scenarios, such as saving backups to remote locations. A plugin configuration file is a YAML file that contains the plugin information and settings to use for the backup operation. Backups created with a plugin require the same plugin for restore. Incompatible with `--backup-dir`
--quiet	Suppresses all output except warning or error messages
--single-data-file	Creates a single data file per segment for all tables on that segment. Without `--single-data-file` (the default), `gpbackup` creates one CSV file per table included in the backup. Note that backups created with this option cannot be restored in parallel with `gprestore --jobs`. Learn more in Define backup layout
--single-backup-dir	Saves all files per host in a single directory instead of creating a separate directory for each segment. With this option, `--backup-dir` must be specified. The files are saved in the following location on each host: <backup-dir>/backups/YYYYMMDD/YYYYMMDDHHMMSS. Learn more in Define backup layout
--verbose	Adds `verbose` severity messages to the `gpbackup` output
--with-stats	Includes database statistics in the backup
--without-globals	Excludes the global Greengage DB system objects — roles, tablespaces, resource queues and groups, and so on — from the backup
--version	Prints the `gpbackup` version
--help	Displays the help information about `gpbackup`

--dbname <dbname>

The name of the database to back up. This option is mandatory

--backup-dir <directory>

The directory for creating backup files. The value must be an absolute path.

By default, backups are created in the backups directory located:

inside $MASTER_DATA_DIRECTORY for the master;
under segment data directories for segments.

Each backup is placed in a separate subdirectory named by date and timestamp in the following format: YYYYMMDD/YYYYMMDDHHMMSS/.

Learn more in Define backup location

--compression-level <level>

Compression level from 1 to 9 applied to the data files of the backup. By default, level 1 compression is used. Higher levels improve compression ratio but increase resource usage and operation time.

To create a backup with uncompressed data in the CSV format, use the --no-compression option.

Learn more in Configure backup compression

--compression-type <type>

Compression algorithm for data files: gzip (default) or zstd.

zstd compression requires Zstandard to be installed in the system. You can check this with the following command:

$ zstd --version

Learn more in Configure backup compression

--copy-queue-size <int>

When gpbackup is invoked with the --single-data-file option, --copy-queue-size can be used to set the number of pre-initialized COPY commands to use for copying data to the backup. This can speed up backups with many small tables by reducing COPY initialization overhead.

Incompatible with --jobs

--data-only

Backs up only table data, without metadata such as SQL commands that create tables and other database objects

--debug

Adds debug and verbose severity messages to the gpbackup output

--exclude-schema <schema>

Excludes the specified schema from the backup. Can be specified multiple times. If a schema name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes.

Incompatible with all other options that filter schemas (--exclude-schema-file, --include-schema, --include-schema-file) or tables (--include-table and others).

Partitions in excluded schemas

If leaf partitions of a partitioned table are stored in a different schema than the root table, schema exclusion behavior depends on the --leaf-partition-data option:

With --leaf-partition-data, leaf partition data is included even if their schema is excluded.
Without --leaf-partition-data, leaf partition data in excluded schemas is not backed up.

Regardless of --leaf-partition-data, metadata of all leaf partitions is included in the backup.

Learn more in Partial backups

--exclude-schema-file <file_name>

Excludes the schemas listed in a file from the backup. The file must list one schema per line and have no trailing blank lines. If a schema name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes.

Incompatible with all other options that filter schemas (--exclude-schema, --include-schema, --include-schema-file) or tables (--include-table and others).

Learn more in Partial backups

--exclude-table <schema.table>

Excludes the specified table or other object — sequence, view, or materialized view — from the backup. Can be specified multiple times. The object name must be in the <schema>.<table> format. If a schema or object name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes.

Incompatible with options that exclude schemas (--exclude-schema and --exclude-schema-file) and with other table filtering options (--include-table and others).

Table exclusion and leaf partitions

For partitioned tables, only root and leaf partitions can be excluded, not intermediate partitions. To exclude a leaf partition, you must also specify --leaf-partition-data.

Learn more in Partial backups

--exclude-table-file <file_name>

Excludes the tables and other objects — sequences, views, or materialized views — listed in a file from the backup. The file must list one object per line and have no trailing blank lines. Each object name must be in the <schema>.<table> format. If a schema or object name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes.

Incompatible with schema filtering options --exclude-schema and --exclude-schema-file and with other table filtering options (--include-table and others).

Learn more in Partial backups

--include-schema <schema>

Backs up only the specified schema. Can be specified multiple times. If a schema name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes.

Incompatible with other options that filter schemas (--exclude-schema, --exclude-schema-file, --include-schema-file) or include tables (--include-table and --include-table-file).

Learn more in Partial backups

--include-schema-file <file_name>

Backs up only schemas listed in a file. The file must list one schema per line and have no trailing blank lines. If a schema name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes.

Incompatible with other options that filter schemas (--exclude-schema, --exclude-schema-file, --include-schema-file) or include tables (--include-table and --include-table-file).

Learn more in Partial backups

--include-table <schema.table>

Backs up only the specified table or other object — sequence, view, or materialized view. Can be specified multiple times. The object name must be in the <schema>.<table> format. If a schema or object name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes.

Incompatible with other options that filter schemas (--exclude-schema and others) or tables (--exclude-table and others).

Note that gpbackup does not automatically include objects on which the specified object depends. For example:

If a table specified in --include-table uses a sequence, include this sequence explicitly.
To back up a materialized view, include the tables that it uses.

Partitioned table inclusion

For partitioned tables, only root and leaf partitions can be included, not intermediate partitions. To include a leaf partition, you must also specify --leaf-partition-data. This includes the partition data and the root table’s metadata.

Learn more in Partial backups

--include-table-file <file_name>

Backs up only tables or other objects — sequences, views, or materialized views — listed in a file. The object name must be in the <schema>.<table> format. The file must list one object per line and have no trailing blank lines. If a schema or object name includes characters other than lowercase letters, digits, or underscores, enclose this name in double quotes.

Incompatible with other options that filter schemas (--exclude-schema and others) or tables (--exclude-table and others).

Note that gpbackup does not automatically include objects on which the specified object depends. For example:

If a table specified in the file uses a sequence, include this sequence explicitly.
To back up a materialized view, include the tables that it uses.

Learn more in Partial backups

--incremental

Creates an incremental backup to append to an incremental backup set. Such a set includes one full backup and one or more incremental backups.

When invoked with --incremental, gpbackup locates the most recent compatible backup and bases a new incremental backup on it. Alternatively, you can specify a timestamp to base the backup on using the --from-timestamp option.

This option requires --leaf-partition-data to be specified and cannot be combined with --data-only or --metadata-only.

Learn more in Incremental backups

--from-timestamp <backup-timestamp>

Specifies the timestamp of an existing backup to use as the base for an incremental backup. That backup must be compatible with the incremental backup being created.

Can be used only with --incremental.

Learn more in Incremental backups

--jobs <int>

The number of jobs to use for parallel backup. By default, gpbackup uses one job with a database connection and backs up objects one by one. When the number of jobs is increased, each of them backs up tables in a separate transaction, speeding up the operation. This leads to an increased number of table locks acquired by the backup operation. If the utility cannot acquire a lock on a table being backed up, it will exit. Thus, it is recommended to create backups with multiple jobs during low-activity periods.

Incompatible with --metadata-only or --single-data-file.

Learn more in Parallel backup and restore

--leaf-partition-data

Creates a separate data file per leaf partition of a partitioned table. Without --leaf-partition-data (the default), the entire table is saved to one data file per segment.

Required for partition-level inclusion or exclusion with schema and table filtering options such as --include-table

Learn more in Partitioned tables

--metadata-only

Backs up only object metadata, such as SQL commands that create database objects, without actual table data

--no-compression

Does not compress data files of the backup.

Learn more in Configure backup compression

--no-inherits

When using table inclusion options --include-table or --include-table-file, inheritance-related tables are also included into the backup. With --no-inherits, all inheritance relationships from these tables to other tables are ignored and only the specified tables are backed up

--no-history

Skips recording information about the backup operation in the backup history service database (gpbackup_history.db in the master data directory)

--plugin-config <config_file_location>

The location of a gpbackup plugin configuration file to use for the backup.

gpbackup plugins extend its functionality and enable custom backup scenarios, such as saving backups to remote locations. A plugin configuration file is a YAML file that contains the plugin information and settings to use for the backup operation.

Backups created with a plugin require the same plugin for restore.

Incompatible with --backup-dir

--quiet

Suppresses all output except warning or error messages

--single-data-file

Creates a single data file per segment for all tables on that segment. Without --single-data-file (the default), gpbackup creates one CSV file per table included in the backup.

Note that backups created with this option cannot be restored in parallel with gprestore --jobs.

Learn more in Define backup layout

--single-backup-dir

Saves all files per host in a single directory instead of creating a separate directory for each segment. With this option, --backup-dir must be specified. The files are saved in the following location on each host: <backup-dir>/backups/YYYYMMDD/YYYYMMDDHHMMSS.

Learn more in Define backup layout

--verbose

Adds verbose severity messages to the gpbackup output

--with-stats

Includes database statistics in the backup

--without-globals

Excludes the global Greengage DB system objects — roles, tablespaces, resource queues and groups, and so on — from the backup

--version

Prints the gpbackup version

--help

Displays the help information about gpbackup

gpbackup has the following return codes:

0 — backup completed successfully.
1 — backup completed with non-fatal errors.
2 — backup failed.

S3 storage plugin

gprestore

Overview of the gpbackup syntax

Options

Return codes