From 5c8758e6ed54ff9e2c5ec72af619bbd52578659c Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Sat, 18 Oct 2014 09:10:12 -0400 Subject: doc: Clean up pg_recvlogical reference page This needed a general cleanup of wording, typos, outdated terminology, formatting, and hard-to-understand and borderline incorrect information. Also tweak the pg_receivexlog page a bit to make the two more consistent. --- doc/src/sgml/ref/pg_receivexlog.sgml | 79 ++++---- doc/src/sgml/ref/pg_recvlogical.sgml | 338 +++++++++++++++++++---------------- 2 files changed, 220 insertions(+), 197 deletions(-) (limited to 'doc') diff --git a/doc/src/sgml/ref/pg_receivexlog.sgml b/doc/src/sgml/ref/pg_receivexlog.sgml index b792aa5440..be26b84c1b 100644 --- a/doc/src/sgml/ref/pg_receivexlog.sgml +++ b/doc/src/sgml/ref/pg_receivexlog.sgml @@ -16,7 +16,7 @@ PostgreSQL documentation pg_receivexlog - streams transaction logs from a PostgreSQL cluster + stream transaction logs from a PostgreSQL server @@ -71,10 +71,6 @@ PostgreSQL documentation Options - - The following command-line options control the location and format of the - output. - @@ -88,12 +84,7 @@ PostgreSQL documentation - - - - The following command-line options control the running of the program. - @@ -105,6 +96,39 @@ PostgreSQL documentation + + + + + + Specifies the number of seconds between status packets sent back to the + server. This allows for easier monitoring of the progress from server. + A value of zero disables the periodic status updates completely, + although an update will still be sent when requested by the server, to + avoid timeout disconnect. The default value is 10 seconds. + + + + + + + + + + Require pg_receivexlog to use an existing + replication slot (see ). + When this option is used, pg_receivexlog will report + a flush position to the server, indicating when each segment has been + synchronized to disk so that the server can remove that segment if it + is not otherwise needed. When using this parameter, it is important + to make sure that pg_receivexlog cannot become the + synchronous standby through an incautious setting of + ; it does not flush + data frequently enough for this to work correctly. + + + + @@ -114,9 +138,7 @@ PostgreSQL documentation - - The following command-line options control the database connection parameters. @@ -166,20 +188,6 @@ PostgreSQL documentation - - - - - - Specifies the number of seconds between status packets sent back to the - server. This allows for easier monitoring of the progress from server. - A value of zero disables the periodic status updates completely, - although an update will still be sent when requested by the server, to - avoid timeout disconnect. The default value is 10 seconds. - - - - @@ -225,25 +233,6 @@ PostgreSQL documentation - - - - - - - Require pg_receivexlog to use an existing - replication slot (see ). - When this option is used, pg_receivexlog will report - a flush position to the server, indicating when each segment has been - synchronized to disk so that the server can remove that segment if it - is not otherwise needed. When using this parameter, it is important - to make sure that pg_receivexlog cannot become the - synchronous standby through an incautious setting of - ; it does not flush - data frequently enough for this to work correctly. - - - diff --git a/doc/src/sgml/ref/pg_recvlogical.sgml b/doc/src/sgml/ref/pg_recvlogical.sgml index 2a521c4f36..0343a13437 100644 --- a/doc/src/sgml/ref/pg_recvlogical.sgml +++ b/doc/src/sgml/ref/pg_recvlogical.sgml @@ -16,39 +16,35 @@ PostgreSQL documentation pg_recvlogical - Control logical decoding (see ) - streams over a walsender connection. + control PostgreSQL logical decoding streams pg_recvlogical - + option - + Description pg_recvlogical controls logical decoding replication slots and streams data from such replication slots. + It creates a replication-mode connection, so it is subject to the same - constraints as pg_receivexlog, - plus those for logical replication (see ). + constraints as , plus those for logical + replication (see ). - Options - pg_recvlogical runs in one of three modes, which - control its primary action: + At least one of the following options must be specified to select an action: @@ -56,129 +52,52 @@ PostgreSQL documentation - Create a new logical replication slot with the name specified in - , using the output plugin - , then exit. The slot is created for the - database given in . + Create a new logical replication slot with the name specified by + , using the output plugin specified by + , for the database specified + by . - + - Begin streaming changes from the logical replication slot with the name - specified in , continuing until terminated with a - signal. If the server side change stream ends with a server - shutdown or disconnect, retry in a loop unless - is specified. The stream format is - determined by the output plugin specified when the slot was created. - - - You must connect to the same database used to create the slot. + Drop the replication slot with the name specified + by , then exit. - + - Drop the replication slot with the name specified - in , then exit. + Begin streaming changes from the logical replication slot specified + by , continuing until terminated by a + signal. If the server side change stream ends with a server shutdown + or disconnect, retry in a loop unless + is specified. + + + + The stream format is determined by the output plugin specified when + the slot was created. + + + + The connection must be to the same database used to create the slot. - - pg_recvlogical supports all the usual - libpq-based options. These are explained in detail in - the documentation for - psql and for - libpq. - - - - - - - - - Username to connect as. Must have a suitable pg_hba.conf - entry allowing replication connections. Defaults to - current operating system user name. - - - - - - - - - - The database to connect to in replication mode; see - mode descriptions for details. May be - a libpq connstring - instead. Defaults to user name. - - - - - - - - - - Host or socket to connect - to. See psql - and libpq - documentation. - - - - - - - - - - Port number to connect to. See - psql - for an explanation of default port choices when this is not - specified. - - - - - - - - - - Prevent prompting for a password. Will exit with an error code if a - password is required but not available. - - - - - - - - - - Provide a password for this connection. Please use the pgservice file - (see ) or an environment variable - instead of this option. - - - - - - + and can be + specified together. cannot be combined with + another action. @@ -186,7 +105,6 @@ PostgreSQL documentation output and other replication behavior: - @@ -198,40 +116,62 @@ PostgreSQL documentation + + + + + + Specifies how often pg_recvlogical should + issue fsync() calls to ensure the output file is + safely flushed to disk. + + + + The server will occasionally request the client to perform a flush and + report the flush position to the server. This setting is in addition + to that, to perform flushes more frequently. + + + + Specifying an interval of 0 disables + issuing fsync() calls altogether, while still + reporting progress to the server. In this case, data could be lost in + the event of a crash. + + + - - + + - When the connection to the server is lost, do not retry in a loop, just exit. + In mode, start replication from the given + LSN. For details on the effect of this, see the documentation + in + and . Ignored in other modes. - - + + - Pass the option NAME to the output plugin with, - if specified, the option value NAME. Which - options exist and their effects depends on the used output plugin. + When the connection to the server is lost, do not retry in a loop, just exit. - - + + - How often should pg_recvlogical issue sync - commands to ensure the --outputfile is safely - flushed to disk without being asked by the server to do so. Specifying - an interval of 0 disables issuing fsyncs altogether, - while still reporting progress the server. In this case, data may be - lost in the event of a crash. + Pass the option name to the output plugin with, + if specified, the option value value. Which + options exist and their effects depends on the used output plugin. @@ -241,7 +181,7 @@ PostgreSQL documentation - When creating a slot, use the logical decoding output + When creating a slot, use the specified logical decoding output plugin. See . This option has no effect if the slot already exists. @@ -253,9 +193,8 @@ PostgreSQL documentation - This option has the same effect as the option of the same name in pg_receivexlog. - See the description there. + This option has the same effect as the option of the same name + in . See the description there. @@ -274,36 +213,114 @@ PostgreSQL documentation - - - + + + - In mode, start replication from the given - LSN. For details on the effect of this, see the documentation - in - and . Ignored in other modes. + Enables verbose mode. - + - - The following additional options are available: - + The following command-line options control the database connection parameters. + + + + + + + The database to connect to. See the description of the actions for + what this means in detail. This can be a libpq connection string; + see for more information. Defaults + to user name. + + + - - - + + + - - Enables verbose mode. - + + Specifies the host name of the machine on which the server is + running. If the value begins with a slash, it is used as the + directory for the Unix domain socket. The default is taken + from the PGHOST environment variable, if set, + else a Unix domain socket connection is attempted. + + + + + + + + + Specifies the TCP port or local Unix domain socket file + extension on which the server is listening for connections. + Defaults to the PGPORT environment variable, if + set, or a compiled-in default. + + + + + + + + + + Username to connect as. Defaults to current operating system user + name. + + + + + + + + + + Never issue a password prompt. If the server requires + password authentication and a password is not available by + other means such as a .pgpass file, the + connection attempt will fail. This option can be useful in + batch jobs and scripts where no user is present to enter a + password. + + + + + + + + + + Force pg_recvlogical to prompt for a + password before connecting to a database. + + + + This option is never essential, since + pg_recvlogical will automatically prompt + for a password if the server demands password authentication. + However, pg_recvlogical will waste a + connection attempt finding out that the server wants a password. + In some cases it is worth typing + + + + + + The following additional options are available: + @@ -324,8 +341,25 @@ PostgreSQL documentation - + + + Environment + + + This utility, like most other PostgreSQL utilities, + uses the environment variables supported by libpq + (see ). + + + + + See Also + + + + + -- cgit v1.2.1