Overview of the gprestore syntax
The gprestore utility restores a database to a Greengage DB cluster from a logical backup.
Synopsis
gprestore --timestamp <YYYYMMDDHHMMSS>
[--backup-dir <directory>]
[--copy-queue-size <int>]
[--create-db]
[--debug]
[--exclude-schema <schema> [--exclude-schema <schema> ...]]
[--exclude-table <schema.table> [--exclude-table <schema.table> ...]]
[--exclude-table-file <file_name>]
[--exclude-schema-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>]
[--truncate-table]
[--redirect-schema <schema>]
[--resize-cluster]
[--data-only | --metadata-only]
[--incremental]
[--jobs <int>]
[--on-error-continue]
[--plugin-config <config_file_location>]
[--quiet]
[--redirect-db <database_name>]
[--verbose]
[--version]
[--with-globals]
[--with-stats]
[--run-analyze]
gprestore --help
gprestore --version
Options
- --timestamp <YYYYMMDDHHMMSS>
-
The timestamp of the backup to restore. This option is mandatory.
- --backup-dir <directory>
-
Absolute path to the directory that contains the backup files. The directory must exist on all cluster hosts and include subdirectories gpseg<N>/backups for all segments running on the host. Inside these directories, there must be YYYYMMDD/YYYYMMDDHHMMSS subdirectories that match the specified timestamp (
--timestamp).NOTEIf the specified directory contains only one timestamp subdirectory,
--timestampcan be omitted.By default, Greengage DB searches for backup files in the following locations:
-
On master: metadata files in $MASTER_DATA_DIRECTORY/backups/YYYYMMDD/YYYYMMDDHHMMSS.
-
On segments: data files in backups/YYYYMMDD/YYYYMMDDHHMMSS inside the segment data directories.
Incompatible with
--plugin-config.Learn more in Define backup location.
-
- --create-db
-
If the database specified in the backup does not exist in the target cluster,
--create-dbcreates it before restore. The new database is created from the template databasetemplate0. - --copy-queue-size <int>
-
Sets the number of pre-initialized COPY commands to use for the restore operation. This can speed up restores with many small tables by reducing
COPYinitialization overhead. By default,COPYcommands are initialized one at a time. - --data-only
-
Restores only table data without creating tables or other objects from metadata. The tables must already exist in the target database. Sequences used by the tables are also updated.
- --debug
-
Adds
debugandverboseseverity messages to thegprestoreoutput. - --exclude-schema <schema>
-
Excludes the specified schema from the restore operation. 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 restore operation. 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 restore operation. 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).For partitioned tables, only the root table can be excluded.
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 restore operation. 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).For partitioned tables, only the root table can be excluded.
Learn more in Partial backups.
- --include-schema <schema>
-
Restores 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>
-
Restores 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>
-
Restores 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
gprestoredoes not automatically restore objects on which the specified object depends. For example:-
If a table specified in
--include-tableuses a sequence, include this sequence explicitly. -
To restore a materialized view, include the tables that it uses.
For partitioned tables, only the root table can be included.
Learn more in Partial backups.
-
- --include-table-file <file_name>
-
Restores 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
gprestoredoes not automatically restore objects on which the specified object depends. For example:-
If a table specified in the file uses a sequence, include this sequence explicitly.
-
To restore a materialized view, include the tables that it uses.
For partitioned tables, only the root table can be included.
Learn more in Partial backups.
-
- --incremental
-
CAUTION
Incremental restore is a Beta feature with limitations. In the current implementation, it does not restore metadata and can be used only with
--data-only.Restores data from a specific incremental backup by its timestamp (
--timestamp). Other backups from the same incremental backup set are ignored.This includes the following table data:
-
All heap tables.
-
Append-optimized tables modified since the previous backup.
-
Leaf partitions modified since the previous backup.
The corresponding tables must exist in the database with the same structure as at the time of backup.
Learn more in Incremental restore.
-
- --jobs <int>
-
The number of jobs to use for parallel restore. By default,
gprestoreuses one job with a database connection and restores objects one by one. When the number of jobs is increased, each of them uses its own connection, which can speed up restore.The number of jobs cannot be increased for single-file backups (created with
gpbackup --single-data-file).Learn more in Parallel backup and restore.
- --truncate-table
-
Truncates tables before restoring their data. Must be used with
--data-onlyand a table filtering option (--include-tableor--include-table-file).Compatible with
--redirect-db; incompatible with--redirect-schema. - --redirect-schema <schema>
-
Restores objects into the specified schema instead of their original schemas. Must be used with an option that includes schemas (
--include-schemaor--include-schema-file) or tables (--include-tableor--include-table-file).Incompatible with options that exclude schemas or tables.
- --resize-cluster
-
Restores the database onto a target cluster with a different number of segments than the source cluster.
- --metadata-only
-
Restores only metadata, such as table definitions, without table data. The objects must not already exist in the target database. When combined with inclusion or exclusion options, can be used to recreate a specific subset of database objects.
Not valid for backups created without metadata, for example, with
gpbackup --data-only. - --on-error-continue
-
Continues restore when SQL errors occur during table creation or data insert. Other errors stop the operation.
Error details are saved to:
-
gprestore_<backup-timestamp>_<restore-time>_error_tables_metadata — metadata restore errors.
-
gprestore_<backup-timestamp>_<restore-time>_error_tables_data — data restore errors.
-
- --plugin-config <config_file_location>
-
Location of a
gpbackupplugin configuration file to use for restore.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 restore operation.Backups created with a plugin require the same plugin for restore.
Incompatible with
--backup-dir. - --quiet
-
Suppresses output except warning or error messages.
- --redirect-db <dbname>
-
Restores the backup into the specified database instead of the original one.
- --verbose
-
Adds
verboseseverity messages to thegprestoreoutput. - --with-globals
-
Restores the global Greengage DB system objects — roles, tablespaces, resource queues and groups, and so on. The backup must include global objects. The
gpbackuputility includes them by default unless the--without-globalsoption is specified. - --with-stats
-
Restores the statistics included in the backup. The backup must be created with
gpbackup --with-stats. - --run-analyze
-
Collects statistics for restored tables using ANALYZE. If a backup includes statistics (that is, was created with
gpbackup --with-stats), they are ignored.For partitioned tables,
--run-analyzeworks as follows:-
If the backup is created without
--leaf-partition-data,ANALYZEruns on the root table. -
If the backup is created with
--leaf-partition-data,ANALYZEruns on individual partitions.
Incompatible with
--with-stats. -
- --version
-
Prints the
gprestoreversion. - --help
-
Displays the help information about
gprestore.
Return codes
gprestore has the following return codes:
-
0— restore completed successfully. -
1— restore completed with non-fatal errors. -
2— restore failed.