begriffs open source - ai-pg/blob - full-docs/man1/pg_checksums.1

   1 '\" t
   2 .\"     Title: pg_checksums
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "PG_CHECKSUMS" "1" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 pg_checksums \- enable, disable or check data checksums in a PostgreSQL database cluster
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBpg_checksums\fR\ 'u
  34 \fBpg_checksums\fR [\fIoption\fR...] [[\fB\-D\fR | \fB\-\-pgdata\fR]\fIdatadir\fR]
  35 .SH "DESCRIPTION"
  36 .PP
  37 pg_checksums
  38 checks, enables or disables data checksums in a
  39 PostgreSQL
  40 cluster\&. The server must be shut down cleanly before running
  41 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\&.
  42 .PP
  43 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
  44 pg_control\&.
  45 .SH "OPTIONS"
  46 .PP
  47 The following command\-line options are available:
  48 .PP
  49 \fB\-D \fR\fB\fIdirectory\fR\fR
  50 .br
  51 \fB\-\-pgdata=\fR\fB\fIdirectory\fR\fR
  52 .RS 4
  53 Specifies the directory where the database cluster is stored\&.
  54 .RE
  55 .PP
  56 \fB\-c\fR
  57 .br
  58 \fB\-\-check\fR
  59 .RS 4
  60 Checks checksums\&. This is the default mode if nothing else is specified\&.
  61 .RE
  62 .PP
  63 \fB\-d\fR
  64 .br
  65 \fB\-\-disable\fR
  66 .RS 4
  67 Disables checksums\&.
  68 .RE
  69 .PP
  70 \fB\-e\fR
  71 .br
  72 \fB\-\-enable\fR
  73 .RS 4
  74 Enables checksums\&.
  75 .RE
  76 .PP
  77 \fB\-f \fR\fB\fIfilenode\fR\fR
  78 .br
  79 \fB\-\-filenode=\fR\fB\fIfilenode\fR\fR
  80 .RS 4
  81 Only validate checksums in the relation with filenode
  82 \fIfilenode\fR\&.
  83 .RE
  84 .PP
  85 \fB\-N\fR
  86 .br
  87 \fB\-\-no\-sync\fR
  88 .RS 4
  89 By default,
  90 \fBpg_checksums\fR
  91 will wait for all files to be written safely to disk\&. This option causes
  92 \fBpg_checksums\fR
  93 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
  94 \-\-check\&.
  95 .RE
  96 .PP
  97 \fB\-P\fR
  98 .br
  99 \fB\-\-progress\fR
 100 .RS 4
 101 Enable progress reporting\&. Turning this on will deliver a progress report while checking or enabling checksums\&.
 102 .RE
 103 .PP
 104 \fB\-\-sync\-method=\fR\fB\fImethod\fR\fR
 105 .RS 4
 106 When set to
 107 fsync, which is the default,
 108 \fBpg_checksums\fR
 109 will recursively open and synchronize all files in the data directory\&. The search for files will follow symbolic links for the WAL directory and each configured tablespace\&.
 110 .sp
 111 On Linux,
 112 syncfs
 113 may be used instead to ask the operating system to synchronize the whole file systems that contain the data directory, the WAL files, and each tablespace\&. See
 114 recovery_init_sync_method
 115 for information about the caveats to be aware of when using
 116 syncfs\&.
 117 .sp
 118 This option has no effect when
 119 \fB\-\-no\-sync\fR
 120 is used\&.
 121 .RE
 122 .PP
 123 \fB\-v\fR
 124 .br
 125 \fB\-\-verbose\fR
 126 .RS 4
 127 Enable verbose output\&. Lists all checked files\&.
 128 .RE
 129 .PP
 130 \fB\-V\fR
 131 .br
 132 \fB\-\-version\fR
 133 .RS 4
 134 Print the
 135 pg_checksums
 136 version and exit\&.
 137 .RE
 138 .PP
 139 \fB\-?\fR
 140 .br
 141 \fB\-\-help\fR
 142 .RS 4
 143 Show help about
 144 pg_checksums
 145 command line arguments, and exit\&.
 146 .RE
 147 .SH "ENVIRONMENT"
 148 .PP
 149 \fBPGDATA\fR
 150 .RS 4
 151 Specifies the directory where the database cluster is stored; can be overridden using the
 152 \fB\-D\fR
 153 option\&.
 154 .RE
 155 .PP
 156 \fBPG_COLOR\fR
 157 .RS 4
 158 Specifies whether to use color in diagnostic messages\&. Possible values are
 159 always,
 160 auto
 161 and
 162 never\&.
 163 .RE
 164 .SH "NOTES"
 165 .PP
 166 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\&.
 167 .PP
 168 When using a replication setup with tools which perform direct copies of relation file blocks (for example
 169 \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\&.
 170 .PP
 171 If
 172 pg_checksums
 173 is aborted or killed while enabling or disabling checksums, the cluster\*(Aqs data checksum configuration remains unchanged, and
 174 pg_checksums
 175 can be re\-run to perform the same operation\&.