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

   1
   2 pg_recvlogical
   3
   4    pg_recvlogical — control PostgreSQL logical decoding streams
   5
   6 Synopsis
   7
   8    pg_recvlogical [option...]
   9
  10 Description
  11
  12    pg_recvlogical controls logical decoding replication slots and streams
  13    data from such replication slots.
  14
  15    It creates a replication-mode connection, so it is subject to the same
  16    constraints as pg_receivewal, plus those for logical replication (see
  17    Chapter 47).
  18
  19    pg_recvlogical has no equivalent to the logical decoding SQL
  20    interface's peek and get modes. It sends replay confirmations for data
  21    lazily as it receives it and on clean exit. To examine pending data on
  22    a slot without consuming it, use pg_logical_slot_peek_changes.
  23
  24    In the absence of fatal errors, pg_recvlogical will run until
  25    terminated by the SIGINT (Control+C) or SIGTERM signal.
  26
  27    When pg_recvlogical receives a SIGHUP signal, it closes the current
  28    output file and opens a new one using the filename specified by the
  29    --file option. This allows us to rotate the output file by first
  30    renaming the current file and then sending a SIGHUP signal to
  31    pg_recvlogical.
  32
  33 Options
  34
  35    At least one of the following options must be specified to select an
  36    action:
  37
  38    --create-slot
  39           Create a new logical replication slot with the name specified by
  40           --slot, using the output plugin specified by --plugin, for the
  41           database specified by --dbname.
  42
  43           The --slot and --dbname are required for this action.
  44
  45           The --enable-two-phase and --enable-failover options can be
  46           specified with --create-slot.
  47
  48    --drop-slot
  49           Drop the replication slot with the name specified by --slot,
  50           then exit.
  51
  52           The --slot is required for this action.
  53
  54    --start
  55           Begin streaming changes from the logical replication slot
  56           specified by --slot, continuing until terminated by a signal. If
  57           the server side change stream ends with a server shutdown or
  58           disconnect, retry in a loop unless --no-loop is specified.
  59
  60           The --slot and --dbname, --file are required for this action.
  61
  62           The stream format is determined by the output plugin specified
  63           when the slot was created.
  64
  65           The connection must be to the same database used to create the
  66           slot.
  67
  68    --create-slot and --start can be specified together. --drop-slot cannot
  69    be combined with another action.
  70
  71    The following command-line options control the location and format of
  72    the output and other replication behavior:
  73
  74    -E lsn
  75           --endpos=lsn
  76           In --start mode, automatically stop replication and exit with
  77           normal exit status 0 when receiving reaches the specified LSN.
  78           If specified when not in --start mode, an error is raised.
  79
  80           If there's a record with LSN exactly equal to lsn, the record
  81           will be output.
  82
  83           The --endpos option is not aware of transaction boundaries and
  84           may truncate output partway through a transaction. Any partially
  85           output transaction will not be consumed and will be replayed
  86           again when the slot is next read from. Individual messages are
  87           never truncated.
  88
  89    --enable-failover
  90           Enables the slot to be synchronized to the standbys. This option
  91           may only be specified with --create-slot.
  92
  93    -f filename
  94           --file=filename
  95           Write received and decoded transaction data into this file. Use
  96           - for stdout.
  97
  98           This parameter is required for --start.
  99
 100    -F interval_seconds
 101           --fsync-interval=interval_seconds
 102           Specifies how often pg_recvlogical should issue fsync() calls to
 103           ensure the output file is safely flushed to disk.
 104
 105           The server will occasionally request the client to perform a
 106           flush and report the flush position to the server. This setting
 107           is in addition to that, to perform flushes more frequently.
 108
 109           Specifying an interval of 0 disables issuing fsync() calls
 110           altogether, while still reporting progress to the server. In
 111           this case, data could be lost in the event of a crash.
 112
 113    -I lsn
 114           --startpos=lsn
 115           In --start mode, start replication from the given LSN. For
 116           details on the effect of this, see the documentation in
 117           Chapter 47 and Section 54.4. Ignored in other modes.
 118
 119    --if-not-exists
 120           Do not error out when --create-slot is specified and a slot with
 121           the specified name already exists.
 122
 123    -n
 124           --no-loop
 125           When the connection to the server is lost, do not retry in a
 126           loop, just exit.
 127
 128    -o name[=value]
 129           --option=name[=value]
 130           Pass the option name to the output plugin with, if specified,
 131           the option value value. Which options exist and their effects
 132           depends on the used output plugin.
 133
 134    -P plugin
 135           --plugin=plugin
 136           When creating a slot, use the specified logical decoding output
 137           plugin. See Chapter 47. This option has no effect if the slot
 138           already exists.
 139
 140    -s interval_seconds
 141           --status-interval=interval_seconds
 142           This option has the same effect as the option of the same name
 143           in pg_receivewal. See the description there.
 144
 145    -S slot_name
 146           --slot=slot_name
 147           In --start mode, use the existing logical replication slot named
 148           slot_name. In --create-slot mode, create the slot with this
 149           name. In --drop-slot mode, delete the slot with this name.
 150
 151           This parameter is required for any of actions.
 152
 153    -t
 154           --enable-two-phase
 155           --two-phase (deprecated)
 156           Enables decoding of prepared transactions. This option may only
 157           be specified with --create-slot.
 158
 159    -v
 160           --verbose
 161           Enables verbose mode.
 162
 163    The following command-line options control the database connection
 164    parameters.
 165
 166    -d dbname
 167           --dbname=dbname
 168           The database to connect to. See the description of the actions
 169           for what this means in detail. The dbname can be a connection
 170           string. If so, connection string parameters will override any
 171           conflicting command line options.
 172
 173           This parameter is required for --create-slot and --start.
 174
 175    -h hostname-or-ip
 176           --host=hostname-or-ip
 177           Specifies the host name of the machine on which the server is
 178           running. If the value begins with a slash, it is used as the
 179           directory for the Unix domain socket. The default is taken from
 180           the PGHOST environment variable, if set, else a Unix domain
 181           socket connection is attempted.
 182
 183    -p port
 184           --port=port
 185           Specifies the TCP port or local Unix domain socket file
 186           extension on which the server is listening for connections.
 187           Defaults to the PGPORT environment variable, if set, or a
 188           compiled-in default.
 189
 190    -U user
 191           --username=user
 192           User name to connect as. Defaults to current operating system
 193           user name.
 194
 195    -w
 196           --no-password
 197           Never issue a password prompt. If the server requires password
 198           authentication and a password is not available by other means
 199           such as a .pgpass file, the connection attempt will fail. This
 200           option can be useful in batch jobs and scripts where no user is
 201           present to enter a password.
 202
 203    -W
 204           --password
 205           Force pg_recvlogical to prompt for a password before connecting
 206           to a database.
 207
 208           This option is never essential, since pg_recvlogical will
 209           automatically prompt for a password if the server demands
 210           password authentication. However, pg_recvlogical will waste a
 211           connection attempt finding out that the server wants a password.
 212           In some cases it is worth typing -W to avoid the extra
 213           connection attempt.
 214
 215    The following additional options are available:
 216
 217    -V
 218           --version
 219           Print the pg_recvlogical version and exit.
 220
 221    -?
 222           --help
 223           Show help about pg_recvlogical command line arguments, and exit.
 224
 225 Exit Status
 226
 227    pg_recvlogical will exit with status 0 when terminated by the SIGINT or
 228    SIGTERM signal. (That is the normal way to end it. Hence it is not an
 229    error.) For fatal errors or other signals, the exit status will be
 230    nonzero.
 231
 232 Environment
 233
 234    This utility, like most other PostgreSQL utilities, uses the
 235    environment variables supported by libpq (see Section 32.15).
 236
 237    The environment variable PG_COLOR specifies whether to use color in
 238    diagnostic messages. Possible values are always, auto and never.
 239
 240 Notes
 241
 242    pg_recvlogical will preserve group permissions on the received WAL
 243    files if group permissions are enabled on the source cluster.
 244
 245 Examples
 246
 247    See Section 47.1 for an example.
 248
 249 See Also
 250
 251    pg_receivewal