'\" t
.\"     Title: pg_checksums
.\"    Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2024
.\"    Manual: PostgreSQL 16.3 Documentation
.\"    Source: PostgreSQL 16.3
.\"  Language: English
.\"
.TH "PG_CHECKSUMS" "1" "2024" "PostgreSQL 16.3" "PostgreSQL 16.3 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\&.