NAME
pg_recvlogical - control PostgreSQL logical decoding streams
SYNOPSIS
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_receivewal(1), plus those for logical replication (see Chapter 47).
pg_recvlogical has no equivalent to the logical decoding SQL interface's 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 pg_logical_slot_peek_changes.
In the absence of fatal errors, pg_recvlogical will run until terminated by the SIGINT (Control+C) or SIGTERM signal.
When pg_recvlogical receives a SIGHUP signal, it closes the current output file and opens a new one using the filename specified by the --file option. This allows us to rotate the output file by first renaming the current file and then sending a SIGHUP signal to pg_recvlogical.
OPTIONS
At least one of the following options must be specified to select an action:
--create-slot
The --two-phase can be specified with --create-slot to enable decoding of prepared transactions.
--drop-slot
--start
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.
--create-slot and --start can be specified together. --drop-slot cannot be combined with another action.
The following command-line options control the location and format of the output and other replication behavior:
-Elsn --endpos=lsn
If there's a record with LSN exactly equal to lsn, the record will be output.
The --endpos 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.
-ffilename --file=filename
-Finterval_seconds --fsync-interval=interval_seconds
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.
-Ilsn --startpos=lsn
--if-not-exists
-n --no-loop
-oname[=value] --option=name[=value]
-Pplugin --plugin=plugin
-sinterval_seconds --status-interval=interval_seconds
-Sslot_name --slot=slot_name
-t --two-phase
-v --verbose
The following command-line options control the database connection parameters.
-ddbname --dbname=dbname
-hhostname-or-ip --host=hostname-or-ip
-pport --port=port
-Uuser --username=user
-w --no-password
-W --password
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 -W to avoid the extra connection attempt.
The following additional options are available:
-V --version
-? --help
EXIT STATUS
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.
ENVIRONMENT
This utility, like most other PostgreSQL utilities, uses the environment variables supported by libpq (see Section 32.15).
The environment variable PG_COLOR specifies whether to use color in diagnostic messages. Possible values are always, auto and never.
NOTES
pg_recvlogical will preserve group permissions on the received WAL files if group permissions are enabled on the source cluster.
EXAMPLES
See Section 47.1 for an example.
SEE ALSO
pg_receivewal(1)