| PostgreSQL 8.3.23 Documentation | ||||
|---|---|---|---|---|
| Prev | Fast Backward | Appendix F. Additional Supplied Modules | Fast Forward | Next |
pg_standby supports creation of a "warm standby" database server. It is designed to be a production-ready program, as well as a customizable template should you require specific modifications.
pg_standby is designed to be a waiting restore_command, which is needed to turn a standard archive recovery into a warm standby operation. Other configuration is required as well, all of which is described in the main server manual (see Section 24.4).
pg_standby features include:
Supports copy or link for restoring WAL files
Written in C, so very portable and easy to install
Easy-to-modify source code, with specifically designated sections to modify for your own needs
Already tested on Linux and Windows
To configure a standby server to use pg_standby, put this into its recovery.conf configuration file:
restore_command = 'pg_standby archiveDir %f %p %r'
where archiveDir is the directory from which WAL segment files should be restored.
The full syntax of pg_standby's command line is
pg_standby [ option ... ] archivelocation nextwalfile xlogfilepath [ restartwalfile ]
When used within restore_command, the %f and %p macros should be specified for nextwalfile and xlogfilepath respectively, to provide the actual file and path required for the restore.
If restartwalfile is specified, normally by using the %r macro, then all WAL files logically preceding this file will be removed from archivelocation. This minimizes the number of files that need to be retained, while preserving crash-restart capability. Use of this parameter is appropriate if the archivelocation is a transient staging area for this particular standby server, but not when the archivelocation is intended as a long-term WAL archive area.
pg_standby assumes that archivelocation is a directory readable by the server-owning user. If restartwalfile (or -k) is specified, the archivelocation directory must be writable too.
Table F-26. pg_standby options
| Option | Default | Description |
|---|---|---|
| -c | yes | Use cp or copy command to restore WAL files from archive. |
| -d | no | Print lots of debug logging output on stderr. |
| -k numfiles | 0 | Remove files from archivelocation so that no more than this many WAL files before the current one are kept in the archive. Zero (the default) means not to remove any files from archivelocation. This parameter will be silently ignored if restartwalfile is specified, since that specification method is more accurate in determining the correct archive cut-off point. Use of this parameter is deprecated as of PostgreSQL 8.3; it is safer and more efficient to specify a restartwalfile parameter. A too small setting could result in removal of files that are still needed for a restart of the standby server, while a too large setting wastes archive space. |
| -l | no | Use ln command to restore WAL files from archive. Link is more efficient than copy, but the default is copy since link will not work in all scenarios. On Windows, this option uses the mklink command to provide a file-to-file symbolic link. -l will not work on versions of Windows prior to Vista. |
| -r maxretries | 3 | Set the maximum number of times to retry the copy or link command if it fails. After each failure, we wait for sleeptime * num_retries so that the wait time increases progressively. So by default, we will wait 5 secs, 10 secs, then 15 secs before reporting the failure back to the standby server. This will be interpreted as end of recovery and the standby will come up fully as a result. |
| -s sleeptime | 5 | Set the number of seconds (up to 60) to sleep between tests to see if the WAL file to be restored is available in the archive yet. The default setting is not necessarily recommended; consult Section 24.4 for discussion. |
| -t triggerfile | none | Specify a trigger file whose presence should cause recovery to end whether or not the next WAL file is available. It is recommended that you use a structured filename to avoid confusion as to which server is being triggered when multiple servers exist on the same system; for example /tmp/pgsql.trigger.5432. |
| -w maxwaittime | 0 | Set the maximum number of seconds to wait for the next WAL file, after which recovery will end and the standby will come up. A setting of zero (the default) means wait forever. The default setting is not necessarily recommended; consult Section 24.4 for discussion. |
| Caution |
|
It is critical the trigger file be created with permissions allowing the postgres process to remove the file. Generally this is best done by creating the file from the postgres user account. Failure to do so will prevent completion of WAL file recovery and the server from coming back online successfully. |
Note: --help is not supported since pg_standby is not intended for interactive use, except during development and testing.
On Linux or Unix systems, you might use:
archive_command = 'cp %p .../archive/%f' restore_command = 'pg_standby -l -d -s 2 -t /tmp/pgsql.trigger.5442 .../archive %f %p %r 2>>standby.log'
where the archive directory is physically located on the standby server, so that the archive_command is accessing it across NFS, but the files are local to the standby (enabling use of ln). This will:
use the ln command to restore WAL files from archive
produce debugging output in standby.log
sleep for 2 seconds between checks for next WAL file availability
stop waiting only when a trigger file called /tmp/pgsql.trigger.5442 appears
remove no-longer-needed files from the archive directory
On Windows, you might use:
archive_command = 'copy %p ...\\archive\\%f' restore_command = 'pg_standby -d -s 5 -t C:\pgsql.trigger.5442 ...\archive %f %p %r 2>>standby.log'
Note that backslashes need to be doubled in the archive_command, but not in the restore_command. This will:
use the copy command to restore WAL files from archive
produce debugging output in standby.log
sleep for 5 seconds between checks for next WAL file availability
stop waiting only when a trigger file called C:\pgsql.trigger.5442 appears
remove no-longer-needed files from the archive directory
Since the Windows example uses copy at both ends, either or both servers might be accessing the archive directory across the network.
pg_standby is designed to work with PostgreSQL 8.2 and later.
PostgreSQL 8.3 provides the %r macro, which is designed to let pg_standby know the last file it needs to keep. With PostgreSQL 8.2, the -k option must be used if archive cleanup is required. This option remains available in 8.3, but its use is deprecated.
Simon Riggs <simon@2ndquadrant.com>