Overview of the gpbackup syntax
The gpbackup utility creates a logical backup of the specified database in a Greengage DB cluster.
Synopsis
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
Options
- --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
1to9applied to the data files of the backup. By default, level1compression 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-compressionoption.Learn more in Configure backup compression.
- --compression-type <type>
-
Compression algorithm for data files:
gzip(default) orzstd.zstdcompression requires Zstandard to be installed in the system. You can check this with the following command:$ zstd --versionLearn more in Configure backup compression.
- --copy-queue-size <int>
-
When
gpbackupis invoked with the--single-data-fileoption,--copy-queue-sizecan 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 reducingCOPYinitialization 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
debugandverboseseverity messages to thegpbackupoutput. - --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-tableand others).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-tableand 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-schemaand--exclude-schema-file) and with other table filtering options (--include-tableand others).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-schemaand--exclude-schema-fileand with other table filtering options (--include-tableand 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-tableand--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-tableand--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-schemaand others) or tables (--exclude-tableand others).Note that
gpbackupdoes not automatically include objects on which the specified object depends. For example:-
If a table specified in
--include-tableuses a sequence, include this sequence explicitly. -
To back up a materialized view, include the tables that it uses.
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-schemaand others) or tables (--exclude-tableand others).Note that
gpbackupdoes 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,gpbackuplocates 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-timestampoption.This option requires
--leaf-partition-datato be specified and cannot be combined with--data-onlyor--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,
gpbackupuses 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-onlyor--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-tableor--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.dbin the master data directory). - --plugin-config <config_file_location>
-
The location of a
gpbackupplugin configuration file to use for the backup.gpbackupplugins 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),gpbackupcreates 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-dirmust 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
verboseseverity messages to thegpbackupoutput. - --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
gpbackupversion. - --help
-
Displays the help information about
gpbackup.
Return codes
gpbackup has the following return codes:
-
0— backup completed successfully. -
1— backup completed with non-fatal errors. -
2— backup failed.