Debian Codegraph @

doc/src/sgml/ref/pg_recvlogical.sgml

raw
1 <!--
2 doc/src/sgml/ref/pg_recvlogical.sgml
3 PostgreSQL documentation
4 -->
5
6 <refentry id="app-pgrecvlogical">
7 <indexterm zone="app-pgrecvlogical">
8 <primary>pg_recvlogical</primary>
9 </indexterm>
10
11 <refmeta>
12 <refentrytitle><application>pg_recvlogical</application></refentrytitle>
13 <manvolnum>1</manvolnum>
14 <refmiscinfo>Application</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18 <refname>pg_recvlogical</refname>
19 <refpurpose>control <productname>PostgreSQL</productname> logical decoding streams</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23 <cmdsynopsis>
24 <command>pg_recvlogical</command>
25 <arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
26 </cmdsynopsis>
27 </refsynopsisdiv>
28
29 <refsect1>
30 <title>Description</title>
31 <para>
32 <command>pg_recvlogical</command> controls logical decoding replication
33 slots and streams data from such replication slots.
34 </para>
35
36 <para>
37 It creates a replication-mode connection, so it is subject to the same
38 constraints as <xref linkend="app-pgreceivewal"/>, plus those for logical
39 replication (see <xref linkend="logicaldecoding"/>).
40 </para>
41
42 <para>
43 <command>pg_recvlogical</command> has no equivalent to the logical decoding
44 SQL interface's peek and get modes. It sends replay confirmations for
45 data lazily as it receives it and on clean exit. To examine pending data on
46 a slot without consuming it, use
47 <link linkend="functions-replication"><function>pg_logical_slot_peek_changes</function></link>.
48 </para>
49
50 <para>
51 In the absence of fatal errors, <application>pg_recvlogical</application>
52 will run until terminated by the <systemitem>SIGINT</systemitem>
53 (<keycombo action="simul"><keycap>Control</keycap><keycap>C</keycap></keycombo>)
54 or <systemitem>SIGTERM</systemitem> signal.
55 </para>
56
57 <para>
58 When <application>pg_recvlogical</application> receives
59 a <systemitem>SIGHUP</systemitem> signal, it closes the current output file
60 and opens a new one using the filename specified by
61 the <option>--file</option> option. This allows us to rotate
62 the output file by first renaming the current file and then sending
63 a <systemitem>SIGHUP</systemitem> signal to
64 <application>pg_recvlogical</application>.
65 </para>
66 </refsect1>
67
68 <refsect1>
69 <title>Options</title>
70
71 <para>
72 At least one of the following options must be specified to select an action:
73
74 <variablelist>
75
76 <varlistentry>
77 <term><option>--create-slot</option></term>
78 <listitem>
79 <para>
80 Create a new logical replication slot with the name specified by
81 <option>--slot</option>, using the output plugin specified by
82 <option>--plugin</option>, for the database specified
83 by <option>--dbname</option>.
84 </para>
85
86 <para>
87 The <option>--slot</option> and <option>--dbname</option> are required
88 for this action.
89 </para>
90
91 <para>
92 The <option>--enable-two-phase</option> and <option>--enable-failover</option>
93 options can be specified with <option>--create-slot</option>.
94 </para>
95 </listitem>
96 </varlistentry>
97
98 <varlistentry>
99 <term><option>--drop-slot</option></term>
100 <listitem>
101 <para>
102 Drop the replication slot with the name specified
103 by <option>--slot</option>, then exit.
104 </para>
105
106 <para>
107 The <option>--slot</option> is required for this action.
108 </para>
109 </listitem>
110 </varlistentry>
111
112 <varlistentry>
113 <term><option>--start</option></term>
114 <listitem>
115 <para>
116 Begin streaming changes from the logical replication slot specified
117 by <option>--slot</option>, continuing until terminated by a
118 signal. If the server side change stream ends with a server shutdown
119 or disconnect, retry in a loop unless
120 <option>--no-loop</option> is specified.
121 </para>
122
123 <para>
124 The <option>--slot</option> and <option>--dbname</option>,
125 <option>--file</option> are required for this action.
126 </para>
127
128 <para>
129 The stream format is determined by the output plugin specified when
130 the slot was created.
131 </para>
132
133 <para>
134 The connection must be to the same database used to create the slot.
135 </para>
136 </listitem>
137 </varlistentry>
138 </variablelist>
139 </para>
140
141 <para>
142 <option>--create-slot</option> and <option>--start</option> can be
143 specified together. <option>--drop-slot</option> cannot be combined with
144 another action.
145 </para>
146
147 <para>
148 The following command-line options control the location and format of the
149 output and other replication behavior:
150
151 <variablelist>
152 <varlistentry>
153 <term><option>-E <replaceable>lsn</replaceable></option></term>
154 <term><option>--endpos=<replaceable>lsn</replaceable></option></term>
155 <listitem>
156 <para>
157 In <option>--start</option> mode, automatically stop replication
158 and exit with normal exit status 0 when receiving reaches the
159 specified LSN. If specified when not in <option>--start</option>
160 mode, an error is raised.
161 </para>
162
163 <para>
164 If there's a record with LSN exactly equal to <replaceable>lsn</replaceable>,
165 the record will be output.
166 </para>
167
168 <para>
169 The <option>--endpos</option> option is not aware of transaction
170 boundaries and may truncate output partway through a transaction.
171 Any partially output transaction will not be consumed and will be
172 replayed again when the slot is next read from. Individual messages
173 are never truncated.
174 </para>
175 </listitem>
176 </varlistentry>
177
178 <varlistentry>
179 <term><option>--enable-failover</option></term>
180 <listitem>
181 <para>
182 Enables the slot to be synchronized to the standbys. This option may
183 only be specified with <option>--create-slot</option>.
184 </para>
185 </listitem>
186 </varlistentry>
187
188 <varlistentry>
189 <term><option>-f <replaceable>filename</replaceable></option></term>
190 <term><option>--file=<replaceable>filename</replaceable></option></term>
191 <listitem>
192 <para>
193 Write received and decoded transaction data into this
194 file. Use <literal>-</literal> for <systemitem>stdout</systemitem>.
195 </para>
196 <para>
197 This parameter is required for <option>--start</option>.
198 </para>
199 </listitem>
200 </varlistentry>
201
202 <varlistentry>
203 <term><option>-F <replaceable>interval_seconds</replaceable></option></term>
204 <term><option>--fsync-interval=<replaceable>interval_seconds</replaceable></option></term>
205 <listitem>
206 <para>
207 Specifies how often <application>pg_recvlogical</application> should
208 issue <function>fsync()</function> calls to ensure the output file is
209 safely flushed to disk.
210 </para>
211
212 <para>
213 The server will occasionally request the client to perform a flush and
214 report the flush position to the server. This setting is in addition
215 to that, to perform flushes more frequently.
216 </para>
217
218 <para>
219 Specifying an interval of <literal>0</literal> disables
220 issuing <function>fsync()</function> calls altogether, while still
221 reporting progress to the server. In this case, data could be lost in
222 the event of a crash.
223 </para>
224 </listitem>
225 </varlistentry>
226
227 <varlistentry>
228 <term><option>-I <replaceable>lsn</replaceable></option></term>
229 <term><option>--startpos=<replaceable>lsn</replaceable></option></term>
230 <listitem>
231 <para>
232 In <option>--start</option> mode, start replication from the given
233 LSN. For details on the effect of this, see the documentation
234 in <xref linkend="logicaldecoding"/>
235 and <xref linkend="protocol-replication"/>. Ignored in other modes.
236 </para>
237 </listitem>
238 </varlistentry>
239
240 <varlistentry>
241 <term><option>--if-not-exists</option></term>
242 <listitem>
243 <para>
244 Do not error out when <option>--create-slot</option> is specified
245 and a slot with the specified name already exists.
246 </para>
247 </listitem>
248 </varlistentry>
249
250 <varlistentry>
251 <term><option>-n</option></term>
252 <term><option>--no-loop</option></term>
253 <listitem>
254 <para>
255 When the connection to the server is lost, do not retry in a loop, just exit.
256 </para>
257 </listitem>
258 </varlistentry>
259
260 <varlistentry>
261 <term><option>-o <replaceable>name</replaceable>[=<replaceable>value</replaceable>]</option></term>
262 <term><option>--option=<replaceable>name</replaceable>[=<replaceable>value</replaceable>]</option></term>
263 <listitem>
264 <para>
265 Pass the option <replaceable>name</replaceable> to the output plugin with,
266 if specified, the option value <replaceable>value</replaceable>. Which
267 options exist and their effects depends on the used output plugin.
268 </para>
269 </listitem>
270 </varlistentry>
271
272 <varlistentry>
273 <term><option>-P <replaceable>plugin</replaceable></option></term>
274 <term><option>--plugin=<replaceable>plugin</replaceable></option></term>
275 <listitem>
276 <para>
277 When creating a slot, use the specified logical decoding output
278 plugin. See <xref linkend="logicaldecoding"/>. This option has no
279 effect if the slot already exists.
280 </para>
281 </listitem>
282 </varlistentry>
283
284 <varlistentry>
285 <term><option>-s <replaceable>interval_seconds</replaceable></option></term>
286 <term><option>--status-interval=<replaceable>interval_seconds</replaceable></option></term>
287 <listitem>
288 <para>
289 This option has the same effect as the option of the same name
290 in <xref linkend="app-pgreceivewal"/>. See the description there.
291 </para>
292 </listitem>
293 </varlistentry>
294
295 <varlistentry>
296 <term><option>-S <replaceable>slot_name</replaceable></option></term>
297 <term><option>--slot=<replaceable>slot_name</replaceable></option></term>
298 <listitem>
299 <para>
300 In <option>--start</option> mode, use the existing logical replication slot named
301 <replaceable>slot_name</replaceable>. In <option>--create-slot</option>
302 mode, create the slot with this name. In <option>--drop-slot</option>
303 mode, delete the slot with this name.
304 </para>
305 <para>
306 This parameter is required for any of actions.
307 </para>
308 </listitem>
309 </varlistentry>
310
311 <varlistentry>
312 <term><option>-t</option></term>
313 <term><option>--enable-two-phase</option></term>
314 <term><option>--two-phase</option> (deprecated)</term>
315 <listitem>
316 <para>
317 Enables decoding of prepared transactions. This option may only be specified with
318 <option>--create-slot</option>.
319 </para>
320 </listitem>
321 </varlistentry>
322
323 <varlistentry>
324 <term><option>-v</option></term>
325 <term><option>--verbose</option></term>
326 <listitem>
327 <para>
328 Enables verbose mode.
329 </para>
330 </listitem>
331 </varlistentry>
332 </variablelist>
333 </para>
334
335 <para>
336 The following command-line options control the database connection parameters.
337
338 <variablelist>
339 <varlistentry>
340 <term><option>-d <replaceable>dbname</replaceable></option></term>
341 <term><option>--dbname=<replaceable>dbname</replaceable></option></term>
342 <listitem>
343 <para>
344 The database to connect to. See the description
345 of the actions for what this means in detail.
346 The <replaceable>dbname</replaceable> can be a <link
347 linkend="libpq-connstring">connection string</link>. If so,
348 connection string parameters will override any conflicting
349 command line options.
350 </para>
351 <para>
352 This parameter is required for <option>--create-slot</option>
353 and <option>--start</option>.
354 </para>
355 </listitem>
356 </varlistentry>
357
358 <varlistentry>
359 <term><option>-h <replaceable>hostname-or-ip</replaceable></option></term>
360 <term><option>--host=<replaceable>hostname-or-ip</replaceable></option></term>
361 <listitem>
362 <para>
363 Specifies the host name of the machine on which the server is
364 running. If the value begins with a slash, it is used as the
365 directory for the Unix domain socket. The default is taken
366 from the <envar>PGHOST</envar> environment variable, if set,
367 else a Unix domain socket connection is attempted.
368 </para>
369 </listitem>
370 </varlistentry>
371
372 <varlistentry>
373 <term><option>-p <replaceable>port</replaceable></option></term>
374 <term><option>--port=<replaceable>port</replaceable></option></term>
375 <listitem>
376 <para>
377 Specifies the TCP port or local Unix domain socket file
378 extension on which the server is listening for connections.
379 Defaults to the <envar>PGPORT</envar> environment variable, if
380 set, or a compiled-in default.
381 </para>
382 </listitem>
383 </varlistentry>
384
385 <varlistentry>
386 <term><option>-U <replaceable>user</replaceable></option></term>
387 <term><option>--username=<replaceable>user</replaceable></option></term>
388 <listitem>
389 <para>
390 User name to connect as. Defaults to current operating system user
391 name.
392 </para>
393 </listitem>
394 </varlistentry>
395
396 <varlistentry>
397 <term><option>-w</option></term>
398 <term><option>--no-password</option></term>
399 <listitem>
400 <para>
401 Never issue a password prompt. If the server requires
402 password authentication and a password is not available by
403 other means such as a <filename>.pgpass</filename> file, the
404 connection attempt will fail. This option can be useful in
405 batch jobs and scripts where no user is present to enter a
406 password.
407 </para>
408 </listitem>
409 </varlistentry>
410
411 <varlistentry>
412 <term><option>-W</option></term>
413 <term><option>--password</option></term>
414 <listitem>
415 <para>
416 Force <application>pg_recvlogical</application> to prompt for a
417 password before connecting to a database.
418 </para>
419
420 <para>
421 This option is never essential, since
422 <application>pg_recvlogical</application> will automatically prompt
423 for a password if the server demands password authentication.
424 However, <application>pg_recvlogical</application> will waste a
425 connection attempt finding out that the server wants a password.
426 In some cases it is worth typing <option>-W</option> to avoid the extra
427 connection attempt.
428 </para>
429 </listitem>
430 </varlistentry>
431 </variablelist>
432 </para>
433
434 <para>
435 The following additional options are available:
436
437 <variablelist>
438 <varlistentry>
439 <term><option>-V</option></term>
440 <term><option>--version</option></term>
441 <listitem>
442 <para>
443 Print the <application>pg_recvlogical</application> version and exit.
444 </para>
445 </listitem>
446 </varlistentry>
447
448 <varlistentry>
449 <term><option>-?</option></term>
450 <term><option>--help</option></term>
451 <listitem>
452 <para>
453 Show help about <application>pg_recvlogical</application> command line
454 arguments, and exit.
455 </para>
456 </listitem>
457 </varlistentry>
458 </variablelist>
459 </para>
460 </refsect1>
461
462 <refsect1>
463 <title>Exit Status</title>
464 <para>
465 <application>pg_recvlogical</application> will exit with status 0 when
466 terminated by the <systemitem>SIGINT</systemitem> or
467 <systemitem>SIGTERM</systemitem> signal. (That is the
468 normal way to end it. Hence it is not an error.) For fatal errors or
469 other signals, the exit status will be nonzero.
470 </para>
471 </refsect1>
472
473 <refsect1>
474 <title>Environment</title>
475
476 <para>
477 This utility, like most other <productname>PostgreSQL</productname> utilities,
478 uses the environment variables supported by <application>libpq</application>
479 (see <xref linkend="libpq-envars"/>).
480 </para>
481
482 <para>
483 The environment variable <envar>PG_COLOR</envar> specifies whether to use
484 color in diagnostic messages. Possible values are
485 <literal>always</literal>, <literal>auto</literal> and
486 <literal>never</literal>.
487 </para>
488 </refsect1>
489
490 <refsect1>
491 <title>Notes</title>
492
493 <para>
494 <application>pg_recvlogical</application> will preserve group permissions on
495 the output files if group permissions are enabled on the source
496 cluster.
497 </para>
498
499 </refsect1>
500
501 <refsect1>
502 <title>Examples</title>
503
504 <para>
505 See <xref linkend="logicaldecoding-example"/> for an example.
506 </para>
507 </refsect1>
508
509 <refsect1>
510 <title>See Also</title>
511
512 <simplelist type="inline">
513 <member><xref linkend="app-pgreceivewal"/></member>
514 </simplelist>
515 </refsect1>
516 </refentry>