Debian Codegraph @

doc/src/sgml/ref/pg_checksums.sgml

raw
1 <!--
2 doc/src/sgml/ref/pg_checksums.sgml
3 PostgreSQL documentation
4 -->
5
6 <refentry id="app-pgchecksums">
7 <indexterm zone="app-pgchecksums">
8 <primary>pg_checksums</primary>
9 </indexterm>
10
11 <refmeta>
12 <refentrytitle><application>pg_checksums</application></refentrytitle>
13 <manvolnum>1</manvolnum>
14 <refmiscinfo>Application</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18 <refname>pg_checksums</refname>
19 <refpurpose>enable, disable or check data checksums in a <productname>PostgreSQL</productname> database cluster</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23 <cmdsynopsis>
24 <command>pg_checksums</command>
25 <arg rep="repeat" choice="opt"><replaceable class="parameter">option</replaceable></arg>
26 <group choice="opt">
27 <group choice="opt">
28 <arg choice="plain"><option>-D</option></arg>
29 <arg choice="plain"><option>--pgdata</option></arg>
30 </group>
31 <replaceable class="parameter">datadir</replaceable>
32 </group>
33 </cmdsynopsis>
34 </refsynopsisdiv>
35
36 <refsect1 id="r1-app-pgchecksums-1">
37 <title>Description</title>
38 <para>
39 <application>pg_checksums</application> checks, enables or disables data
40 checksums in a <productname>PostgreSQL</productname> cluster. The server
41 must be shut down cleanly before running
42 <application>pg_checksums</application>. When verifying checksums, the exit
43 status is zero if there are no checksum errors, and nonzero if at least one
44 checksum failure is detected. When enabling or disabling checksums, the
45 exit status is nonzero if the operation failed.
46 </para>
47
48 <para>
49 When verifying checksums, every file in the cluster is scanned. When
50 enabling checksums, each relation file block with a changed checksum is
51 rewritten in-place.
52 Disabling checksums only updates the file <filename>pg_control</filename>.
53 </para>
54 </refsect1>
55
56 <refsect1>
57 <title>Options</title>
58
59 <para>
60 The following command-line options are available:
61
62 <variablelist>
63 <varlistentry>
64 <term><option>-D <replaceable>directory</replaceable></option></term>
65 <term><option>--pgdata=<replaceable>directory</replaceable></option></term>
66 <listitem>
67 <para>
68 Specifies the directory where the database cluster is stored.
69 </para>
70 </listitem>
71 </varlistentry>
72
73 <varlistentry>
74 <term><option>-c</option></term>
75 <term><option>--check</option></term>
76 <listitem>
77 <para>
78 Checks checksums. This is the default mode if nothing else is
79 specified.
80 </para>
81 </listitem>
82 </varlistentry>
83
84 <varlistentry>
85 <term><option>-d</option></term>
86 <term><option>--disable</option></term>
87 <listitem>
88 <para>
89 Disables checksums.
90 </para>
91 </listitem>
92 </varlistentry>
93
94 <varlistentry>
95 <term><option>-e</option></term>
96 <term><option>--enable</option></term>
97 <listitem>
98 <para>
99 Enables checksums.
100 </para>
101 </listitem>
102 </varlistentry>
103
104 <varlistentry>
105 <term><option>-f <replaceable>filenode</replaceable></option></term>
106 <term><option>--filenode=<replaceable>filenode</replaceable></option></term>
107 <listitem>
108 <para>
109 Only validate checksums in the relation with filenode
110 <replaceable>filenode</replaceable>.
111 </para>
112 </listitem>
113 </varlistentry>
114
115 <varlistentry>
116 <term><option>-N</option></term>
117 <term><option>--no-sync</option></term>
118 <listitem>
119 <para>
120 By default, <command>pg_checksums</command> will wait for all files
121 to be written safely to disk. This option causes
122 <command>pg_checksums</command> to return without waiting, which is
123 faster, but means that a subsequent operating system crash can leave
124 the updated data directory corrupt. Generally, this option is useful
125 for testing but should not be used on a production installation.
126 This option has no effect when using <literal>--check</literal>.
127 </para>
128 </listitem>
129 </varlistentry>
130
131 <varlistentry>
132 <term><option>-P</option></term>
133 <term><option>--progress</option></term>
134 <listitem>
135 <para>
136 Enable progress reporting. Turning this on will deliver a progress
137 report while checking or enabling checksums.
138 </para>
139 </listitem>
140 </varlistentry>
141
142 <varlistentry>
143 <term><option>--sync-method=<replaceable>method</replaceable></option></term>
144 <listitem>
145 <para>
146 When set to <literal>fsync</literal>, which is the default,
147 <command>pg_checksums</command> will recursively open and synchronize
148 all files in the data directory. The search for files will follow
149 symbolic links for the WAL directory and each configured tablespace.
150 </para>
151 <para>
152 On Linux, <literal>syncfs</literal> may be used instead to ask the
153 operating system to synchronize the whole file systems that contain the
154 data directory, the WAL files, and each tablespace. See
155 <xref linkend="guc-recovery-init-sync-method"/> for information about
156 the caveats to be aware of when using <literal>syncfs</literal>.
157 </para>
158 <para>
159 This option has no effect when <option>--no-sync</option> is used.
160 </para>
161 </listitem>
162 </varlistentry>
163
164 <varlistentry>
165 <term><option>-v</option></term>
166 <term><option>--verbose</option></term>
167 <listitem>
168 <para>
169 Enable verbose output. Lists all checked files.
170 </para>
171 </listitem>
172 </varlistentry>
173
174 <varlistentry>
175 <term><option>-V</option></term>
176 <term><option>--version</option></term>
177 <listitem>
178 <para>
179 Print the <application>pg_checksums</application> version and exit.
180 </para>
181 </listitem>
182 </varlistentry>
183
184 <varlistentry>
185 <term><option>-?</option></term>
186 <term><option>--help</option></term>
187 <listitem>
188 <para>
189 Show help about <application>pg_checksums</application> command line
190 arguments, and exit.
191 </para>
192 </listitem>
193 </varlistentry>
194 </variablelist>
195 </para>
196 </refsect1>
197
198 <refsect1>
199 <title>Environment</title>
200
201 <variablelist>
202 <varlistentry>
203 <term><envar>PGDATA</envar></term>
204
205 <listitem>
206 <para>
207 Specifies the directory where the database cluster is
208 stored; can be overridden using the <option>-D</option> option.
209 </para>
210 </listitem>
211 </varlistentry>
212
213 <varlistentry>
214 <term><envar>PG_COLOR</envar></term>
215 <listitem>
216 <para>
217 Specifies whether to use color in diagnostic messages. Possible values
218 are <literal>always</literal>, <literal>auto</literal> and
219 <literal>never</literal>.
220 </para>
221 </listitem>
222 </varlistentry>
223 </variablelist>
224 </refsect1>
225
226 <refsect1>
227 <title>Notes</title>
228 <para>
229 Enabling checksums in a large cluster can potentially take a long time.
230 During this operation, the cluster or other programs that write to the
231 data directory must not be started or else data loss may occur.
232 </para>
233 <para>
234 When using a replication setup with tools which perform direct copies
235 of relation file blocks (for example <xref linkend="app-pgrewind"/>),
236 enabling or disabling checksums can lead to page corruptions in the
237 shape of incorrect checksums if the operation is not done consistently
238 across all nodes. When enabling or disabling checksums in a replication
239 setup, it is thus recommended to stop all the clusters before switching
240 them all consistently. Destroying all standbys, performing the operation
241 on the primary and finally recreating the standbys from scratch is also
242 safe.
243 </para>
244 <para>
245 If <application>pg_checksums</application> is aborted or killed while
246 enabling or disabling checksums, the cluster's data checksum configuration
247 remains unchanged, and <application>pg_checksums</application> can be
248 re-run to perform the same operation.
249 </para>
250 </refsect1>
251 </refentry>