Table of Contents Previous Next


5 Operation : 5.4 BART Subcommands

All subcommands support a help option (-h, --help). If the help option is specified, information is displayed regarding that particular subcommand. The subcommand, itself, is not executed.
Note: In the following sections, the help option is omitted from the syntax diagrams for the purpose of providing clarity for the subcommand options.
For clarity, the syntax diagrams also show only the single-character form of the option. The Options subsections list both the single-character and multi-character forms of the options.
5.4.1 INIT
The INIT subcommand creates the BART backup catalog directory. For managed Postgres database servers of version 9.4, INIT sets the Postgres archive_command configuration parameter based upon the setting of the BART archive_command parameter in the server section of the BART configuration file. The INIT subcommand also rebuilds the BART backupinfo file.
bart INIT [ –s { server_name | all } ] [ -o ]
[ -r [ -i { backup_id | backup_name | all } ] ]
Note: Do not invoke the INIT subcommand while the BART BACKUP subcommand is in progress. Base backups affected by the backup process will be skipped and ignored by the INIT subcommand.
When the INIT subcommand is invoked, several different actions may be performed simultaneously. The following summarizes the actions performed under certain conditions and options.
When the INIT subcommand is invoked, the following action is always performed:
For the server specified by the -s option, or for all servers if -s all is specified or the -s option is omitted, the BART backup catalog directory structure is completed down to the archived_wals subdirectory if it does not already exist.
When the INIT subcommand is invoked without the -r option, the following action is always performed:
For the server specified by the -s option, or for all servers if -s all is specified or the -s option is omitted, an attempt is made to set the Postgres archive_command configuration parameter for database server version 9.4. If the archive_command parameter is already set (in other words, archive_command is set to a command string in either the postgresql.conf file or the postgresql.auto.conf file), then the existing archive_command setting is not replaced with the BART archive_command setting unless the -o option is specified as well. See Section 4.2.3.2 for additional information.
When the INIT subcommand is invoked with the -r option, the following action is always performed:
For the server specified by the -s option, or for all servers if -s all is specified or the -s option is omitted, the backupinfo file is recreated for all backups. If the -i option is included, then the backupinfo file is recreated for the specified backup.
The BART backupinfo file named backupinfo is initially created by the BACKUP subcommand and contains the backup information used by BART.
When INIT -r is invoked, BART rebuilds the backupinfo file using the content of the backup directory.
Note: If the backup was initially created with a user-defined backup name, and then the INIT -r option rebuilds that backupinfo file, the user-defined backup name is no longer available. Thus, future references to the backup must use the integer backup identifier.
The backupinfo file could be missing if the BACKUP subcommand did not complete successfully.
Note: The backupinfo file was not created by, nor used by BART version 1.0.x. Thus, if you wish to use BART 1.1 to access backups that were created with previous versions of BART, use the INIT -r option to create the backupinfo files. See Section 3.3 for information on upgrading from earlier BART versions.
-s, --server { server_name | all }
server_name is the name of the database server to which the INIT actions are to be applied. If all is specified or if the option is omitted, the actions are applied to all servers.
-o, --override
Override the existing, active Postgres archive_command configuration parameter setting in the postgresql.conf file or the postgresql.auto.conf file using the BART archive_command parameter in the BART configuration file. The INIT generated archive command string is written to the postgresql.auto.conf file. This option only applies for database server version 9.4. The replication database user of these database servers must be a superuser. Note: If the archive_mode configuration parameter is set to off, then the -o option must be used to set the Postgres archive_command using the BART archive_command parameter in the BART configuration file even if the archive_command is not currently set in postgresql.conf nor in postgresql.auto.conf.
-r, --rebuild
Rebuilds the backupinfo file. This file is a text file named backupinfo located in each base backup subdirectory.
-i, --backupid { backup_id | backup_name | all }
backup_id is an integer, base backup identifier. backup_name is the user-defined alphanumeric name for the base backup. If all is specified or if the option is omitted, the backupinfo files of all backups for the database servers specified by the -s option are recreated. The -i option can only be used with the -r option.
The following example completes the BART backup catalog directory and sets the Postgres archive_command using the default BART archive command format of scp %p %h:%a/%f. The default BART archive command format is used when the BART archive_command parameter is not explicitly included or assigned a command string within the server section of the BART configuration file.
The archive_mode and archive_command parameters in the database server are set as follows:
The INIT subcommand is invoked. The -o option is not necessary since archive_mode is on and archive_command is not set.
The Postgres archive_command is now set as follows:
The following example overrides an existing, active, archive command by resetting the Postgres archive_command parameter from the BART archive_command = 'cp %p %a/%f' parameter in the BART configuration file.
The archive_mode and archive_command parameters in the database server are set as follows:
The INIT subcommand is invoked with the -o option to override the current Postgres archive_command setting.
The Postgres archive_command is now set as follows:
5.4.2 BACKUP
The BACKUP subcommand creates a base backup by invoking the Postgres pg_basebackup utility program.
Note: Use the --debug option prior to the BACKUP subcommand to see the exact invocation of pg_basebackup.
bart BACKUP –s { server_name | all } [ -F { p | t } ]
[ -z ] [ –c compression_level ]
[ --backup-name backup_name ]
By default, the target format is a tar file, and the -x flag is passed to pg_basebackup to ensure that the WAL files are also archived.
The backup is saved in the directory formed by backup_path/server_name/backup_id where backup_path is the value assigned to the backup_path parameter in the BART configuration file, server_name is the lowercase name of the database server as listed in the configuration file, and backup_id is an integer, base backup identifier assigned by BART to the particular base backup.
While a BACKUP subcommand is in progress, no other processes are allowed to access or interfere with the affected base backups. Therefore any of the following subcommands issued while a backup is in progress will skip and ignore those affected base backups – INIT, SHOW-BACKUPS, VERIFY-CHKSUM, MANAGE, and DELETE.
Note: Although this capability to check and warn if there is not enough disk space available before copying backup files is provided with the BACKUP subcommand, the RESTORE subcommand does not have this same capability. Thus, it is possible that the RESTORE subcommand may result in an error while copying files if there is not enough disk space available.
In the postgresql.conf file, be sure the wal_keep_segments configuration parameter is set to a sufficiently large value, otherwise you may encounter the following error from pg_basebackup during usage of the BACKUP subcommand:
A low setting of the wal_keep_segments configuration parameter may result in the deletion of some WAL files before pg_basebackup has had a chance to save them to the BART backup catalog.
For information about the wal_keep_segments parameter, see the PostgreSQL Core Documentation available at:
If in the BART configuration file, parameter setting xlog-method=stream applies to a given database server, streaming of the transaction log in parallel with creation of the backup is performed for that database server, otherwise the transaction log files are collected upon completion of the backup. See Section 4.1 for global setting of xlog-method. See Section 4.2.5 for setting of xlog-method by database server.
Note: If the transaction log streaming method is used, the -F p option for a plain text backup format must be specified with the BACKUP subcommand.
Note: If the database server contains user-defined tablespaces (that is, tablespaces created with the CREATE TABLESPACE command), only the tar backup file format is supported. In other words, the BACKUP subcommand option -F p for specifying a plain text backup file format may not be used. Consequently, transaction log streaming with the BACKUP subcommand cannot be used. Thus, the xlog-method = fetch parameter setting must be in effect for such database servers containing user-defined tablespaces.
-s, --server { server_name | all }
server_name is the name of the database server to be backed up as specified in the BART configuration file. If all is specified, all servers are backed up. Note: If all is specified, and a connection to a database server listed in the BART configuration file cannot be opened, the backup for that database server is skipped, but the backup operation continues for the other database servers. The following error message is displayed when a database server connection fails:
-F, --format { p | t }
Specifies the backup file format. Use p for plain text or t for tar. If the option is omitted, the default is tar format.
-z, --gzip
-c, --compress-level compression_level
Specifies the gzip compression level on the tar file output. compression_level is a digit from 1 through 9, inclusive, with 9 being the best compression. This option is applicable only for the tar format.
--backup-name backup_name
User-defined, friendly name to be assigned to the base backup. This is an alphanumeric string that may include the following variables to be substituted by the timestamp values when the backup is taken: 1) %year – 4-digit year, 2) %month – 2-digit month, 3) %day – 2-digit day, 4) %hour – 2-digit hour, 5) %minute – 2-digit minute, and 6) %second – 2-digit second. To include the percent sign (%) as a character in the backup name, specify %% in the alphanumeric string. Enclose the string in single quotes (') or double quotes (") if it contains space characters. Use of space characters, however, then requires enclosing the backup name in quotes when referenced with the -i option by other subcommands. This option overrides the backup-name parameter in the server section of the BART configuration file. If the --backup-name option is not specified, and the backup-name parameter is not set for this database server in the BART configuration file, then the base backup can only be referenced in other BART subcommands by the BART assigned, integer backup identifier.
The following example creates a base backup of server ppas93_remote in the default tar format with gzip compression. The debug option (--debug) is also specified so the actual pg_basebackup command is shown. Note that checksums are generated for the base backup and user-defined tablespaces for the tar format backup.
Note that the -F p option must be specified with the BACKUP subcommand when streaming is used.
The SHOW-SERVERS subcommand displays the information for the managed database servers listed in the BART configuration file.
bart SHOW-SERVERS [ –s { server_name | all } ]
-s, --server { server_name | all }
server_name is the name of the database server whose BART configuration information is to be displayed. If all is specified or if the option is omitted, information for all database servers is displayed.
The SHOW-BACKUPS subcommand displays the base backup information for the managed database servers.
bart SHOW-BACKUPS [ –s { server_name | all } ]
[ -i { backup_id | backup_name | all } ]
Note: If SHOW-BACKUPS is invoked while the BART BACKUP subcommand is in progress, base backups affected by the backup process show an in progress status in the displayed backup information.
-s, --server { server_name | all }
server_name is the name of the database server whose base backup information is to be displayed. If all is specified or if the option is omitted, the base backup information for all database servers is displayed.
-i, --backupid { backup_id | backup_name | all }
backup_id is an integer, base backup identifier. backup_name is the user-defined alphanumeric name for the base backup. If all is specified or if the option is omitted, all base backup information for the relevant database server is displayed.
-t, --toggle
The VERIFY-CHKSUM subcommand verifies the MD5 checksums of the base backups and any user-defined tablespaces for the specified database server or for all database servers.
[ –s { server_name | all } ]
[ -i { backup_id | backup_name | all } ]
The VERIFY-CHKSUM subcommand is not applicable to plain format backups. It is only used for tar format backups.
Note: If VERIFY-CHKSUM is invoked while the BART BACKUP subcommand is in progress, base backups affected by the backup process will be skipped and ignored by the VERIFY-CHKSUM subcommand.
-s, --server { server_name | all }
server_name is the name of the database server whose tar backup checksums are to be verified. If all is specified or if the -s option is omitted, the checksums are verified for all database servers.
-i, --backupid { backup_id | backup_name | all }
backup_id is the integer, base backup identifier of a tar format base backup whose checksum is to be verified along with any user-defined tablespaces. backup_name is the user-defined alphanumeric name for the base backup. If all is specified or if the -i option is omitted, the checksums of all tar backups for the relevant database server are verified.
5.4.6 MANAGE
The MANAGE subcommand evaluates, marks, and deletes backups based upon the retention policy. The MANAGE subcommand also invokes compression on the archived WAL files based upon the wal_compression parameter.
bart MANAGE [ –s { server_name | all } ]
-i { backup_id | backup_name | all } ]
Note: Do not invoke the MANAGE subcommand while the BART BACKUP subcommand is in progress. Base backups affected by the backup process will be skipped and ignored by the MANAGE subcommand.
Application of a retention policy is dependent upon the retention_policy parameter in the BART configuration file. Management of backups such as evaluating the backups according to the retention policy, marking their status, and deleting obsolete backups are then performed with the MANAGE subcommand. See Section 5.2 for information on retention policy management.
WAL compression is controlled by the wal_compression parameter in the BART configuration file. See sections 4.1 and 4.2.5 for information on setting this parameter.
When the MANAGE subcommand is invoked, several different actions may be performed simultaneously. The following summarizes the actions performed under certain conditions and options.
When the MANAGE subcommand is invoked with no options or with only the -s option to specify all or a particular database server, the following actions are performed:
For the server specified by the -s option, or for all servers if -s all is specified or the -s option is omitted, active backups are marked as obsolete in accordance with the retention policy.
All backups that were marked obsolete or keep prior to invoking the MANAGE subcommand remain marked with the same prior status.
When the MANAGE subcommand is invoked with any other option besides the -s option, the following actions are performed:
For the server specified by the -s option, or for all servers if -s all is specified or the -s option is omitted, the action performed is determined by the other specified options (that is, -l to list obsolete backups, -d to delete obsolete backups, -c to keep or to return backups to active status, or -n to perform a dry run of any action).
All backups that were marked obsolete or keep prior to invoking the MANAGE subcommand remain marked with the same prior status unless the -c option (without the -n option) is specified to change the backup status of the particular backup or all backups referenced with the -i option.
When the RESTORE subcommand is invoked, if the -c option is specified or if the enabled setting of the copy_wals_during_restore BART configuration parameter is in effect for the database server, then the following actions occur: If compressed, archived WAL files are stored in the BART backup catalog and the location to which the WAL files are to be restored is on a remote host relative to the BART host, then the archived WAL files are transmitted across the network to the remote host in compressed format, but only if the gzip compression program is accessible in the PATH of the remote user account that is used to log into the remote host when performing the RESTORE operation. This remote user is specified with either the remote-host parameter in the BART configuration file (see Section 4.2.5) or the RESTORE -r option (see Section 5.4.7). Transmission of compressed WAL files results in less network traffic. After the compressed WAL files are transmitted across the network, the RESTORE subcommand uncompresses the files for the point-in-time recovery operation.
When the RESTORE subcommand is invoked without the -c option and the disabled setting of the copy_wals_during_restore BART configuration parameter is in effect for the database server, then any compressed, archived WAL files needed for the RESTORE operation are uncompressed in the BART backup catalog. The uncompressed WAL files can then be streamed to the remote host by the restore_command in the recovery.conf file when the database server archive recovery begins.
-s, --server { server_name | all }
server_name is the name of the database server to which the actions are to be applied. If all is specified or if the -s option is omitted, the actions are applied to all database servers.
-l, --list-obsolete
-d, --delete-obsolete
-c, --change-status { keep | nokeep }
Change the status of a backup to keep to retain it indefinitely. Specify nokeep to change the status of any backup, regardless of its current marked status, back to active status. The backup can then be re-evaluated and possibly be marked to obsolete according to the retention policy by subsequent usage of the MANAGE subcommand. Note: The –i option must also be specified when using the -c option.
-i, --backupid { backup_id | backup_name | all }
backup_id is an integer, base backup identifier. backup_name is the user-defined alphanumeric name for the base backup. If all is specified, the actions are applied to all backups. Note: The -i option must only be used with the -c option.
-n, --dry-run
Displays the results as if the operation was performed, however, no changes are actually made. In other words, a test run is performed so that you can see the results prior to actually implementing the actions. Thus, -n specified with the -d option displays which backups would be deleted, but does not actually delete the backups. Specifying the -n option with the -c option displays the keep or nokeep action, but does not actually change the backup from its current status. Specifying -n alone with no other options, or with only the -s option, displays which active backups would be marked as obsolete, but does not actually change the backup status. In addition, no compression is performed on uncompressed, archived WAL files even if WAL compression is enabled for the database server.
The following example uses the enabled wal_compression parameter in the BART configuration file as shown by the following:
When the MANAGE subcommand is invoked, the following message is displayed indicating that WAL file compression is performed:
5.4.7 RESTORE
The RESTORE subcommand restores the base 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 to perform point-in-time recovery.
Note: Use the --debug option prior to the RESTORE subcommand to see the commands executed during the process.
bart RESTORE –s server_name -p restore_path
[ –i { backup_id | backup_name } ]
[ -r remote_user@remote_host_address ]
[ -t timeline_id ]
[ { -x target_xid | -g target_timestamp } ]
Note: Check to ensure that the host where the backup is to be restored contains enough disk space for the base 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 base backup to use for the restore operation and obtain the base backup ID. If you wish to use the latest (that is, the most recent) base backup, you can omit the -i option and the RESTORE subcommand uses that backup by default.
The base 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 none of -t timeline_id, -x target_xid, and -g target_timestamp options are given, then no recovery.conf file is generated. In other words, only the base backup is restored and no point-in-time recovery is performed.
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 one is generated, inspect the recovery configuration file named recovery.conf located in the restore_path directory to verify the parameter settings for a point-in-time recovery operation.
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.
-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, base backup identifier of the base backup to be used for the restoration. backup_name is the user-defined alphanumeric name for the base backup. If the option is omitted, the default is to use the latest (that is, the most recent) base 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.
-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 ppas93_remote to the /opt/restore directory up to timestamp 2015-12-15 10:47:00.
The following example performs the RESTORE operation with the -c option to copy the archived WAL files to the local restore_path/archived_wals directory. The -d debug option displays the commands executed during the process.
5.4.8 DELETE
The DELETE subcommand removes the subdirectory and data files from the BART backup catalog for the specified base backups along with its archived WAL files.
[']{ backup_id | backup_name },... }[']
Note: Do not invoke the DELETE subcommand while the BART BACKUP subcommand is in progress. Base backups affected by the backup process will be skipped and ignored by the DELETE subcommand.
-s, --server server_name
server_name is the name of the database server whose backups are to be deleted.
-i, --backupid { all | [']{ backup_id | backup_name },... }['] }
backup_id is the integer, base backup identifier of the base backup to be deleted. backup_name is the user-defined alphanumeric name for the base backup. Multiple backup identifiers and backup names may be specified in a comma-separated list. The list must be enclosed within single quotes if there is any white space appearing before or after each comma. If all is specified, all of the base backups and their archived WAL files for the specified database server are deleted.
-n, --dry-run

5 Operation : 5.4 BART Subcommands

Table of Contents Previous Next