begriffs open source - ai-pg/blob - full-docs/txt/app-pgverifybackup.txt

   1
   2 pg_verifybackup
   3
   4    pg_verifybackup — verify the integrity of a base backup of a PostgreSQL
   5    cluster
   6
   7 Synopsis
   8
   9    pg_verifybackup [option...]
  10
  11 Description
  12
  13    pg_verifybackup is used to check the integrity of a database cluster
  14    backup taken using pg_basebackup against a backup_manifest generated by
  15    the server at the time of the backup. The backup may be stored either
  16    in the "plain" or the "tar" format; this includes tar-format backups
  17    compressed with any algorithm supported by pg_basebackup. However, at
  18    present, WAL verification is supported only for plain-format backups.
  19    Therefore, if the backup is stored in tar-format, the -n,
  20    --no-parse-wal option should be used.
  21
  22    It is important to note that the validation which is performed by
  23    pg_verifybackup does not and cannot include every check which will be
  24    performed by a running server when attempting to make use of the
  25    backup. Even if you use this tool, you should still perform test
  26    restores and verify that the resulting databases work as expected and
  27    that they appear to contain the correct data. However, pg_verifybackup
  28    can detect many problems that commonly occur due to storage problems or
  29    user error.
  30
  31    Backup verification proceeds in four stages. First, pg_verifybackup
  32    reads the backup_manifest file. If that file does not exist, cannot be
  33    read, is malformed, fails to match the system identifier with
  34    pg_control of the backup directory or fails verification against its
  35    own internal checksum, pg_verifybackup will terminate with a fatal
  36    error.
  37
  38    Second, pg_verifybackup will attempt to verify that the data files
  39    currently stored on disk are exactly the same as the data files which
  40    the server intended to send, with some exceptions that are described
  41    below. Extra and missing files will be detected, with a few exceptions.
  42    This step will ignore the presence or absence of, or any modifications
  43    to, postgresql.auto.conf, standby.signal, and recovery.signal, because
  44    it is expected that these files may have been created or modified as
  45    part of the process of taking the backup. It also won't complain about
  46    a backup_manifest file in the target directory or about anything inside
  47    pg_wal, even though these files won't be listed in the backup manifest.
  48    Only files are checked; the presence or absence of directories is not
  49    verified, except indirectly: if a directory is missing, any files it
  50    should have contained will necessarily also be missing.
  51
  52    Next, pg_verifybackup will checksum all the files, compare the
  53    checksums against the values in the manifest, and emit errors for any
  54    files for which the computed checksum does not match the checksum
  55    stored in the manifest. This step is not performed for any files which
  56    produced errors in the previous step, since they are already known to
  57    have problems. Files which were ignored in the previous step are also
  58    ignored in this step.
  59
  60    Finally, pg_verifybackup will use the manifest to verify that the
  61    write-ahead log records which will be needed to recover the backup are
  62    present and that they can be read and parsed. The backup_manifest
  63    contains information about which write-ahead log records will be
  64    needed, and pg_verifybackup will use that information to invoke
  65    pg_waldump to parse those write-ahead log records. The --quiet flag
  66    will be used, so that pg_waldump will only report errors, without
  67    producing any other output. While this level of verification is
  68    sufficient to detect obvious problems such as a missing file or one
  69    whose internal checksums do not match, they aren't extensive enough to
  70    detect every possible problem that might occur when attempting to
  71    recover. For instance, a server bug that produces write-ahead log
  72    records that have the correct checksums but specify nonsensical actions
  73    can't be detected by this method.
  74
  75    Note that if extra WAL files which are not required to recover the
  76    backup are present, they will not be checked by this tool, although a
  77    separate invocation of pg_waldump could be used for that purpose. Also
  78    note that WAL verification is version-specific: you must use the
  79    version of pg_verifybackup, and thus of pg_waldump, which pertains to
  80    the backup being checked. In contrast, the data file integrity checks
  81    should work with any version of the server that generates a
  82    backup_manifest file.
  83
  84 Options
  85
  86    pg_verifybackup accepts the following command-line arguments:
  87
  88    -e
  89           --exit-on-error
  90           Exit as soon as a problem with the backup is detected. If this
  91           option is not specified, pg_verifybackup will continue checking
  92           the backup even after a problem has been detected, and will
  93           report all problems detected as errors.
  94
  95    -F format
  96           --format=format
  97           Specifies the format of the backup. format can be one of the
  98           following:
  99
 100         p
 101                 plain
 102                 Backup consists of plain files with the same layout as the
 103                 source server's data directory and tablespaces.
 104
 105         t
 106                 tar
 107                 Backup consists of tar files, which may be compressed. A
 108                 valid backup includes the main data directory in a file
 109                 named base.tar, the WAL files in pg_wal.tar, and separate
 110                 tar files for each tablespace, named after the
 111                 tablespace's OID. If the backup is compressed, the
 112                 relevant compression extension is added to the end of each
 113                 file name.
 114
 115    -i path
 116           --ignore=path
 117           Ignore the specified file or directory, which should be
 118           expressed as a relative path name, when comparing the list of
 119           data files actually present in the backup to those listed in the
 120           backup_manifest file. If a directory is specified, this option
 121           affects the entire subtree rooted at that location. Complaints
 122           about extra files, missing files, file size differences, or
 123           checksum mismatches will be suppressed if the relative path name
 124           matches the specified path name. This option can be specified
 125           multiple times.
 126
 127    -m path
 128           --manifest-path=path
 129           Use the manifest file at the specified path, rather than one
 130           located in the root of the backup directory.
 131
 132    -n
 133           --no-parse-wal
 134           Don't attempt to parse write-ahead log data that will be needed
 135           to recover from this backup.
 136
 137    -P
 138           --progress
 139           Enable progress reporting. Turning this on will deliver a
 140           progress report while verifying checksums.
 141
 142           This option cannot be used together with the option --quiet.
 143
 144    -q
 145           --quiet
 146           Don't print anything when a backup is successfully verified.
 147
 148    -s
 149           --skip-checksums
 150           Do not verify data file checksums. The presence or absence of
 151           files and the sizes of those files will still be checked. This
 152           is much faster, because the files themselves do not need to be
 153           read.
 154
 155    -w path
 156           --wal-directory=path
 157           Try to parse WAL files stored in the specified directory, rather
 158           than in pg_wal. This may be useful if the backup is stored in a
 159           separate location from the WAL archive.
 160
 161    Other options are also available:
 162
 163    -V
 164           --version
 165           Print the pg_verifybackup version and exit.
 166
 167    -?
 168           --help
 169           Show help about pg_verifybackup command line arguments, and
 170           exit.
 171
 172 Examples
 173
 174    To create a base backup of the server at mydbserver and verify the
 175    integrity of the backup:
 176 $ pg_basebackup -h mydbserver -D /usr/local/pgsql/data
 177 $ pg_verifybackup /usr/local/pgsql/data
 178
 179    To create a base backup of the server at mydbserver, move the manifest
 180    somewhere outside the backup directory, and verify the backup:
 181 $ pg_basebackup -h mydbserver -D /usr/local/pgsql/backup1234
 182 $ mv /usr/local/pgsql/backup1234/backup_manifest /my/secure/location/backup_mani
 183 fest.1234
 184 $ pg_verifybackup -m /my/secure/location/backup_manifest.1234 /usr/local/pgsql/b
 185 ackup1234
 186
 187    To verify a backup while ignoring a file that was added manually to the
 188    backup directory, and also skipping checksum verification:
 189 $ pg_basebackup -h mydbserver -D /usr/local/pgsql/data
 190 $ edit /usr/local/pgsql/data/note.to.self
 191 $ pg_verifybackup --ignore=note.to.self --skip-checksums /usr/local/pgsql/data
 192
 193 See Also
 194
 195    pg_basebackup