Running the BART WAL Scanner

The BART WAL scanner is used to process each WAL file to find and record modified blocks in a corresponding MBM file. As a BART account user, use the BART WAL scanner to invoke the bart-scanner program located in the <BART_HOME>/bin directory.

For detailed information about the WAL scanner and its usage, see the EDB Postgres Backup and Recovery User Guide available at the EDB website.

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.

The following table describes the VERIFY-CHKSUM options.

Options

Description

-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 archived_wals directory as specified in the the archive_path parameter in the bart.cfg file contains the MBM files.

wal_file

Specifies the full directory path to a WAL file to be scanned. The archive path directory 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 code sample demonstrates starting 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 sample 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 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 code sample demonstrates invoking 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$

The following command demonstrates scanning an individual WAL file:

-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 shown in the following code sample:

-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