Running the BART WAL Scanner

Use the BART WAL scanner to invoke the bart-scanner program located in the <BART_HOME>/bin directory. When invoking the WAL scanner, the current user must be the BART user account. For detailed information about WAL scanner and its usage, see the Running the BART WAL Scanner section of EDB Postgres Backup and Recovery User Guide available at:

Syntax:

bart-scanner
[ -d ]
[ -c <config_file_path> ]
{ –h |
-v |
--daemon |
-p <mbm_file> |
<wal_file> |
RELOAD |
STOP }

When the bart-scanner program is invoked, it forks a separate process for each database server enabled with the allow_incremental_backups parameter.

The WAL scanner processes can run in either the foreground or background depending upon usage of the --daemon option:

  • If the --daemon option is specified, the WAL scanner process runs in the background. All output messages can be viewed in the BART log file.
  • If the --daemon option is omitted, the WAL scanner process runs in the foreground. All output messages can be viewed from the terminal running the program as well as in the BART log file.

Options

  • -h or --help
Displays general syntax and information on WAL scanner usage.
  • -v or --version
Displays the WAL scanner version information.
  • -d or --debug
Displays debugging output while executing the WAL scanner with any of its options.
  • -c <config_file_path> or --config-path <config_file_path>
Specifies <config_file_path> as the full directory path to a BART configuration file. Use this option if you do not want to use the default BART configuration file <BART_HOME>/etc/bart.cfg
  • --daemon
Runs the WAL scanner as a background process.
  • -p <mbm_file> or --print <mbm_file>
Specifies the full directory path to an MBM file whose content is to be printed. The archive path directory <backup_path>/<server_name>/archived_wals contains the MBM files.
  • wal_file

Specifies the full directory path to a WAL file to be scanned. The archive path directory <backup_path>/<server_name>/archived_wals contains the WAL files. Use it if a WAL file in the archive path is missing its MBM file.

This option is to be used for assisting the EnterpriseDB support team for debugging problems that may have been encountered.

  • RELOAD
    • Reloads the BART configuration file. The keyword RELOAD is case-insensitive.
    • The RELOAD option is useful if you make changes to the configuration file after the WAL scanner has been started. It will reload the configuration file and adjust the WAL scanners accordingly. For example, if a server section allowing incremental backups is removed from the BART configuration file, then the process attached to that server will stop. Similarly, if a server allowing incremental backups is added, a new WAL scanner process will be launched to scan the WAL files of that server.
  • STOP
Stops the WAL scanner. The keyword STOP is not case-sensitive.

Example

The following example shows the startup of the WAL scanner to run interactively. The WAL scanner begins scanning existing WAL files in the archive path that have not yet been scanned (that is, there is no corresponding MBM file for the WAL file):

-bash-4.2$ bart-scanner
INFO: process created for server 'acctg', pid = 5287
INFO: going to parse backlog of WALs, if any.
INFO: WAL file to be processed: 0000000100000000000000ED
INFO: WAL file to be processed: 0000000100000000000000EE
INFO: WAL file to be processed: 0000000100000000000000EF
INFO: WAL file to be processed: 0000000100000000000000F0
INFO: WAL file to be processed: 0000000100000000000000F1

The following code snippet is the content of the archive path showing the MBM files created for the WAL files. (The user name and group name of the files have been removed from the example to list the WAL files and MBM files in a more readable manner):

[root@localhost archived_wals]# pwd
/opt/backup/acctg/archived_wals
[root@localhost archived_wals]# ls -l
total 81944
-rw------- 1 ... ... 16777216 Dec 20 09:10 0000000100000000000000ED
-rw------- 1 ... ... 16777216 Dec 20 09:06 0000000100000000000000EE
-rw------- 1 ... ... 16777216 Dec 20 09:11 0000000100000000000000EF
-rw------- 1 ... ... 16777216 Dec 20 09:15 0000000100000000000000F0
-rw------- 1 ... ... 16777216 Dec 20 09:16 0000000100000000000000F1
-rw------- 1 ... ... 305      Dec 20 09:16 0000000100000000000000F1.00000028.backup
-rw-rw-r-- 1 ... ... 161      Dec 20 09:18
0000000100000000ED00002800000000EE000000.mbm
-rw-rw-r-- 1 ... ... 161      Dec 20 09:18
0000000100000000EE00002800000000EF000000.mbm
-rw-rw-r-- 1 ... ... 161      Dec 20 09:18
0000000100000000EF00002800000000F0000000.mbm
-rw-rw-r-- 1 ... ... 161      Dec 20 09:18
0000000100000000F000002800000000F1000000.mbm
-rw-rw-r-- 1 ... ... 161      Dec 20 09:18
0000000100000000F100002800000000F2000000.mbm

To stop the interactively running WAL scanner, either enter ctrl-C at the terminal running the WAL scanner or invoke the bart-scanner program from another terminal with the STOP option:

-bash-4.2$ bart-scanner STOP
-bash-4.2$

The terminal on which the WAL scanner was running interactively now appears as follows after it has been stopped:

-bash-4.2$ bart-scanner
INFO: process created for server 'acctg', pid = 5287
INFO: going to parse backlog of WALs, if any.
INFO: WAL file to be processed: 0000000100000000000000ED
INFO: WAL file to be processed: 0000000100000000000000EE
INFO: WAL file to be processed: 0000000100000000000000EF
INFO: WAL file to be processed: 0000000100000000000000F0
INFO: WAL file to be processed: 0000000100000000000000F1
INFO: bart-scanner stopped
-bash-4.2$

The following example shows how to invoke the WAL scanner to run as a background process with the --daemon option:

-bash-4.2$ bart-scanner --daemon
-bash-4.2$

The WAL scanner runs as a background process. There is also a separate background process for each database server that has been enabled for WAL scanning with the allow_incremental_backups parameter in the BART configuration file:

-bash-4.2$ ps -ef | grep bart
 enterpr+   4340  1   0   09:48   ? 00:00:00 bart-scanner --daemon
 enterpr+   4341 4340 0   09:48   ? 00:00:00 bart-scanner --daemon
 enterpr+   4415 3673 0   09:50     pts/0 00:00:00 grep   --color=auto bart

To stop the WAL scanner processes, invoke the WAL scanner with the stop option:

-bash-4.2$ bart-scanner STOP
-bash-4.2$

If it is necessary to individually scan a WAL file, this can be done as follows:

-bash-4.2$ bart-scanner /opt/backup/acctg/archived_wals/0000000100000000000000FF
-bash-4.2$

Should it be necessary to print the content of an MBM file for assisting the EnterpriseDB support team for debugging problems that may have been encountered, use the -p option to specify the file as in the following example:

-bash-4.2$ bart-scanner -p
/opt/backup/acctg/archived_wals/0000000100000000FF0000280000000100000000.mbm

Header:
Version: 1.0:90500:1.2.0
Scan Start: 2016-12-20 10:02:11 EST, Scan End: 2016-12-20 10:02:11 EST, Diff: 0 sec(s)
Start LSN: ff000028, End LSN: 100000000, TLI: 1
flags: 0, Check Sum: f9cfe66ae2569894d6746b61503a767d

Path: base/14845/16384
NodeTag: BLOCK_CHANGE
Relation: relPath base/14845/16384, isTSNode 0, Blocks
*.............................................................................
First modified block: 0
Total modified blocks: 1

Path: base/14845/16391
NodeTag: BLOCK_CHANGE
Relation: relPath base/14845/16391, isTSNode 0, Blocks
*..............................................................................
First modified block: 0
Total modified blocks: 1