← Back to branch summary

~ubuntu-branches/ubuntu/utopic/postgresql-9.4/utopic-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/ref/pg_recvlogical.sgml

  • Committer: Package Import Robot
  • Author(s): Martin Pitt, CVE-2014-8161
  • Date: 2015-02-06 12:31:46 UTC
  • mfrom: (1.1.5) (7.1.2 utopic-proposed)
  • Revision ID: package-import@ubuntu.com-20150206123146-vtmf30jbkm7w16p8
Tags: 9.4.1-0ubuntu0.14.10
https://launchpad.net/bugs/1418928
* New upstream security/bug fix release (LP: #1418928)
  - Fix buffer overruns in to_char() [CVE-2015-0241]
  - Fix buffer overruns in contrib/pgcrypto [CVE-2015-0243]
  - Fix possible loss of frontend/backend protocol synchronization after an
    error [CVE-2015-0244]
  - Fix information leak via constraint-violation error messages
    [CVE-2014-8161]
  - See release notes for details about other fixes:
    http://www.postgresql.org/about/news/1569/

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/ref/pg_recvlogical.sgml
16
16
 
17
17
 <refnamediv>
18
18
  <refname>pg_recvlogical</refname>
19
 
  <refpurpose>Control logical decoding (see <xref linkend="logicaldecoding">)
20
 
   streams over a walsender connection.</refpurpose>
 
19
  <refpurpose>control <productname>PostgreSQL</productname> logical decoding streams</refpurpose>
21
20
 </refnamediv>
22
21
 
23
22
 <refsynopsisdiv>
24
23
  <cmdsynopsis>
25
24
   <command>pg_recvlogical</command>
26
 
   <arg rep="repeat" choice="opt"><option>option</option></arg>
 
25
   <arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
27
26
  </cmdsynopsis>
28
27
 </refsynopsisdiv>
29
28
 
30
 
 <refsect1 id="R1-APP-PGRECVLOGICAL-1">
 
29
 <refsect1>
31
30
  <title>Description</title>
32
31
  <para>
33
32
   <command>pg_recvlogical</command> controls logical decoding replication
34
33
   slots and streams data from such replication slots.
35
34
  </para>
 
35
 
36
36
  <para>
37
37
   It creates a replication-mode connection, so it is subject to the same
38
 
   constraints as <link
39
 
   linkend="app-pgreceivexlog"><application>pg_receivexlog</application></link>,
40
 
   plus those for logical replication (see <xref
41
 
   linkend="logicaldecoding">).
 
38
   constraints as <xref linkend="app-pgreceivexlog">, plus those for logical
 
39
   replication (see <xref linkend="logicaldecoding">).
42
40
  </para>
43
 
 
44
41
 </refsect1>
45
42
 
46
43
 <refsect1>
47
44
  <title>Options</title>
48
45
 
49
46
   <para>
50
 
    <application>pg_recvlogical</application> runs in one of three modes, which
51
 
    control its primary action:
 
47
    At least one of the following options must be specified to select an action:
52
48
 
53
49
    <variablelist>
54
50
 
56
52
      <term><option>--create-slot</option></term>
57
53
      <listitem>
58
54
       <para>
59
 
        Create a new logical replication slot with the name specified in
60
 
        <option>--slot</option>, using the output plugin
61
 
        <option>--plugin</option>, then exit. The slot is created for the
62
 
        database given in <option>--dbname</option>.
63
 
       </para>
64
 
      </listitem>
65
 
     </varlistentry>
66
 
 
67
 
     <varlistentry>
68
 
      <term><option>--start</option></term>
69
 
      <listitem>
70
 
       <para>
71
 
        Begin streaming changes from the logical replication slot with the name
72
 
        specified in <option>--slot</option>, continuing until terminated with a
73
 
        signal. If the server side change stream ends with a server
74
 
        shutdown or disconnect, retry in a loop unless
75
 
        <option>--no-loop</option> is specified. The stream format is
76
 
        determined by the output plugin specified when the slot was created.
77
 
       </para>
78
 
       <para>
79
 
        You must connect to the same database used to create the slot.
 
55
        Create a new logical replication slot with the name specified by
 
56
        <option>--slot</option>, using the output plugin specified by
 
57
        <option>--plugin</option>, for the database specified
 
58
        by <option>--dbname</option>.
80
59
       </para>
81
60
      </listitem>
82
61
     </varlistentry>
86
65
      <listitem>
87
66
       <para>
88
67
        Drop the replication slot with the name specified
89
 
        in <option>--slot</option>, then exit.
 
68
        by <option>--slot</option>, then exit.
 
69
       </para>
 
70
      </listitem>
 
71
     </varlistentry>
 
72
 
 
73
     <varlistentry>
 
74
      <term><option>--start</option></term>
 
75
      <listitem>
 
76
       <para>
 
77
        Begin streaming changes from the logical replication slot specified
 
78
        by <option>--slot</option>, continuing until terminated by a
 
79
        signal. If the server side change stream ends with a server shutdown
 
80
        or disconnect, retry in a loop unless
 
81
        <option>--no-loop</option> is specified.
 
82
       </para>
 
83
 
 
84
       <para>
 
85
        The stream format is determined by the output plugin specified when
 
86
        the slot was created.
 
87
       </para>
 
88
 
 
89
       <para>
 
90
        The connection must be to the same database used to create the slot.
90
91
       </para>
91
92
      </listitem>
92
93
     </varlistentry>
93
94
    </variablelist>
94
 
 
95
95
   </para>
96
96
 
97
97
   <para>
98
 
    <application>pg_recvlogical</application> supports all the usual
99
 
    <literal>libpq</literal>-based options. These are explained in detail in
100
 
    the documentation for
101
 
    <link linkend="APP-PSQL"><application>psql</application></link> and for
102
 
    <link linkend="libpq"><literal>libpq</literal></link>.
103
 
 
104
 
    <variablelist>
105
 
 
106
 
      <varlistentry>
107
 
       <term><option>-U <replaceable>user</replaceable></option></term>
108
 
       <term><option>--username <replaceable>user</replaceable></option></term>
109
 
       <listitem>
110
 
        <para>
111
 
         Username to connect as. Must have a suitable <literal>pg_hba.conf</literal>
112
 
         entry allowing <literal>replication</literal> connections. Defaults to
113
 
         current operating system user name.
114
 
        </para>
115
 
       </listitem>
116
 
      </varlistentry>
117
 
 
118
 
      <varlistentry>
119
 
       <term><option>-d <replaceable>database</replaceable></option></term>
120
 
       <term><option>--dbname <replaceable>database</replaceable></option></term>
121
 
       <listitem>
122
 
        <para>
123
 
         The database to connect to in <literal>replication</literal> mode; see
124
 
         mode descriptions for details. May be
125
 
         a <link linkend="LIBPQ-CONNSTRING">libpq connstring</link>
126
 
         instead. Defaults to user name.
127
 
        </para>
128
 
       </listitem>
129
 
      </varlistentry>
130
 
 
131
 
      <varlistentry>
132
 
       <term><option>-h <replaceable>hostname-or-ip</replaceable></option></term>
133
 
       <term><option>--host <replaceable>hostname-or-ip</replaceable></option></term>
134
 
       <listitem>
135
 
        <para>
136
 
         Host or socket to connect
137
 
         to. See <link linkend="APP-PSQL"><application>psql</application></link>
138
 
         and <link linkend="libpq"><literal>libpq</literal></link>
139
 
         documentation.
140
 
        </para>
141
 
       </listitem>
142
 
      </varlistentry>
143
 
 
144
 
      <varlistentry>
145
 
       <term><option>-p <replaceable>port</replaceable></option></term>
146
 
       <term><option>--port <replaceable>port</replaceable></option></term>
147
 
       <listitem>
148
 
        <para>
149
 
         Port number to connect to. See
150
 
         <link linkend="R1-APP-PSQL-3"><application>psql</application></link>
151
 
         for an explanation of default port choices when this is not
152
 
         specified.
153
 
        </para>
154
 
       </listitem>
155
 
      </varlistentry>
156
 
 
157
 
      <varlistentry>
158
 
       <term><option>-w</option></term>
159
 
       <term><option>--no-password</option></term>
160
 
       <listitem>
161
 
        <para>
162
 
         Prevent prompting for a password. Will exit with an error code if a
163
 
         password is required but not available.
164
 
        </para>
165
 
       </listitem>
166
 
      </varlistentry>
167
 
 
168
 
      <varlistentry>
169
 
       <term><option>-W</option></term>
170
 
       <term><option>--password</option></term>
171
 
       <listitem>
172
 
        <para>
173
 
         Provide a password for this connection. Please use the pgservice file
174
 
         (see <xref linkend="libpq-pgservice">) or an environment variable
175
 
         instead of this option.
176
 
        </para>
177
 
       </listitem>
178
 
      </varlistentry>
179
 
 
180
 
     </variablelist>
181
 
 
 
98
    <option>--create-slot</option> and <option>--start</option> can be
 
99
    specified together.  <option>--drop-slot</option> cannot be combined with
 
100
    another action.
182
101
   </para>
183
102
 
184
103
   <para>
186
105
    output and other replication behavior:
187
106
 
188
107
    <variablelist>
189
 
 
190
108
     <varlistentry>
191
109
      <term><option>-f <replaceable>filename</replaceable></option></term>
192
110
      <term><option>--file=<replaceable>filename</replaceable></option></term>
198
116
      </listitem>
199
117
     </varlistentry>
200
118
 
 
119
     <varlistentry>
 
120
      <term><option>-F <replaceable>interval_seconds</replaceable></option></term>
 
121
      <term><option>--fsync-interval=<replaceable>interval_seconds</replaceable></option></term>
 
122
      <listitem>
 
123
       <para>
 
124
        Specifies how often <application>pg_recvlogical</application> should
 
125
        issue <function>fsync()</function> calls to ensure the output file is
 
126
        safely flushed to disk.
 
127
       </para>
 
128
 
 
129
       <para>
 
130
        The server will occasionally request the client to perform a flush and
 
131
        report the flush position to the server.  This setting is in addition
 
132
        to that, to perform flushes more frequently.
 
133
       </para>
 
134
 
 
135
       <para>
 
136
        Specifying an interval of <literal>0</literal> disables
 
137
        issuing <function>fsync()</function> calls altogether, while still
 
138
        reporting progress to the server.  In this case, data could be lost in
 
139
        the event of a crash.
 
140
       </para>
 
141
      </listitem>
 
142
     </varlistentry>
 
143
 
 
144
     <varlistentry>
 
145
      <term><option>-I <replaceable>lsn</replaceable></option></term>
 
146
      <term><option>--startpos=<replaceable>lsn</replaceable></option></term>
 
147
      <listitem>
 
148
       <para>
 
149
        In <option>--start</option> mode, start replication from the given
 
150
        LSN.  For details on the effect of this, see the documentation
 
151
        in <xref linkend="logicaldecoding">
 
152
        and <xref linkend="protocol-replication">. Ignored in other modes.
 
153
       </para>
 
154
      </listitem>
 
155
     </varlistentry>
201
156
 
202
157
     <varlistentry>
203
158
      <term><option>-n</option></term>
210
165
     </varlistentry>
211
166
 
212
167
     <varlistentry>
213
 
      <term><option>-o <replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
214
 
      <term><option>--option=<replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
 
168
      <term><option>-o <replaceable>name</replaceable>[=<replaceable>value</replaceable>]</option></term>
 
169
      <term><option>--option=<replaceable>name</replaceable>[=<replaceable>value</replaceable>]</option></term>
215
170
      <listitem>
216
171
       <para>
217
 
        Pass the option <parameter>NAME</parameter> to the output plugin with,
218
 
        if specified, the option value <parameter>NAME</parameter>. Which
 
172
        Pass the option <replaceable>name</replaceable> to the output plugin with,
 
173
        if specified, the option value <replaceable>value</replaceable>. Which
219
174
        options exist and their effects depends on the used output plugin.
220
175
       </para>
221
176
      </listitem>
222
177
     </varlistentry>
223
178
 
224
179
     <varlistentry>
225
 
      <term><option>-F <replaceable>interval_seconds</replaceable></option></term>
226
 
      <term><option>--fsync-interval=<replaceable>interval_seconds</replaceable></option></term>
227
 
      <listitem>
228
 
       <para>
229
 
        How often should <application>pg_recvlogical</application> issue sync
230
 
        commands to ensure the <parameter>--outputfile</parameter> is safely
231
 
        flushed to disk without being asked by the server to do so. Specifying
232
 
        an interval of <literal>0</literal> disables issuing fsyncs altogether,
233
 
        while still reporting progress the server.  In this case, data may be
234
 
        lost in the event of a crash.
235
 
       </para>
236
 
      </listitem>
237
 
     </varlistentry>
238
 
 
239
 
     <varlistentry>
240
180
      <term><option>-P <replaceable>plugin</replaceable></option></term>
241
181
      <term><option>--plugin=<replaceable>plugin</replaceable></option></term>
242
182
      <listitem>
243
183
       <para>
244
 
        When creating a slot, use the logical decoding output
 
184
        When creating a slot, use the specified logical decoding output
245
185
        plugin. See <xref linkend="logicaldecoding">. This option has no
246
186
        effect if the slot already exists.
247
187
       </para>
253
193
      <term><option>--status-interval=<replaceable>interval_seconds</replaceable></option></term>
254
194
      <listitem>
255
195
       <para>
256
 
        This option has the same effect as the option of the same name in <link
257
 
        linkend="app-pgreceivexlog"><application>pg_receivexlog</application></link>.
258
 
        See the description there.
 
196
        This option has the same effect as the option of the same name
 
197
        in <xref linkend="app-pgreceivexlog">.  See the description there.
259
198
       </para>
260
199
      </listitem>
261
200
     </varlistentry>
274
213
     </varlistentry>
275
214
 
276
215
     <varlistentry>
277
 
      <term><option>-I <replaceable>lsn</replaceable></option></term>
278
 
      <term><option>--startpos=<replaceable>lsn</replaceable></option></term>
279
 
      <listitem>
280
 
       <para>
281
 
        In <option>--start</option> mode, start replication from the given
282
 
        LSN.  For details on the effect of this, see the documentation
283
 
        in <xref linkend="logicaldecoding">
284
 
        and <xref linkend="protocol-replication">. Ignored in other modes.
285
 
       </para>
286
 
      </listitem>
287
 
     </varlistentry>
288
 
    </variablelist>
289
 
 
290
 
   </para>
291
 
 
292
 
   <para>
293
 
    The following additional options are available:
294
 
 
295
 
    <variablelist>
296
 
 
297
 
     <varlistentry>
298
216
       <term><option>-v</></term>
299
217
       <term><option>--verbose</></term>
300
218
       <listitem>
303
221
       </para>
304
222
       </listitem>
305
223
     </varlistentry>
306
 
 
 
224
    </variablelist>
 
225
   </para>
 
226
 
 
227
   <para>
 
228
    The following command-line options control the database connection parameters.
 
229
 
 
230
    <variablelist>
 
231
      <varlistentry>
 
232
       <term><option>-d <replaceable>database</replaceable></option></term>
 
233
       <term><option>--dbname=<replaceable>database</replaceable></option></term>
 
234
       <listitem>
 
235
        <para>
 
236
         The database to connect to.  See the description of the actions for
 
237
         what this means in detail.  This can be a libpq connection string;
 
238
         see <xref linkend="LIBPQ-CONNSTRING"> for more information.  Defaults
 
239
         to user name.
 
240
        </para>
 
241
       </listitem>
 
242
      </varlistentry>
 
243
 
 
244
      <varlistentry>
 
245
       <term><option>-h <replaceable>hostname-or-ip</replaceable></option></term>
 
246
       <term><option>--host=<replaceable>hostname-or-ip</replaceable></option></term>
 
247
       <listitem>
 
248
        <para>
 
249
         Specifies the host name of the machine on which the server is
 
250
         running.  If the value begins with a slash, it is used as the
 
251
         directory for the Unix domain socket. The default is taken
 
252
         from the <envar>PGHOST</envar> environment variable, if set,
 
253
         else a Unix domain socket connection is attempted.
 
254
        </para>
 
255
       </listitem>
 
256
      </varlistentry>
 
257
 
 
258
      <varlistentry>
 
259
       <term><option>-p <replaceable>port</replaceable></option></term>
 
260
       <term><option>--port=<replaceable>port</replaceable></option></term>
 
261
       <listitem>
 
262
        <para>
 
263
         Specifies the TCP port or local Unix domain socket file
 
264
         extension on which the server is listening for connections.
 
265
         Defaults to the <envar>PGPORT</envar> environment variable, if
 
266
         set, or a compiled-in default.
 
267
        </para>
 
268
       </listitem>
 
269
      </varlistentry>
 
270
 
 
271
      <varlistentry>
 
272
       <term><option>-U <replaceable>user</replaceable></option></term>
 
273
       <term><option>--username=<replaceable>user</replaceable></option></term>
 
274
       <listitem>
 
275
        <para>
 
276
         Username to connect as.  Defaults to current operating system user
 
277
         name.
 
278
        </para>
 
279
       </listitem>
 
280
      </varlistentry>
 
281
 
 
282
      <varlistentry>
 
283
       <term><option>-w</option></term>
 
284
       <term><option>--no-password</option></term>
 
285
       <listitem>
 
286
        <para>
 
287
         Never issue a password prompt.  If the server requires
 
288
         password authentication and a password is not available by
 
289
         other means such as a <filename>.pgpass</filename> file, the
 
290
         connection attempt will fail.  This option can be useful in
 
291
         batch jobs and scripts where no user is present to enter a
 
292
         password.
 
293
        </para>
 
294
       </listitem>
 
295
      </varlistentry>
 
296
 
 
297
      <varlistentry>
 
298
       <term><option>-W</option></term>
 
299
       <term><option>--password</option></term>
 
300
       <listitem>
 
301
        <para>
 
302
         Force <application>pg_recvlogical</application> to prompt for a
 
303
         password before connecting to a database.
 
304
        </para>
 
305
 
 
306
        <para>
 
307
         This option is never essential, since
 
308
         <application>pg_recvlogical</application> will automatically prompt
 
309
         for a password if the server demands password authentication.
 
310
         However, <application>pg_recvlogical</application> will waste a
 
311
         connection attempt finding out that the server wants a password.
 
312
         In some cases it is worth typing <option>-W</> to avoid the extra
 
313
         connection attempt.
 
314
        </para>
 
315
      </listitem>
 
316
     </varlistentry>
 
317
     </variablelist>
 
318
   </para>
 
319
 
 
320
   <para>
 
321
    The following additional options are available:
 
322
 
 
323
    <variablelist>
307
324
     <varlistentry>
308
325
       <term><option>-V</></term>
309
326
       <term><option>--version</></term>
324
341
        </para>
325
342
       </listitem>
326
343
      </varlistentry>
327
 
 
328
344
    </variablelist>
329
345
   </para>
330
346
 </refsect1>
 
347
 
 
348
 <refsect1>
 
349
  <title>Environment</title>
 
350
 
 
351
  <para>
 
352
   This utility, like most other <productname>PostgreSQL</> utilities,
 
353
   uses the environment variables supported by <application>libpq</>
 
354
   (see <xref linkend="libpq-envars">).
 
355
  </para>
 
356
 </refsect1>
 
357
 
 
358
 <refsect1>
 
359
  <title>Examples</title>
 
360
 
 
361
  <para>
 
362
   See <xref linkend="logicaldecoding-example"> for an example.
 
363
  </para>
 
364
 </refsect1>
 
365
 
 
366
 <refsect1>
 
367
  <title>See Also</title>
 
368
 
 
369
  <simplelist type="inline">
 
370
   <member><xref linkend="app-pgreceivexlog"></member>
 
371
  </simplelist>
 
372
 </refsect1>
331
373
</refentry>