Table of Contents Previous Next



5.4.8 RESTORE
The RESTORE subcommand restores the backup and its archived WAL files for the designated database server to the specified directory location. If the appropriate RESTORE options are specified, a recovery.conf file is generated with the recovery configuration parameters.
bart RESTORE –s server_name -p restore_path
[ –i { backup_id | backup_name } ]
[ -r remote_user@remote_host_address ]
[ -w number_of_workers ]
[ -t timeline_id ]
[ { -x target_xid | -g target_timestamp } ]
Review the information (especially in Section 25.3.4 “Recovering Using a Continuous Archive Backup”) documented in the PostgreSQL Core Documentation available at:
Note: See Section 2.1.5.2 for special requirements when restoring an incremental backup to a remote database server.
Note: Check to ensure that the host where the backup is to be restored contains enough disk space for the backup and its archived WAL files. The RESTORE subcommand does not have the capability to detect if there is sufficient disk space available before restoring the backup files. Thus, it is possible that the RESTORE subcommand may result in an error while copying files if there is not enough disk space available.
Step 1: Stop the Postgres database server on which you will be performing the restore operation.
Step 2: Inspect the pg_xlog subdirectory of the data directory and be sure to save any WAL files that have not yet been archived to the BART backup catalog (backup_path/server_name/archived_wals).
If there are some files that have not been archived, save these to a temporary location. You will later need to copy these files to the restored pg_xlog subdirectory after completing the RESTORE subcommand and before restarting the database server.
Step 3: Decide if you will restore to the current data directory, or to a new directory.
Step 4: Perform the same process for tablespaces as described in Step 3. The tablespace_path parameter in the BART configuration file must contain the tablespace directory paths to which the tablespace data files are to be restored. See Section 4.2.4 for more information.
Step 5: Identify the timeline ID you wish to use to perform the restore operation.
Step 6: Identify the backup to use for the restore operation and obtain the backup ID or backup name. If you wish to use the latest (that is, the most recent) backup, you can omit the -i option and the RESTORE subcommand uses that backup by default.
The backups can be listed with the SHOW-BACKUPS subcommand as in the following example:
Step 7: Run the BART RESTORE subcommand.
If any of -t timeline_id, -x target_xid, or -g target_timestamp options are given, then a recovery.conf file is generated with the recovery configuration parameters corresponding to the specified options. That is, point-in-time recovery is performed upon restarting the database server.
If you do not specifythe -t timeline_id, -x target_xid, and -g target_timestamp options, then a minimal recovery.conf file is generated. Archive recovery will proceed only until consistency is reached, with no restoration of files from the archive.
Use the --debug option to display the underlying commands used by BART.
Note: If invalid values are specified for the options, or if invalid option combinations are specified (for example, if both the -x target_xid and the -g target_timestamp options are given), no error message is generated by BART. The invalid options are accepted and passed to the recovery.conf file, which will then be processed by the database server when it is restarted.
Note: If the -c option is specified or if the enabled setting of the copy_wals_during_restore BART configuration parameter is in effect for this database server, then the following actions occur:
In addition to restoring the database cluster to the directory specified by the -p restore_path option, the archived WAL files of the backup are copied from the BART backup catalog to the subdirectory restore_path/archived_wals.
If a recovery.conf file is generated, the command string set in the restore_command parameter retrieves the WAL files from this archived_wals subdirectory relative to the restore_path parent directory as: restore_command = 'cp archived_wals/%f %p'
Step 8: Copy any saved WAL files from Step 2 to the restore_path/pg_xlog subdirectory.
Step 9: Inspect the restored directories and data files of the restored database cluster in directory restore_path.
All files and directories must be owned by the user account that you intend to use to start the database server. This user account is typically the Postgres user account (enterprisedb or postgres), but it may be some other user account of your choice. Recursively change the user and group ownership of the restore_path directory, its files, and its subdirectories if necessary.
Step 10: If you are performing a point-in-time recovery, inspect the recovery.conf file located in the restore_path directory to verify it contains the appropriate parameter settings to recover to the indicated point. Otherwise, the recovery.conf file should be configured to recover only until the cluster reaches consistency. In either case, the settings may be modified as desired.
Step 11: WAL archiving is disabled at this point.
The BART RESTORE subcommand adds an archive_mode = off parameter at the end of the postgresql.conf file.
The original archive_mode parameter still resides in the postgresql.conf file in its initial location with its last setting.
Step 12: Start the database server to initiate recovery. After completion, check the database server log file to ensure the recovery was successful.
Note: If the backup is restored to a different database cluster directory than where the original database cluster resided, then certain operations dependent upon the database cluster location may fail if their supporting service scripts are not updated to reflect the new directory location where the backup has been restored.
For information about the usage and modification of service scripts, see the EDB Postgres Advanced Server Installation Guide available at:
Note: Before modifying the service unit files for Advanced Server 9.6 in RHEL 7/CentOS 7, see the instructions in Section 3.5.2 “Modifying the Data Directory Location on CentOS or RedHat 7.x” in the EDB Postgres Advanced Server 9.6 Installation Guide. For Advanced Server 10 in RHEL 7/CentOS 7, see the same topic in Section 3.3.3 in the EDB Postgres Advanced Server 10 Installation Guide.
-s, --server server_name
server_name is the name of the database server to be restored.
-p, --restore-path restore_path
restore_path is the directory path where the backup of the database server is to be restored. The directory must be empty and have the proper ownership and privileges assigned to it.
-i, --backupid { backup_id | backup_name }
backup_id is the integer, backup identifier of the backup to be used for the restoration. backup_name is the user-defined alphanumeric name for the backup. If the option is omitted, the default is to use the latest (that is, the most recent) backup.
-r, --remote-host remote_user@remote_host_address
remote_user is the user account on the remote database server host that accepts a password-less SSH/SCP login connection and is the owner of the directory where the backup is to be restored. remote_host_address is the IP address of the remote host to which the backup is to be restored. This option must be specified if the remote_host parameter for this database server is not set in the BART configuration file. Note: If the BART user account is not the same as the operating system account that owns the restore_path directory given with the -p option, the remote_host BART configuration parameter or the RESTORE subcommand -r option must be used to specify the restore_path directory owner even when restoring to a directory on the same host as the BART host. See Section 4.2.5 for information on the remote_host parameter.
-w, --workers number_of_workers
number_of_workers is the specification of the number of worker processes to run in parallel to stream the modified blocks of an incremental backup to the restore location. For example, if 4 worker processes are specified, 4 receiver processes on the restore host and 4 streamer processes on the BART host are used. The output of each streamer process is connected to the input of a receiver process. When the receiver gets to the point where it needs a modified block file, it obtains those modified blocks from its input. With this method, the modified block files are never written to the restore host disk. If the -w option is omitted, the default is 1 worker process.
-t, --target-tli timeline_id
timeline_id is the integer identifier of the timeline to be used for replaying the archived WAL files for point-in-time recovery.
-x, --target-xid target_xid
target_xid is the integer identifier of the transaction ID that determines the transaction up to and including, which point-in-time recovery encompasses. Only one of the -x target_xid or the -g target_timestamp option should be included if point-in-time recovery is desired.
-g, --target-timestamp target_timestamp
target_timestamp is the timestamp that determines the point in time up to and including, which point-in-time recovery encompasses. Only one of the -x target_xid or the -g target_timestamp option should be included if point-in-time recovery is desired.
-c, --copy-wals
If specified, the archived WAL files are copied from the BART backup catalog to directory restore_path/archived_wals. If BART generates the recovery.conf file for point-in-time recovery, the restore_command retrieves the WAL files from restore_path/archived_wals for the database server archive recovery. If the -c option is omitted and the copy_wals_during_restore parameter in the BART configuration file is not enabled in a manner applicable to this database server, the default action is that the restore_command in the recovery.conf file is generated to retrieve the archived WAL files directly from the BART backup catalog. See sections 4.1 and 4.2.5 for information on the copy_wals_during_restore parameter.
The following example restores database server mktg to the /opt/restore directory up to timestamp 2015-12-15 10:47:00.
The following example performs the RESTORE operation with the copy_wals_during_restore parameter enabled to copy the archived WAL files to the local restore_path/archived_wals directory.


Table of Contents Previous Next