1PG_RECVLOGICAL(1) PostgreSQL 15.4 Documentation PG_RECVLOGICAL(1)
2
6 pg_recvlogical - control PostgreSQL logical decoding streams
7
9 pg_recvlogical [option...]
10
12 pg_recvlogical controls logical decoding replication slots and streams
13 data from such replication slots.
14 It creates a replication-mode connection, so it is subject to the same
16 constraints as pg_receivewal(1), plus those for logical replication
17 (see Chapter 49).
18 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
25 At least one of the following options must be specified to select an
26 action:
27 --create-slot
29 Create a new logical replication slot with the name specified by
30 --slot, using the output plugin specified by --plugin, for the
31 database specified by --dbname.
32 The --two-phase can be specified with --create-slot to enable
34 decoding of prepared transactions.
35 --drop-slot
37 Drop the replication slot with the name specified by --slot, then
38 exit.
39 --start
41 Begin streaming changes from the logical replication slot specified
42 by --slot, continuing until terminated by a signal. If the server
43 side change stream ends with a server shutdown or disconnect, retry
44 in a loop unless --no-loop is specified.
45 The stream format is determined by the output plugin specified when
47 the slot was created.
48 The connection must be to the same database used to create the
50 slot.
51 --create-slot and --start can be specified together. --drop-slot
53 cannot be combined with another action.
54 The following command-line options control the location and format of
56 the output and other replication behavior:
57 -E lsn
59 --endpos=lsn
60 In --start mode, automatically stop replication and exit with
61 normal exit status 0 when receiving reaches the specified LSN. If
62 specified when not in --start mode, an error is raised.
63 If there's a record with LSN exactly equal to lsn, the record will
65 be output.
66 The --endpos option is not aware of transaction boundaries and may
68 truncate output partway through a transaction. Any partially output
69 transaction will not be consumed and will be replayed again when
70 the slot is next read from. Individual messages are never
71 truncated.
72 -f filename
74 --file=filename
75 Write received and decoded transaction data into this file. Use -
76 for stdout.
77 -F interval_seconds
79 --fsync-interval=interval_seconds
80 Specifies how often pg_recvlogical should issue fsync() calls to
81 ensure the output file is safely flushed to disk.
82 The server will occasionally request the client to perform a flush
84 and report the flush position to the server. This setting is in
85 addition to that, to perform flushes more frequently.
86 Specifying an interval of 0 disables issuing fsync() calls
88 altogether, while still reporting progress to the server. In this
89 case, data could be lost in the event of a crash.
90 -I lsn
92 --startpos=lsn
93 In --start mode, start replication from the given LSN. For details
94 on the effect of this, see the documentation in Chapter 49 and
95 Section 55.4. Ignored in other modes.
96 --if-not-exists
98 Do not error out when --create-slot is specified and a slot with
99 the specified name already exists.
100 -n
102 --no-loop
103 When the connection to the server is lost, do not retry in a loop,
104 just exit.
105 -o name[=value]
107 --option=name[=value]
108 Pass the option name to the output plugin with, if specified, the
109 option value value. Which options exist and their effects depends
110 on the used output plugin.
111 -P plugin
113 --plugin=plugin
114 When creating a slot, use the specified logical decoding output
115 plugin. See Chapter 49. This option has no effect if the slot
116 already exists.
117 -s interval_seconds
119 --status-interval=interval_seconds
120 This option has the same effect as the option of the same name in
121 pg_receivewal(1). See the description there.
122 -S slot_name
124 --slot=slot_name
125 In --start mode, use the existing logical replication slot named
126 slot_name. In --create-slot mode, create the slot with this name.
127 In --drop-slot mode, delete the slot with this name.
128 -t
130 --two-phase
131 Enables decoding of prepared transactions. This option may only be
132 specified with --create-slot
133 -v
135 --verbose
136 Enables verbose mode.
137 The following command-line options control the database connection
139 parameters.
140 -d dbname
142 --dbname=dbname
143 The database to connect to. See the description of the actions for
144 what this means in detail. The dbname can be a connection string.
145 If so, connection string parameters will override any conflicting
146 command line options. Defaults to the user name.
147 -h hostname-or-ip
149 --host=hostname-or-ip
150 Specifies the host name of the machine on which the server is
151 running. If the value begins with a slash, it is used as the
152 directory for the Unix domain socket. The default is taken from the
153 PGHOST environment variable, if set, else a Unix domain socket
154 connection is attempted.
155 -p port
157 --port=port
158 Specifies the TCP port or local Unix domain socket file extension
159 on which the server is listening for connections. Defaults to the
160 PGPORT environment variable, if set, or a compiled-in default.
161 -U user
163 --username=user
164 User name to connect as. Defaults to current operating system user
165 name.
166 -w
168 --no-password
169 Never issue a password prompt. If the server requires password
170 authentication and a password is not available by other means such
171 as a .pgpass file, the connection attempt will fail. This option
172 can be useful in batch jobs and scripts where no user is present to
173 enter a password.
174 -W
176 --password
177 Force pg_recvlogical to prompt for a password before connecting to
178 a database.
179 This option is never essential, since pg_recvlogical will
181 automatically prompt for a password if the server demands password
182 authentication. However, pg_recvlogical will waste a connection
183 attempt finding out that the server wants a password. In some cases
184 it is worth typing -W to avoid the extra connection attempt.
185 The following additional options are available:
187 -V
189 --version
190 Print the pg_recvlogical version and exit.
191 -?
193 --help
194 Show help about pg_recvlogical command line arguments, and exit.
195
197 This utility, like most other PostgreSQL utilities, uses the
198 environment variables supported by libpq (see Section 34.15).
199 The environment variable PG_COLOR specifies whether to use color in
201 diagnostic messages. Possible values are always, auto and never.
202
204 pg_recvlogical will preserve group permissions on the received WAL
205 files if group permissions are enabled on the source cluster.
206
208 See Section 49.1 for an example.
209
211 pg_receivewal(1)
212PostgreSQL 15.4 2023 PG_RECVLOGICAL(1)