1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
'\" t
.\" Title: pg_checksums
.\" Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" Date: 2024
.\" Manual: PostgreSQL 15.7 Documentation
.\" Source: PostgreSQL 15.7
.\" Language: English
.\"
.TH "PG_CHECKSUMS" "1" "2024" "PostgreSQL 15.7" "PostgreSQL 15.7 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\&.
|
