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

   1
   2 pg_resetwal
   3
   4    pg_resetwal — reset the write-ahead log and other control information
   5    of a PostgreSQL database cluster
   6
   7 Synopsis
   8
   9    pg_resetwal [ -f | --force ] [ -n | --dry-run ] [option...] [ -D |
  10    --pgdata ]datadir
  11
  12 Description
  13
  14    pg_resetwal clears the write-ahead log (WAL) and optionally resets some
  15    other control information stored in the pg_control file. This function
  16    is sometimes needed if these files have become corrupted. It should be
  17    used only as a last resort, when the server will not start due to such
  18    corruption.
  19
  20    Some options, such as --wal-segsize (see below), can also be used to
  21    modify certain global settings of a database cluster without the need
  22    to rerun initdb. This can be done safely on an otherwise sound database
  23    cluster, if none of the dangerous modes mentioned below are used.
  24
  25    If pg_resetwal is used on a data directory where the server has been
  26    cleanly shut down and the control file is sound, then it will have no
  27    effect on the contents of the database system, except that no longer
  28    used WAL files are cleared away. Any other use is potentially dangerous
  29    and must be done with great care. pg_resetwal will require the -f
  30    (force) option to be specified before working on a data directory in an
  31    unclean shutdown state or with a corrupted control file.
  32
  33    After running this command on a data directory with corrupted WAL or a
  34    corrupted control file, it should be possible to start the server, but
  35    bear in mind that the database might contain inconsistent data due to
  36    partially-committed transactions. You should immediately dump your
  37    data, run initdb, and restore. After restore, check for inconsistencies
  38    and repair as needed.
  39
  40    If pg_resetwal complains that it cannot determine valid data for
  41    pg_control, you can force it to proceed anyway by specifying the -f
  42    (force) option. In this case plausible values will be substituted for
  43    the missing data. Most of the fields can be expected to match, but
  44    manual assistance might be needed for the next OID, next transaction ID
  45    and epoch, next multitransaction ID and offset, and WAL starting
  46    location fields. These fields can be set using the options discussed
  47    below. If you are not able to determine correct values for all these
  48    fields, -f can still be used, but the recovered database must be
  49    treated with even more suspicion than usual: an immediate dump and
  50    restore is imperative. Do not execute any data-modifying operations in
  51    the database before you dump, as any such action is likely to make the
  52    corruption worse.
  53
  54    This utility can only be run by the user who installed the server,
  55    because it requires read/write access to the data directory.
  56
  57 Options
  58
  59    datadir
  60           -D datadir
  61           --pgdata=datadir
  62           Specifies the location of the database directory. For safety
  63           reasons, you must specify the data directory on the command
  64           line. pg_resetwal does not use the environment variable PGDATA.
  65
  66    -f
  67           --force
  68           Force pg_resetwal to proceed even in situations where it could
  69           be dangerous, as explained above. Specifically, this option is
  70           required to proceed if the server had not been cleanly shut down
  71           or if pg_resetwal cannot determine valid data for pg_control.
  72
  73    -n
  74           --dry-run
  75           The -n/--dry-run option instructs pg_resetwal to print the
  76           values reconstructed from pg_control and values about to be
  77           changed, and then exit without modifying anything. This is
  78           mainly a debugging tool, but can be useful as a sanity check
  79           before allowing pg_resetwal to proceed for real.
  80
  81    -V
  82           --version
  83           Display version information, then exit.
  84
  85    -?
  86           --help
  87           Show help, then exit.
  88
  89    The following options are only needed when pg_resetwal is unable to
  90    determine appropriate values by reading pg_control. Safe values can be
  91    determined as described below. For values that take numeric arguments,
  92    hexadecimal values can be specified by using the prefix 0x. Note that
  93    these instructions only apply with the standard block size of 8 kB.
  94
  95    -c xid,xid
  96           --commit-timestamp-ids=xid,xid
  97           Manually set the oldest and newest transaction IDs for which the
  98           commit time can be retrieved.
  99
 100           A safe value for the oldest transaction ID for which the commit
 101           time can be retrieved (first part) can be determined by looking
 102           for the numerically smallest file name in the directory
 103           pg_commit_ts under the data directory. Conversely, a safe value
 104           for the newest transaction ID for which the commit time can be
 105           retrieved (second part) can be determined by looking for the
 106           numerically greatest file name in the same directory. The file
 107           names are in hexadecimal.
 108
 109    -e xid_epoch
 110           --epoch=xid_epoch
 111           Manually set the next transaction ID's epoch.
 112
 113           The transaction ID epoch is not actually stored anywhere in the
 114           database except in the field that is set by pg_resetwal, so any
 115           value will work so far as the database itself is concerned. You
 116           might need to adjust this value to ensure that replication
 117           systems such as Slony-I and Skytools work correctly — if so, an
 118           appropriate value should be obtainable from the state of the
 119           downstream replicated database.
 120
 121    -l walfile
 122           --next-wal-file=walfile
 123           Manually set the WAL starting location by specifying the name of
 124           the next WAL segment file.
 125
 126           The name of next WAL segment file should be larger than any WAL
 127           segment file name currently existing in the directory pg_wal
 128           under the data directory. These names are also in hexadecimal
 129           and have three parts. The first part is the “timeline ID” and
 130           should usually be kept the same. For example, if
 131           00000001000000320000004A is the largest entry in pg_wal, use -l
 132           00000001000000320000004B or higher.
 133
 134           Note that when using nondefault WAL segment sizes, the numbers
 135           in the WAL file names are different from the LSNs that are
 136           reported by system functions and system views. This option takes
 137           a WAL file name, not an LSN.
 138
 139 Note
 140
 141           pg_resetwal itself looks at the files in pg_wal and chooses a
 142           default -l setting beyond the last existing file name.
 143           Therefore, manual adjustment of -l should only be needed if you
 144           are aware of WAL segment files that are not currently present in
 145           pg_wal, such as entries in an offline archive; or if the
 146           contents of pg_wal have been lost entirely.
 147
 148    -m mxid,mxid
 149           --multixact-ids=mxid,mxid
 150           Manually set the next and oldest multitransaction ID.
 151
 152           A safe value for the next multitransaction ID (first part) can
 153           be determined by looking for the numerically largest file name
 154           in the directory pg_multixact/offsets under the data directory,
 155           adding one, and then multiplying by 65536 (0x10000). Conversely,
 156           a safe value for the oldest multitransaction ID (second part of
 157           -m) can be determined by looking for the numerically smallest
 158           file name in the same directory and multiplying by 65536. The
 159           file names are in hexadecimal, so the easiest way to do this is
 160           to specify the option value in hexadecimal and append four
 161           zeroes.
 162
 163    -o oid
 164           --next-oid=oid
 165           Manually set the next OID.
 166
 167           There is no comparably easy way to determine a next OID that's
 168           beyond the largest one in the database, but fortunately it is
 169           not critical to get the next-OID setting right.
 170
 171    -O mxoff
 172           --multixact-offset=mxoff
 173           Manually set the next multitransaction offset.
 174
 175           A safe value can be determined by looking for the numerically
 176           largest file name in the directory pg_multixact/members under
 177           the data directory, adding one, and then multiplying by 52352
 178           (0xCC80). The file names are in hexadecimal. There is no simple
 179           recipe such as the ones for other options of appending zeroes.
 180
 181    -u xid
 182           --oldest-transaction-id=xid
 183           Manually set the oldest unfrozen transaction ID.
 184
 185           A safe value can be determined by looking for the numerically
 186           smallest file name in the directory pg_xact under the data
 187           directory and then multiplying by 1048576 (0x100000). Note that
 188           the file names are in hexadecimal. It is usually easiest to
 189           specify the option value in hexadecimal too. For example, if
 190           0007 is the smallest entry in pg_xact, -u 0x700000 will work
 191           (five trailing zeroes provide the proper multiplier).
 192
 193    -x xid
 194           --next-transaction-id=xid
 195           Manually set the next transaction ID.
 196
 197           A safe value can be determined by looking for the numerically
 198           largest file name in the directory pg_xact under the data
 199           directory, adding one, and then multiplying by 1048576
 200           (0x100000). Note that the file names are in hexadecimal. It is
 201           usually easiest to specify the option value in hexadecimal too.
 202           For example, if 0011 is the largest entry in pg_xact, -x
 203           0x1200000 will work (five trailing zeroes provide the proper
 204           multiplier).
 205
 206    --char-signedness=option
 207           Manually set the default char signedness. Possible values are
 208           signed and unsigned.
 209
 210           For a database cluster that pg_upgrade upgraded from a
 211           PostgreSQL version before 18, the safe value would be the
 212           default char signedness of the platform that ran the cluster
 213           before that upgrade. For all other clusters, signed would be the
 214           safe value. However, this option is exclusively for use with
 215           pg_upgrade and should not normally be used manually.
 216
 217    --wal-segsize=wal_segment_size
 218           Set the new WAL segment size, in megabytes. The value must be
 219           set to a power of 2 between 1 and 1024 (megabytes). See the same
 220           option of initdb for more information.
 221
 222           This option can also be used to change the WAL segment size of
 223           an existing database cluster, avoiding the need to re-initdb.
 224
 225 Note
 226
 227           While pg_resetwal will set the WAL starting address beyond the
 228           latest existing WAL segment file, some segment size changes can
 229           cause previous WAL file names to be reused. It is recommended to
 230           use -l together with this option to manually set the WAL
 231           starting address if WAL file name overlap will cause problems
 232           with your archiving strategy.
 233
 234 Environment
 235
 236    PG_COLOR
 237           Specifies whether to use color in diagnostic messages. Possible
 238           values are always, auto and never.
 239
 240 Notes
 241
 242    This command must not be used when the server is running. pg_resetwal
 243    will refuse to start up if it finds a server lock file in the data
 244    directory. If the server crashed then a lock file might have been left
 245    behind; in that case you can remove the lock file to allow pg_resetwal
 246    to run. But before you do so, make doubly certain that there is no
 247    server process still alive.
 248
 249    pg_resetwal works only with servers of the same major version.
 250
 251 See Also
 252
 253    pg_controldata