begriffs open source - ai-pg/blob - full-docs/src/sgml/man1/pg_recvlogical.1

   1 '\" t
   2 .\"     Title: pg_recvlogical
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "PG_RECVLOGICAL" "1" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 pg_recvlogical \- control PostgreSQL logical decoding streams
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBpg_recvlogical\fR\ 'u
  34 \fBpg_recvlogical\fR [\fIoption\fR...]
  35 .SH "DESCRIPTION"
  36 .PP
  37 \fBpg_recvlogical\fR
  38 controls logical decoding replication slots and streams data from such replication slots\&.
  39 .PP
  40 It creates a replication\-mode connection, so it is subject to the same constraints as
  41 \fBpg_receivewal\fR(1), plus those for logical replication (see
  42 Chapter\ \&47)\&.
  43 .PP
  44 \fBpg_recvlogical\fR
  45 has no equivalent to the logical decoding SQL interface\*(Aqs peek and get modes\&. It sends replay confirmations for data lazily as it receives it and on clean exit\&. To examine pending data on a slot without consuming it, use
  46 \fBpg_logical_slot_peek_changes\fR\&.
  47 .PP
  48 In the absence of fatal errors,
  49 pg_recvlogical
  50 will run until terminated by the
  51 SIGINT
  52 (Control+C) or
  53 SIGTERM
  54 signal\&.
  55 .PP
  56 When
  57 pg_recvlogical
  58 receives a
  59 SIGHUP
  60 signal, it closes the current output file and opens a new one using the filename specified by the
  61 \fB\-\-file\fR
  62 option\&. This allows us to rotate the output file by first renaming the current file and then sending a
  63 SIGHUP
  64 signal to
  65 pg_recvlogical\&.
  66 .SH "OPTIONS"
  67 .PP
  68 At least one of the following options must be specified to select an action:
  69 .PP
  70 \fB\-\-create\-slot\fR
  71 .RS 4
  72 Create a new logical replication slot with the name specified by
  73 \fB\-\-slot\fR, using the output plugin specified by
  74 \fB\-\-plugin\fR, for the database specified by
  75 \fB\-\-dbname\fR\&.
  76 .sp
  77 The
  78 \fB\-\-slot\fR
  79 and
  80 \fB\-\-dbname\fR
  81 are required for this action\&.
  82 .sp
  83 The
  84 \fB\-\-enable\-two\-phase\fR
  85 and
  86 \fB\-\-enable\-failover\fR
  87 options can be specified with
  88 \fB\-\-create\-slot\fR\&.
  89 .RE
  90 .PP
  91 \fB\-\-drop\-slot\fR
  92 .RS 4
  93 Drop the replication slot with the name specified by
  94 \fB\-\-slot\fR, then exit\&.
  95 .sp
  96 The
  97 \fB\-\-slot\fR
  98 is required for this action\&.
  99 .RE
 100 .PP
 101 \fB\-\-start\fR
 102 .RS 4
 103 Begin streaming changes from the logical replication slot specified by
 104 \fB\-\-slot\fR, continuing until terminated by a signal\&. If the server side change stream ends with a server shutdown or disconnect, retry in a loop unless
 105 \fB\-\-no\-loop\fR
 106 is specified\&.
 107 .sp
 108 The
 109 \fB\-\-slot\fR
 110 and
 111 \fB\-\-dbname\fR,
 112 \fB\-\-file\fR
 113 are required for this action\&.
 114 .sp
 115 The stream format is determined by the output plugin specified when the slot was created\&.
 116 .sp
 117 The connection must be to the same database used to create the slot\&.
 118 .RE
 119 .PP
 120 \fB\-\-create\-slot\fR
 121 and
 122 \fB\-\-start\fR
 123 can be specified together\&.
 124 \fB\-\-drop\-slot\fR
 125 cannot be combined with another action\&.
 126 .PP
 127 The following command\-line options control the location and format of the output and other replication behavior:
 128 .PP
 129 \fB\-E \fR\fB\fIlsn\fR\fR
 130 .br
 131 \fB\-\-endpos=\fR\fB\fIlsn\fR\fR
 132 .RS 4
 133 In
 134 \fB\-\-start\fR
 135 mode, automatically stop replication and exit with normal exit status 0 when receiving reaches the specified LSN\&. If specified when not in
 136 \fB\-\-start\fR
 137 mode, an error is raised\&.
 138 .sp
 139 If there\*(Aqs a record with LSN exactly equal to
 140 \fIlsn\fR, the record will be output\&.
 141 .sp
 142 The
 143 \fB\-\-endpos\fR
 144 option is not aware of transaction boundaries and may truncate output partway through a transaction\&. Any partially output transaction will not be consumed and will be replayed again when the slot is next read from\&. Individual messages are never truncated\&.
 145 .RE
 146 .PP
 147 \fB\-\-enable\-failover\fR
 148 .RS 4
 149 Enables the slot to be synchronized to the standbys\&. This option may only be specified with
 150 \fB\-\-create\-slot\fR\&.
 151 .RE
 152 .PP
 153 \fB\-f \fR\fB\fIfilename\fR\fR
 154 .br
 155 \fB\-\-file=\fR\fB\fIfilename\fR\fR
 156 .RS 4
 157 Write received and decoded transaction data into this file\&. Use
 158 \-
 159 for
 160 stdout\&.
 161 .sp
 162 This parameter is required for
 163 \fB\-\-start\fR\&.
 164 .RE
 165 .PP
 166 \fB\-F \fR\fB\fIinterval_seconds\fR\fR
 167 .br
 168 \fB\-\-fsync\-interval=\fR\fB\fIinterval_seconds\fR\fR
 169 .RS 4
 170 Specifies how often
 171 pg_recvlogical
 172 should issue
 173 \fBfsync()\fR
 174 calls to ensure the output file is safely flushed to disk\&.
 175 .sp
 176 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\&.
 177 .sp
 178 Specifying an interval of
 179 0
 180 disables issuing
 181 \fBfsync()\fR
 182 calls altogether, while still reporting progress to the server\&. In this case, data could be lost in the event of a crash\&.
 183 .RE
 184 .PP
 185 \fB\-I \fR\fB\fIlsn\fR\fR
 186 .br
 187 \fB\-\-startpos=\fR\fB\fIlsn\fR\fR
 188 .RS 4
 189 In
 190 \fB\-\-start\fR
 191 mode, start replication from the given LSN\&. For details on the effect of this, see the documentation in
 192 Chapter\ \&47
 193 and
 194 Section\ \&54.4\&. Ignored in other modes\&.
 195 .RE
 196 .PP
 197 \fB\-\-if\-not\-exists\fR
 198 .RS 4
 199 Do not error out when
 200 \fB\-\-create\-slot\fR
 201 is specified and a slot with the specified name already exists\&.
 202 .RE
 203 .PP
 204 \fB\-n\fR
 205 .br
 206 \fB\-\-no\-loop\fR
 207 .RS 4
 208 When the connection to the server is lost, do not retry in a loop, just exit\&.
 209 .RE
 210 .PP
 211 \fB\-o \fR\fB\fIname\fR\fR\fB[=\fR\fB\fIvalue\fR\fR\fB]\fR
 212 .br
 213 \fB\-\-option=\fR\fB\fIname\fR\fR\fB[=\fR\fB\fIvalue\fR\fR\fB]\fR
 214 .RS 4
 215 Pass the option
 216 \fIname\fR
 217 to the output plugin with, if specified, the option value
 218 \fIvalue\fR\&. Which options exist and their effects depends on the used output plugin\&.
 219 .RE
 220 .PP
 221 \fB\-P \fR\fB\fIplugin\fR\fR
 222 .br
 223 \fB\-\-plugin=\fR\fB\fIplugin\fR\fR
 224 .RS 4
 225 When creating a slot, use the specified logical decoding output plugin\&. See
 226 Chapter\ \&47\&. This option has no effect if the slot already exists\&.
 227 .RE
 228 .PP
 229 \fB\-s \fR\fB\fIinterval_seconds\fR\fR
 230 .br
 231 \fB\-\-status\-interval=\fR\fB\fIinterval_seconds\fR\fR
 232 .RS 4
 233 This option has the same effect as the option of the same name in
 234 \fBpg_receivewal\fR(1)\&. See the description there\&.
 235 .RE
 236 .PP
 237 \fB\-S \fR\fB\fIslot_name\fR\fR
 238 .br
 239 \fB\-\-slot=\fR\fB\fIslot_name\fR\fR
 240 .RS 4
 241 In
 242 \fB\-\-start\fR
 243 mode, use the existing logical replication slot named
 244 \fIslot_name\fR\&. In
 245 \fB\-\-create\-slot\fR
 246 mode, create the slot with this name\&. In
 247 \fB\-\-drop\-slot\fR
 248 mode, delete the slot with this name\&.
 249 .sp
 250 This parameter is required for any of actions\&.
 251 .RE
 252 .PP
 253 \fB\-t\fR
 254 .br
 255 \fB\-\-enable\-two\-phase\fR
 256 .br
 257 \fB\-\-two\-phase\fR (deprecated)
 258 .RS 4
 259 Enables decoding of prepared transactions\&. This option may only be specified with
 260 \fB\-\-create\-slot\fR\&.
 261 .RE
 262 .PP
 263 \fB\-v\fR
 264 .br
 265 \fB\-\-verbose\fR
 266 .RS 4
 267 Enables verbose mode\&.
 268 .RE
 269 .PP
 270 The following command\-line options control the database connection parameters\&.
 271 .PP
 272 \fB\-d \fR\fB\fIdbname\fR\fR
 273 .br
 274 \fB\-\-dbname=\fR\fB\fIdbname\fR\fR
 275 .RS 4
 276 The database to connect to\&. See the description of the actions for what this means in detail\&. The
 277 \fIdbname\fR
 278 can be a
 279 connection string\&. If so, connection string parameters will override any conflicting command line options\&.
 280 .sp
 281 This parameter is required for
 282 \fB\-\-create\-slot\fR
 283 and
 284 \fB\-\-start\fR\&.
 285 .RE
 286 .PP
 287 \fB\-h \fR\fB\fIhostname\-or\-ip\fR\fR
 288 .br
 289 \fB\-\-host=\fR\fB\fIhostname\-or\-ip\fR\fR
 290 .RS 4
 291 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
 292 \fBPGHOST\fR
 293 environment variable, if set, else a Unix domain socket connection is attempted\&.
 294 .RE
 295 .PP
 296 \fB\-p \fR\fB\fIport\fR\fR
 297 .br
 298 \fB\-\-port=\fR\fB\fIport\fR\fR
 299 .RS 4
 300 Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. Defaults to the
 301 \fBPGPORT\fR
 302 environment variable, if set, or a compiled\-in default\&.
 303 .RE
 304 .PP
 305 \fB\-U \fR\fB\fIuser\fR\fR
 306 .br
 307 \fB\-\-username=\fR\fB\fIuser\fR\fR
 308 .RS 4
 309 User name to connect as\&. Defaults to current operating system user name\&.
 310 .RE
 311 .PP
 312 \fB\-w\fR
 313 .br
 314 \fB\-\-no\-password\fR
 315 .RS 4
 316 Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a
 317 \&.pgpass
 318 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\&.
 319 .RE
 320 .PP
 321 \fB\-W\fR
 322 .br
 323 \fB\-\-password\fR
 324 .RS 4
 325 Force
 326 pg_recvlogical
 327 to prompt for a password before connecting to a database\&.
 328 .sp
 329 This option is never essential, since
 330 pg_recvlogical
 331 will automatically prompt for a password if the server demands password authentication\&. However,
 332 pg_recvlogical
 333 will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing
 334 \fB\-W\fR
 335 to avoid the extra connection attempt\&.
 336 .RE
 337 .PP
 338 The following additional options are available:
 339 .PP
 340 \fB\-V\fR
 341 .br
 342 \fB\-\-version\fR
 343 .RS 4
 344 Print the
 345 pg_recvlogical
 346 version and exit\&.
 347 .RE
 348 .PP
 349 \fB\-?\fR
 350 .br
 351 \fB\-\-help\fR
 352 .RS 4
 353 Show help about
 354 pg_recvlogical
 355 command line arguments, and exit\&.
 356 .RE
 357 .SH "EXIT STATUS"
 358 .PP
 359 pg_recvlogical
 360 will exit with status 0 when terminated by the
 361 SIGINT
 362 or
 363 SIGTERM
 364 signal\&. (That is the normal way to end it\&. Hence it is not an error\&.) For fatal errors or other signals, the exit status will be nonzero\&.
 365 .SH "ENVIRONMENT"
 366 .PP
 367 This utility, like most other
 368 PostgreSQL
 369 utilities, uses the environment variables supported by
 370 libpq
 371 (see
 372 Section\ \&32.15)\&.
 373 .PP
 374 The environment variable
 375 \fBPG_COLOR\fR
 376 specifies whether to use color in diagnostic messages\&. Possible values are
 377 always,
 378 auto
 379 and
 380 never\&.
 381 .SH "NOTES"
 382 .PP
 383 pg_recvlogical
 384 will preserve group permissions on the received WAL files if group permissions are enabled on the source cluster\&.
 385 .SH "EXAMPLES"
 386 .PP
 387 See
 388 Section\ \&47.1
 389 for an example\&.
 390 .SH "SEE ALSO"
 391 \fBpg_receivewal\fR(1)