Managing BART v9

Suggest edits

The EDB Backup and Recovery Tool (BART) is an administrative utility providing simplified backup and recovery management for multiple local or remote EDB Postgres Advanced Server and PostgreSQL database servers. For more information about BART, see Backup and Recovery Tool.

This feature is built into the Postgres Enterprise Manager (PEM) web interface and makes it easier for you to monitor and manage BART.

In PEM version 7.10 and later, you can manage a BART server and perform all the BART operations through the PEM console.

Prerequisites

  • Before adding a BART server to the PEM console, you must manually install and configure BART on the BART host. For more information about installing and configuring BART, see BART installation.
Note

While integrating PEM with BART, the PEM agent creates the backup directory required for BART and ensures that the ownership and permissions on the directory are correct.

  • Before associating a database server with a BART server, you must install SSH on the database server and the BART server.

  • Before restoring a BART backup, you must install BART, a PEM agent, and SSH on the target server. SSH must also be installed on the BART server that you plan to use to restore.

  • To take a backup of the replica database servers, ensure that the latest pg_basebackup utility is installed on the database server that you want to manage through BART.

Configuring a BART server

You can use the Create–BART Server dialog box to register an existing BART server with the PEM server. To open the dialog box, right-click the BART Servers node and select Create-BART Server.

Use the General tab to describe the general properties of the BART server:

  • Use the Agent Name field to select the agent that you want to use for the BART server. Only those PEM agents that are supported for BART are listed.

  • Use the Server Name field to specify a name for the server. The name specified identifies the server in the Browser tree.

  • Use the Host field to specify the IP address of the host or agent where BART is installed.

  • Use the User field to specify the user name to use for performing all the BART operations. You can use the enterprisedb (for EDB Postgres Advanced Server) or postgres (for PostgreSQL) database user account, or you can create a new BART user account. This user must be an operating system user who owns the BART backup catalog directory.

  • Use the Installation path field to specify the directory path where BART is installed on the host or BART server.

  • Use the Backup path field to specify the file system parent directory to store all BART backups and archived WAL files.

  • Use the pg_basebackup_path field to specify the path to the pg_basebackup utility.

  • Use the Xlog/WAL method field to specify how to collect the transaction log while pg_basebackup executes. The default option is fetch, which specifies to collect the transaction log files after the backup has completed. Set the Xlog/WAL method to stream to stream the transaction log in parallel with the full base backup creation. If streaming is used, the max_wal_senders configuration parameter in the postgresql.conf file for affected database servers must account for an additional session for the streaming of the transaction log. The setting must be a minimum of 2.

    For more information about Xlog/WAL methods, see PostgreSQL core documentation.

  • Use the Retention policy field to specify the retention policy for the backup. This policy determines when to mark an active backup as obsolete and hence a candidate for deletion. You can specify the retention policy in terms of number of backup or in terms of duration (days, weeks, or months).

  • Use the optional Log file field to specify the path to BART log file.

Use the Misc tab to describe the backup-related properties of the BART server:

  • Use the Scanner log file field to specify the path to the Xlog/WAL scanner log file. BART creates a log scanner file only if you specify the path.

  • Use the Socket dir path field to specify the path to the socket directory to store all BART sockets. The default directory is /tmp. This parameter is added from BART version 2.5.2 and later.

  • Use the Socket name field to specify the BART socket file name. Using this option overrides the default BART socket name generated using MD5 checksum. This parameter is added in BART version 2.5.6 and later.

  • Use the WAL compression? switch to specify if you want to compress the archived Xlog/WAL files in Gzip format. To enable WAL compression, the gzip compression program must be present in the BART user account’s PATH. Don't enable the WAL compression setting for database servers where you need to take incremental backups.

  • Use the Copy WALs during restore? field to specify how the archived WAL files are collected when invoking the RESTORE operation. Set to Enabled to copy the archived WAL files from the BART backup catalog to the restore_path/archived_wals directory prior to the database server archive recovery. Set to Disabled to retrieve the archived WAL files directly from the BART backup catalog during the database server archive recovery. Enabling this option helps you save time during the restore operation.

  • Use the Thread count field to specify the number of worker threads for copying blocks or data files from the database server to the BART backup catalog. Specify a thread count of 1 if you want to take the backup using the pg_basebackup utility.

  • Use the Batch size field to specify the number of blocks of memory used for copying modified blocks. This applies only to incremental backups.

  • Use the Scan interval field to specify the number of seconds to wait before the WAL scanner scans the new WAL files.

  • Use the MBM scan timeout field to specify the number of seconds to wait for MBM files before timing out. This applies only to incremental backups.

  • Use the Workers field to specify the number of parallel worker processes required to stream the modified blocks of an incremental backups to the restore host.

Associating the BART server with a database server

After configuring the BART server, you must associate it with the database server whose backup you want to manage with BART. You can either:

  • Use the PEM console to modify the properties of an existing monitored database server to map it to the newly configured BART server.

  • Use the PEM console to create a new monitored database server and map it to the newly configured BART server.

To map the BART server to a new PEM database server, right-click the PEM Server Directory node and select Create > Server. Enter the details on all the generic tabs and then enter the BART-specific details on the BART tab.

Use the General tab to describe the general properties of the BART Server that map to the PEM server:

  • Use the BART server field to select the BART server name. All the BART servers configured in the PEM console are listed.

  • Use the Server name field to specify a name for the database server that you want to back up using the BART server. This name is stored in the BART configuration file.

  • Use the Description field to specify the description of the database server.

  • Use the Backup name field to specify a template for user-defined names to assign to the backups of the database server. If you don't specify a backup name template, then the backup can be referenced in BART sub-commands only by the BART-assigned, integer backup identifier.

  • Use the Host address field to specify the IP address of the database server that you want to configure for backup.

  • Use the Port field to specify the port to use for the database that you want to backup.

  • Use the User field to specify the user of the database that you want to back up using BART through the PEM console. If you want to enable incremental backups for this database server, then the user must be a superuser.

  • Use the Password field to specify the password for the user of the database that you want to back up.

  • Use the Cluster Owner field to specify the Linux operating system user account that owns the database cluster. This is typically enterprisedb for EDB Postgres Advanced Server database clusters installed in the Oracle databases compatible mode. It is postgres for PostgreSQL database clusters and for EDB Postgres Advanced Server database clusters installed in the PostgreSQL databases compatible mode.

  • Use the Archive command field to specify the desired format of the archive command string to use in the bart.cfg file. Inputs provided for the archive command overwrite the database server's Postgresql.conf file. Once the server is added, the database server restarts or database configurations are reloaded.

  • Use the Archive path field to store the archived WAL files. The default location is the BART backup catalog. This parameter is in BART version 2.5.2 and later.

  • Use the Allow incremental backup? switch to specify whether to enable incremental backup for this database server.

  • Use the Setup passwordless SSH? switch to specify if you want to create SSH certificates to allow passwordless logins between the database server and the BART server. Be sure to bind a PEM agent before setting up the passwordless SSH authentication. Passwordless SSH doesn't work for a database server being remotely monitored by a PEM agent.

Use the fields on the Misc tab to describe the miscellaneous properties of the BART server:

  • Use the Override default configuration? switch to specify if you want to override the BART server configurations with the specific database server configurations.

  • Use the Xlog method to specify how to collect the transaction log while pg_basebackup executes.

  • Use the Retention policy field to specify the retention policy for the backup. This policy determines when to mark an active backup as obsolete and hence a candidate for deletion. You can specify the retention policy in terms of number of backup or in terms of duration (days, weeks, or months).

  • Use the WAL compression switch to specify if you want to compress the archived Xlog/WAL files in Gzip format. To enable WAL compression, the gzip compression program must be present in the BART user account’s PATH. The wal_compression setting must not be enabled for those database servers where you need to take incremental backups.

  • Use the Copy WALs during restore field to specify how the archived WAL files are collected when invoking the RESTORE operation. Set to enabled to copy the archived WAL files from the BART backup catalog to the <;restore_path>/archived_wals directory prior to the database server archive recovery. Set to disabled to retrieve the archived WAL files directly from the BART backup catalog during the database server archive recovery.

  • Use the Thread count field to specify the number of threads to copy the blocks. You must set the thread count to 1 if you want to take a backup with the pg_basebackup utility.

  • Use the Batch size field to specify the number of blocks of memory used for copying modified blocks. This option applies only to incremental backups.

  • Use the Scan interval field to specify the number of seconds for the WAL scanner to wait before scanning the new WAL files.

  • Use the MBM scan timeout field to specify the number of seconds to wait for MBM files before timing out. This option applies only to incremental backups.

  • Use the Workers field to specify the number of parallel worker processes required to stream the modified blocks of an incremental backups to the restore host.

Viewing the BART server details on a PEM dashboard

After associating the BART server with a database server, you can review the backup and restore details for that server on the PEM dashboard. You can also perform operations such as restoring or deleting a backup that's listed on the dashboard.

When you select a monitored BART server, details of all the associated database servers along with their backups and restore activities are displayed as a chart on the dashboard in the Backup and Restore Activities panel. You can filter the list of backups on criteria specified in the filter boxes (database server, activity, or duration).

The Managed Database Servers panel displays a list of all the database servers managed by a BART server along with their high-level details.

The Initiated Server Backups panel displayes a list of all the backups of the database servers managed by a BART server. You can filter the list to display the details of any database server. You can also filter the list on criteria that you specify in the filter box. Typically, this filter works with any kind of string value (excluding date, time, and size) listed under the columns. For example, you can type tar to filter the list and display only those backups that are in tar format.

Backup details displayed include the Backup Name, Backup ID, Status, Server Name, Start Time, Type, Parent ID, Format, Duration, and Size. The Status column shows the status of the backups. Status can be one of the following: In Progress, Active, Keep, or Obsolete.

A backup is marked as Obsolete when the backup retention period has passed or if the number of retained backups (specified as the retention policy of the BART server) is met. If you want to make an exception so that a particular backup doesn't get marked as Obsolete even after the retention policy expires, mark that backup as Keep. Similarly, if you mark a particular backup as NoKeep, the backup is reevaluated to determine whether to change its status back to Obsolete based on the current retention policy.

If any of the scheduled tasks for backup, restore, validate host, validate server, or delete obsolete backup for any of the BART server is deleted, it doesn't appear under the BART Tool Activities graph of the BART server's dashboard. However, it is listed under the Initiated Server Backups list.

A pin in the first column under Actions indicates that you can mark a backup as Keep by selecting the pin. An inverted pin indicates that you can mark the backup as NoKeep. The second column under Actions displays the Restore icon, which you can select to perform the restore operation.

You can delete all the obsolete backups by selecting Delete Obsolete. You can also refresh the list of backups by selecting Refresh.

Scheduling BART backups

To create or manage a backup, select Tools > Schedule Backup. The dialog box header displays general execution information about the backup. Select the plus sign (+) to add information about a scheduled backup. Enter the backup details in the schedule definition dialog.

Use the General tab to describe the general properties of the backup:

  • Use the Database Server field to specify the target database server that you want to back up.

  • Use the Backup name to specify a name for the backup.

  • Use the Backup type switch to specify the backup type—full backup or incremental.

  • Use the Parent backup field to select the ID of the parent backup for incremental backup. This parent backup can be a full or an incremental backup.

  • Use the Format switch to specify the output format of the backup—plain text or tar. For incremental backup, select plain text.

  • Use the Gzip compression switch to specify whether to enable gzip compression for the backup. This option applies only to tar format.

  • Use the Compression level field to specify the gzip compression level on the tar file output.

  • Use the Thread count field to specify the number of threads that copy the blocks.

  • Use the MBM scan timeout field to specify the number of seconds to wait for required MBM files before timing out.

  • Use the Verify checksum field to specify if you want the application to verify the checksum of the backup.

  • Use the pg_basebackup field to specify whether to use the pg_basebackup utility for the backup. Typically, you use the pg_basebackup utility only for backing up the replica servers since you can't use it for incremental backups.

Provide scheduling details for the backup on the Schedule tab:

  • Use the Enabled? switch to indicate whether to enable the schedule.

  • Use the calendar selector in the Start field to specify the starting date and time for the schedule.

  • Use the calendar selector in the End field to specify the ending date and time for the schedule.

Use the Repeat tab to specify the details about the schedule in a cron-style format. The schedule executes on each date or time element selected on the Repeat tab. Click in a field to open a list of valid values for that field. Select a specific value to add that value to the list of selected values for the field.

Use the fields in the Days box to specify the days when the schedule executes:

  • Use the Week Days field to select the days when the schedule executes.

  • Use the Month Days field to select the numeric days when the schedule executes. Specify the Last Day value to perform the schedule on the last day of the month, regardless of the date.

  • Use the Months field to select the months when the schedule executes.

Use the fields in the Times box to specify the times when the schedule executes:

  • Use the Hours field to select the hour when the schedule executes.

  • Use the Minutes field to select the minute when the schedule executes.

Use the Notifications tab to specify the email notification settings for a scheduled backup:

  • Use the Send the notifications field to specify when to send the email notifications.

  • Use the Email group field to specify the email group to receive the email notification.

Scheduling BART obsolete backups deletion

Use the Schedule Obsolete Backup Deletion dialog box to schedule or modify a BART obsolete backup deletion.

Use the context menu from the database server where BART was configured.

Provide information on the General tab to describe the scheduling details:

  • Use the Enabled? switch to indicate whether to enable the schedule.
  • Use the calendar selector in the Start field to specify the starting date and time for the schedule.
  • Use the calendar selector in the End field to specify the ending date and time for the schedule.

Use the Repeat tab to specify the details about the schedule in a cron-style format. The schedule executes on each date or time element selected on the Repeat tab. Click in a field to open a list of valid values. Select a value to add it to the list of selected values for the field.

Use the fields in the Days box to specify the days when the schedule executes:

  • Use the Week Days field to select the days when the schedule executes.
  • Use the Month Days field to select the numeric days when the schedule executes. Specify Last Day to perform the schedule on the last day of the month, regardless of the date.
  • Use the Months field to select the months when the schedule executes.

Use the fields in the Times box to specify the times when the schedule executes:

  • Use the Hours field to select the hour when the schedule executes.
  • Use the Minutes field to select the minute when the schedule executes.

Restoring BART backups

You can restore the backups that you created earlier using BART server on a target remote host. When you select a particular BART server, all the associated backups are listed in the dashboard under Initiated Server Backups.

To restore a backup, select Restore next to the backup that you want to restore.

In the Restore Backup dialog box, provide information in the fields on the General tab:

  • Use the Target agent field name to specify the name of the agent where you want to restore the backup.

  • Use the Remote user field to specify the user account on the remote database server host where you want to restore the backup.

  • Use the Remote host address field to specify the IP address of the remote host where you want to restore the backup.

  • Use the SSH port field to specify the SSH port to use for restoring the backup.

  • Use the Restore path field to specify the path where you want to restore the backup.

  • Use the Number of workers field to specify processes to run in parallel to stream the modified blocks of an incremental backup to the restore location.

  • Use the Setup passwordless SSH? switch to specify if you want to create SSH certificates to allow passwordless logins between the BART server and the target host for restore.

On the Advanced tab, specify your preferences for advanced options for restoring the backup:

  • Use the Copy WALs to restore path? switch to specify if you want to copy WAL files to the restore path.

  • Use the Point in time recovery switch to specify if you want point-in-time recovery.

  • Use the Timeline ID field to specify the timeline ID to use for replaying the archived WAL files for point-in-time recovery.

  • Use the Transaction ID (XID) field to specify the transaction ID for point-in-time recovery.

  • Use the Timestamp field to specify the timestamp to use for restore.

Note

You can specify either Transaction ID or Timestamp for the point-in-time recovery.

Use the Notifications tab to specify the email notification settings for restoring the backup:

  • Use the Send the notifications field to specify when you want to send the email notifications.

  • Use the Email group field to specify the email group to receive the email notification.