qhb_checksums

qhb_checksums — enable, disable or check data checksums in a QHB database cluster

Synopsis

qhb_checksums [option...] [[ -D | --pgdata ]datadir]

qhb_checksums checks, enables or disables data checksums in a QHB cluster. The server must be shut down cleanly before running qhb_checksums. When verifying checksums, the exit status is zero if there are no checksum errors, and nonzero if at least one checksum failure is detected. When enabling or disabling checksums, the exit status is nonzero if the operation failed.

Every table file has a header; by default, its checksum field is 0, and "checksum version" in shared file ControlFile is 0. At the first run you should enable checksums using --enable option which will set checksum version to 1 and change checksum field in every header of the database table files (global, base, pg_tblspc directories). If it is necessary to validate checksums in files, the program memorizes checksum value from file, resets it, reads a new value, then compares it to the old one and puts this old value back (if old value disagrees with evaluated value, an error will erase and its location will be printed). If it is necessary to disable checksums, qhb_checksums changes checksum version value to 0 and does nothing with table files.

When verifying checksums, every file in the cluster is scanned. When enabling checksums, each relation file block with a changed checksum is rewritten in-place. Disabling checksums only updates the file pg_control.

Options

The following command-line options are available:

-D directory
--pgdata=directory
Specifies the directory where the database cluster is stored.

-c
--check
Checks checksums. This is the default mode if nothing else is specified.

-d
--disable
Disables checksums.

-e
--enable
Enables checksums.

-f filenode
--filenode=filenode
Only validate checksums in the relation with filenode filenode.

-N
--no-sync
By default, qhb_checksums will wait for all files to be written safely to disk. This option causes qhb_checksums to return without waiting, which is faster, but means that a subsequent operating system crash can leave the updated data directory corrupt. Generally, this option is useful for testing but should not be used on a production installation. This option has no effect when using --check.

-P
--progress
Enable progress reporting. Turning this on will deliver a progress report while checking or enabling checksums.

-v
--verbose
Enable verbose output. Lists all checked files.

-V
--version
Print the qhb_checksums version and exit.

-h
--help
Show help about qhb_checksums command line arguments, and exit.

Environment

PGDATA
Specifies the directory where the database cluster is stored; can be overridden using the -D option.

PG_COLOR
Specifies whether to use color in diagnostic messages. Possible values are always, auto and never.

Notes

Enabling checksums in a large cluster can potentially take a long time. During this operation, the cluster or other programs that write to the data directory must not be started or else data loss may occur.

When using a replication setup with tools which perform direct copies of relation file blocks (for example qhb_rewind), enabling or disabling checksums can lead to page corruptions in the shape of incorrect checksums if the operation is not done consistently across all nodes. When enabling or disabling checksums in a replication setup, it is thus recommended to stop all the clusters before switching them all consistently. Destroying all standbys, performing the operation on the primary and finally recreating the standbys from scratch is also safe.

If qhb_checksums is aborted or killed while enabling or disabling checksums, the cluster's data checksum configuration remains unchanged, and qhb_checksums can be re-run to perform the same operation.

Error Handling

Error Possibly encrypted block appears either during file encrypting or when it is severely corrupted, which means MismatchBlockChecksum.

Examples

Checksums enabling; at the end statistics is printed, including the number of treated blocks and files. Any failure results in program halting and exiting with exit code 1:

qhb_checksums -e

Checking the checksums that have been enabled already; statistics and failure behavior is similar to --enable:

qhb_checksums -с

Disabling the checksums in /global/pg_control regardless of any failures except for Permission denied:

qhb_checksums -d

Note
--enable, --check, and --disable are the main three arguments which following switches can be applied at:

--verbose for printing debugging output;

--no-sync for disabling flushing changes to disk;

--progress for progress reporting.