From: Heikki Linnakangas Date: Fri, 9 Jan 2015 16:04:35 +0000 (+0200) Subject: Improve documentation X-Git-Url: http://git.postgresql.org/gitweb/static/gitweb.js?a=commitdiff_plain;h=aa690a76d6e24170cb4a35e625d27b0ea5ae9b39;p=users%2Fheikki%2Fpostgres.git Improve documentation --- diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml index 028d448011..7f22dd567c 100644 --- a/doc/src/sgml/ref/pg_rewind.sgml +++ b/doc/src/sgml/ref/pg_rewind.sgml @@ -21,13 +21,19 @@ PostgreSQL documentation - pg_rewind - --target-pgdata=DIRECTORY - - - - --dry-run - + pg_rewind + option + + + + + + directory + + + + + @@ -35,16 +41,33 @@ PostgreSQL documentation Description - pg_rewind is a tool for synchronizing a PostgreSQL data directory with another -PostgreSQL data directory that was forked from the first one. The result is -equivalent to rsyncing the first data directory (referred to as the old cluster -from now on) with the second one (the new cluster). The advantage of pg_rewind -over rsync is that pg_rewind uses the WAL to determine changed data blocks, -and does not require reading through all files in the cluster. That makes it -a lot faster when the database is large and only a small portion of it differs -between the clusters. + pg_rewind is a tool for synchronizing a PostgreSQL cluster + with another copy of the same cluster, after the cluster's timelines have + diverged. A typical scenario is to bring an old master server back online + after failover, as a standby that follows the new master. - + + + The result is equivalent to replacing the target data directory with the + source one. All files are copied, including configuration files. The advantage + of pg_rewind over restoring a base backup, or tools like rsync, is that + pg_rewind does not require reading through all unchanged files in the cluster. + That makes it a lot faster when the database is large and only a small portion + of it differs between the clusters. + + + + pg_rewind examines the timeline histories of the source and target clusters + to determine the point where they diverged, and expects to find WAL in the + target cluster's pg_xlog directory reaching all the way back to the point of + divergence. In the typical failover scenario where the target cluster was shut + down soon after the divergence, that is not a problem, but if the target cluster + had run for a long time after the divergence, the old WAL files might not be + present anymore. In that case, they can be manually copied from the WAL archive + to the pg_xlog directory. Fetching missing files from a WAL archive automatically + is currently not supported. + + Options @@ -53,49 +76,78 @@ between the clusters. pg_rewind accepts the following command-line arguments: + + + + + + This option specifies the target data directory that is synchronized with + the source. The target server must cleanly shut down before running + pg_rewind + + + + + + + + + Specifies a source data directory to synchronize the target with. When + --source-pgdata is used, the source server master be cleanly shut down. + + + + + + + + + Specifies a libpq connection string to connect to the source PostgreSQL + server to synchronize the target with. The server must be up and running, + and must not be in recovery mode. + + + + + + + + + + Do everything except actually modifying the target directory. + + + - enable verbose progress information + Enable verbose progress information - display version information, then exit + Display version information, then exit - show help, then exit + Show help, then exit - - Usage - - - - pg_rewind --target-pgdata=path --source-server=new server's conn string - -The contents of the old data directory will be overwritten with the new data -so that after pg_rewind finishes, the old data directory is equal to the new -one. - + Environment - pg_rewind expects to find all the necessary WAL files in the pg_xlog - directories of the clusters. This includes all the WAL on both clusters - starting from the last common checkpoint preceding the fork. Fetching - missing files from a WAL archive is currently not supported. However, you - can copy any missing files manually from the WAL archive to the pg_xlog - directory. + When --source-server option is used, pg_rewind also uses the + environment variables supported by libpq (see + ). @@ -103,35 +155,51 @@ one. Theory of operation - -The basic idea is to copy everything from the new cluster to the old cluster, -except for the blocks that we know to be the same. - -1. Scan the WAL log of the old cluster, starting from the last checkpoint before -the point where the new cluster's timeline history forked off from the old cluster. -For each WAL record, make a note of the data blocks that were touched. This yields -a list of all the data blocks that were changed in the old cluster, after the new -cluster forked off. - -2. Copy all those changed blocks from the new cluster to the old cluster. - -3. Copy all other files like clog, conf files etc. from the new cluster to old cluster. -Everything except the relation files. - -4. Apply the WAL from the new cluster, starting from the checkpoint created at -failover. (pg_rewind doesn't actually apply the WAL, it just creates a backup -label file indicating that when PostgreSQL is started, it will start replay -from that checkpoint and apply all the required WAL) + The basic idea is to copy everything from the new cluster to the old cluster, + except for the blocks that we know to be the same. + + + + + Scan the WAL log of the old cluster, starting from the last checkpoint + before the point where the new cluster's timeline history forked off + from the old cluster. For each WAL record, make a note of the data + blocks that were touched. This yields a list of all the data blocks + that were changed in the old cluster, after the new cluster forked off. + + + + + Copy all those changed blocks from the new cluster to the old cluster. + + + + + Copy all other files like clog, conf files etc. from the new cluster + to old cluster. Everything except the relation files. + + + + + Apply the WAL from the new cluster, starting from the checkpoint + created at failover. (pg_rewind doesn't actually apply the WAL, it + just creates a backup label file indicating that when PostgreSQL is + started, it will start replay from that checkpoint and apply all the + required WAL) + + + Restrictions - pg_reind needs that cluster uses either data checksums that + pg_rewind needs that cluster uses either data checksums that can be enabled at server initialization with initdb or WAL logging of hint - bits that can be enabled by settings "wal_log_hints = on" in postgresql.conf. + bits that can be enabled by settings wal_log_hints to on + in postgresql.conf.