path: root/doc/src/sgml/man1/pg_recvlogical.1

'\" t
.\"     Title: pg_recvlogical
.\"    Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2024
.\"    Manual: PostgreSQL 16.2 Documentation
.\"    Source: PostgreSQL 16.2
.\"  Language: English
.\"
.TH "PG_RECVLOGICAL" "1" "2024" "PostgreSQL 16.2" "PostgreSQL 16.2 Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pg_recvlogical \- control PostgreSQL logical decoding streams
.SH "SYNOPSIS"
.HP \w'\fBpg_recvlogical\fR\ 'u
\fBpg_recvlogical\fR [\fIoption\fR...]
.SH "DESCRIPTION"
.PP
\fBpg_recvlogical\fR
controls logical decoding replication slots and streams data from such replication slots\&.
.PP
It creates a replication\-mode connection, so it is subject to the same constraints as
\fBpg_receivewal\fR(1), plus those for logical replication (see
Chapter\ \&49)\&.
.PP
\fBpg_recvlogical\fR
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
\fBpg_logical_slot_peek_changes\fR\&.
.PP
In the absence of fatal errors,
pg_recvlogical
will run until terminated by the
SIGINT
(Control+C) or
SIGTERM
signal\&.
.SH "OPTIONS"
.PP
At least one of the following options must be specified to select an action:
.PP
\fB\-\-create\-slot\fR
.RS 4
Create a new logical replication slot with the name specified by
\fB\-\-slot\fR, using the output plugin specified by
\fB\-\-plugin\fR, for the database specified by
\fB\-\-dbname\fR\&.
.sp
The
\fB\-\-two\-phase\fR
can be specified with
\fB\-\-create\-slot\fR
to enable decoding of prepared transactions\&.
.RE
.PP
\fB\-\-drop\-slot\fR
.RS 4
Drop the replication slot with the name specified by
\fB\-\-slot\fR, then exit\&.
.RE
.PP
\fB\-\-start\fR
.RS 4
Begin streaming changes from the logical replication slot specified by
\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
\fB\-\-no\-loop\fR
is specified\&.
.sp
The stream format is determined by the output plugin specified when the slot was created\&.
.sp
The connection must be to the same database used to create the slot\&.
.RE
.PP
\fB\-\-create\-slot\fR
and
\fB\-\-start\fR
can be specified together\&.
\fB\-\-drop\-slot\fR
cannot be combined with another action\&.
.PP
The following command\-line options control the location and format of the output and other replication behavior:
.PP
\fB\-E \fR\fB\fIlsn\fR\fR
.br
\fB\-\-endpos=\fR\fB\fIlsn\fR\fR
.RS 4
In
\fB\-\-start\fR
mode, automatically stop replication and exit with normal exit status 0 when receiving reaches the specified LSN\&. If specified when not in
\fB\-\-start\fR
mode, an error is raised\&.
.sp
If there\*(Aqs a record with LSN exactly equal to
\fIlsn\fR, the record will be output\&.
.sp
The
\fB\-\-endpos\fR
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\&.
.RE
.PP
\fB\-f \fR\fB\fIfilename\fR\fR
.br
\fB\-\-file=\fR\fB\fIfilename\fR\fR
.RS 4
Write received and decoded transaction data into this file\&. Use
\-
for
stdout\&.
.RE
.PP
\fB\-F \fR\fB\fIinterval_seconds\fR\fR
.br
\fB\-\-fsync\-interval=\fR\fB\fIinterval_seconds\fR\fR
.RS 4
Specifies how often
pg_recvlogical
should issue
\fBfsync()\fR
calls to ensure the output file is safely flushed to disk\&.
.sp
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\&.
.sp
Specifying an interval of
0
disables issuing
\fBfsync()\fR
calls altogether, while still reporting progress to the server\&. In this case, data could be lost in the event of a crash\&.
.RE
.PP
\fB\-I \fR\fB\fIlsn\fR\fR
.br
\fB\-\-startpos=\fR\fB\fIlsn\fR\fR
.RS 4
In
\fB\-\-start\fR
mode, start replication from the given LSN\&. For details on the effect of this, see the documentation in
Chapter\ \&49
and
Section\ \&55.4\&. Ignored in other modes\&.
.RE
.PP
\fB\-\-if\-not\-exists\fR
.RS 4
Do not error out when
\fB\-\-create\-slot\fR
is specified and a slot with the specified name already exists\&.
.RE
.PP
\fB\-n\fR
.br
\fB\-\-no\-loop\fR
.RS 4
When the connection to the server is lost, do not retry in a loop, just exit\&.
.RE
.PP
\fB\-o \fR\fB\fIname\fR\fR\fB[=\fR\fB\fIvalue\fR\fR\fB]\fR
.br
\fB\-\-option=\fR\fB\fIname\fR\fR\fB[=\fR\fB\fIvalue\fR\fR\fB]\fR
.RS 4
Pass the option
\fIname\fR
to the output plugin with, if specified, the option value
\fIvalue\fR\&. Which options exist and their effects depends on the used output plugin\&.
.RE
.PP
\fB\-P \fR\fB\fIplugin\fR\fR
.br
\fB\-\-plugin=\fR\fB\fIplugin\fR\fR
.RS 4
When creating a slot, use the specified logical decoding output plugin\&. See
Chapter\ \&49\&. This option has no effect if the slot already exists\&.
.RE
.PP
\fB\-s \fR\fB\fIinterval_seconds\fR\fR
.br
\fB\-\-status\-interval=\fR\fB\fIinterval_seconds\fR\fR
.RS 4
This option has the same effect as the option of the same name in
\fBpg_receivewal\fR(1)\&. See the description there\&.
.RE
.PP
\fB\-S \fR\fB\fIslot_name\fR\fR
.br
\fB\-\-slot=\fR\fB\fIslot_name\fR\fR
.RS 4
In
\fB\-\-start\fR
mode, use the existing logical replication slot named
\fIslot_name\fR\&. In
\fB\-\-create\-slot\fR
mode, create the slot with this name\&. In
\fB\-\-drop\-slot\fR
mode, delete the slot with this name\&.
.RE
.PP
\fB\-t\fR
.br
\fB\-\-two\-phase\fR
.RS 4
Enables decoding of prepared transactions\&. This option may only be specified with
\fB\-\-create\-slot\fR
.RE
.PP
\fB\-v\fR
.br
\fB\-\-verbose\fR
.RS 4
Enables verbose mode\&.
.RE
.PP
The following command\-line options control the database connection parameters\&.
.PP
\fB\-d \fR\fB\fIdbname\fR\fR
.br
\fB\-\-dbname=\fR\fB\fIdbname\fR\fR
.RS 4
The database to connect to\&. See the description of the actions for what this means in detail\&. The
\fIdbname\fR
can be a
connection string\&. If so, connection string parameters will override any conflicting command line options\&. Defaults to the user name\&.
.RE
.PP
\fB\-h \fR\fB\fIhostname\-or\-ip\fR\fR
.br
\fB\-\-host=\fR\fB\fIhostname\-or\-ip\fR\fR
.RS 4
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
\fBPGHOST\fR
environment variable, if set, else a Unix domain socket connection is attempted\&.
.RE
.PP
\fB\-p \fR\fB\fIport\fR\fR
.br
\fB\-\-port=\fR\fB\fIport\fR\fR
.RS 4
Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. Defaults to the
\fBPGPORT\fR
environment variable, if set, or a compiled\-in default\&.
.RE
.PP
\fB\-U \fR\fB\fIuser\fR\fR
.br
\fB\-\-username=\fR\fB\fIuser\fR\fR
.RS 4
User name to connect as\&. Defaults to current operating system user name\&.
.RE
.PP
\fB\-w\fR
.br
\fB\-\-no\-password\fR
.RS 4
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\&.
.RE
.PP
\fB\-W\fR
.br
\fB\-\-password\fR
.RS 4
Force
pg_recvlogical
to prompt for a password before connecting to a database\&.
.sp
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
\fB\-W\fR
to avoid the extra connection attempt\&.
.RE
.PP
The following additional options are available:
.PP
\fB\-V\fR
.br
\fB\-\-version\fR
.RS 4
Print the
pg_recvlogical
version and exit\&.
.RE
.PP
\fB\-?\fR
.br
\fB\-\-help\fR
.RS 4
Show help about
pg_recvlogical
command line arguments, and exit\&.
.RE
.SH "EXIT STATUS"
.PP
pg_recvlogical
will exit with status 0 when terminated by the
SIGINT
or
SIGTERM
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\&.
.SH "ENVIRONMENT"
.PP
This utility, like most other
PostgreSQL
utilities, uses the environment variables supported by
libpq
(see
Section\ \&34.15)\&.
.PP
The environment variable
\fBPG_COLOR\fR
specifies whether to use color in diagnostic messages\&. Possible values are
always,
auto
and
never\&.
.SH "NOTES"
.PP
pg_recvlogical
will preserve group permissions on the received WAL files if group permissions are enabled on the source cluster\&.
.SH "EXAMPLES"
.PP
See
Section\ \&49.1
for an example\&.
.SH "SEE ALSO"
\fBpg_receivewal\fR(1)