Overview of the gprestore syntax

Pavel Semyonov

Contents

Options
Return codes

The gprestore utility has the following syntax:

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

Option Description

Option	Description
--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`). NOTE If the specified directory contains only one timestamp subdirectory, `--timestamp` can 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-db` creates it before restore. The new database is created from the template database `template0`
--copy-queue-size <int>	Sets the number of pre-initialized COPY commands to use for the restore operation. This can speed up backups with many small tables by reducing `COPY` initialization overhead. By default, `COPY` commands 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 `debug` and `verbose` severity messages to the `gprestore` output
--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-table` and 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-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 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-schema` and `--exclude-schema-file`) and with other table filtering options (`--include-table` and 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-schema` and `--exclude-schema-file` and with other table filtering options (`--include-table` and 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-table` and `--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-table` and `--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-schema` and others) or tables (`--exclude-table` and others). Note that `gprestore` does not automatically restore objects on which the specified object depends. For example: If a table specified in `--include-table` 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
--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-schema` and others) or tables (`--exclude-table` and others). Note that `gprestore` does 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, `gprestore` uses 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-only` and a table filtering option (`--include-table` or `--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-schema` or `--include-schema-file`) or tables (`--include-table` or `--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 `gpbackup` plugin configuration file to use for restore. `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 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 `verbose` severity messages to the `gprestore` output
--with-globals	Restores the global Greengage DB system objects — roles, tablespaces, resource queues and groups, and so on. The backup must be created with `gpbackup --with-globals`
--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-analyze` works as follows: If the backup is created without `--leaf-partition-data`, `ANALYZE` runs on the root table. If the backup is created with `--leaf-partition-data`, `ANALYZE` runs on individual partitions. Incompatible with `--with-stats`
--version	Prints the `gprestore` version
--help	Displays the help information about `gprestore`

--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).

NOTE

If the specified directory contains only one timestamp subdirectory, --timestamp can 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-db creates it before restore. The new database is created from the template database template0

--copy-queue-size <int>

Sets the number of pre-initialized COPY commands to use for the restore operation. This can speed up backups with many small tables by reducing COPY initialization overhead. By default, COPY commands 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 debug and verbose severity messages to the gprestore output

--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-table and 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-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 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-schema and --exclude-schema-file) and with other table filtering options (--include-table and 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-schema and --exclude-schema-file and with other table filtering options (--include-table and 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-table and --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-table and --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-schema and others) or tables (--exclude-table and others).

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

If a table specified in --include-table 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

--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-schema and others) or tables (--exclude-table and others).

Note that gprestore does 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, gprestore uses 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-only and a table filtering option (--include-table or --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-schema or --include-schema-file) or tables (--include-table or --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 gpbackup plugin configuration file to use for restore.

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 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 verbose severity messages to the gprestore output

--with-globals

Restores the global Greengage DB system objects — roles, tablespaces, resource queues and groups, and so on. The backup must be created with gpbackup --with-globals

--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-analyze works as follows:

If the backup is created without --leaf-partition-data, ANALYZE runs on the root table.
If the backup is created with --leaf-partition-data, ANALYZE runs on individual partitions.

Incompatible with --with-stats

--version

Prints the gprestore version

--help

Displays the help information about gprestore

gprestore has the following return codes:

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

gpbackup

Overview of the gprestore syntax

Options

Return codes