diff options
Diffstat (limited to 'doc/src/sgml/man1/pg_checksums.1')
| -rw-r--r-- | doc/src/sgml/man1/pg_checksums.1 | 156 |
1 files changed, 156 insertions, 0 deletions
diff --git a/doc/src/sgml/man1/pg_checksums.1 b/doc/src/sgml/man1/pg_checksums.1 new file mode 100644 index 0000000..a20ca34 --- /dev/null +++ b/doc/src/sgml/man1/pg_checksums.1 @@ -0,0 +1,156 @@ +'\" t +.\" Title: pg_checksums +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "PG_CHECKSUMS" "1" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_checksums \- enable, disable or check data checksums in a PostgreSQL database cluster +.SH "SYNOPSIS" +.HP \w'\fBpg_checksums\fR\ 'u +\fBpg_checksums\fR [\fIoption\fR...] [[\fB\-D\fR | \fB\-\-pgdata\fR]\fIdatadir\fR] +.SH "DESCRIPTION" +.PP +pg_checksums +checks, enables or disables data checksums in a +PostgreSQL +cluster\&. The server must be shut down cleanly before running +pg_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\&. +.PP +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\&. +.SH "OPTIONS" +.PP +The following command\-line options are available: +.PP +\fB\-D \fR\fB\fIdirectory\fR\fR +.br +\fB\-\-pgdata=\fR\fB\fIdirectory\fR\fR +.RS 4 +Specifies the directory where the database cluster is stored\&. +.RE +.PP +\fB\-c\fR +.br +\fB\-\-check\fR +.RS 4 +Checks checksums\&. This is the default mode if nothing else is specified\&. +.RE +.PP +\fB\-d\fR +.br +\fB\-\-disable\fR +.RS 4 +Disables checksums\&. +.RE +.PP +\fB\-e\fR +.br +\fB\-\-enable\fR +.RS 4 +Enables checksums\&. +.RE +.PP +\fB\-f \fR\fB\fIfilenode\fR\fR +.br +\fB\-\-filenode=\fR\fB\fIfilenode\fR\fR +.RS 4 +Only validate checksums in the relation with filenode +\fIfilenode\fR\&. +.RE +.PP +\fB\-N\fR +.br +\fB\-\-no\-sync\fR +.RS 4 +By default, +\fBpg_checksums\fR +will wait for all files to be written safely to disk\&. This option causes +\fBpg_checksums\fR +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\&. +.RE +.PP +\fB\-P\fR +.br +\fB\-\-progress\fR +.RS 4 +Enable progress reporting\&. Turning this on will deliver a progress report while checking or enabling checksums\&. +.RE +.PP +\fB\-v\fR +.br +\fB\-\-verbose\fR +.RS 4 +Enable verbose output\&. Lists all checked files\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pg_checksums +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_checksums +command line arguments, and exit\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGDATA\fR +.RS 4 +Specifies the directory where the database cluster is stored; can be overridden using the +\fB\-D\fR +option\&. +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.SH "NOTES" +.PP +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\&. +.PP +When using a replication setup with tools which perform direct copies of relation file blocks (for example +\fBpg_rewind\fR(1)), 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\&. +.PP +If +pg_checksums +is aborted or killed while enabling or disabling checksums, the cluster\*(Aqs data checksum configuration remains unchanged, and +pg_checksums +can be re\-run to perform the same operation\&. |