← Back to branch summary

~ubuntu-branches/ubuntu/precise/postgresql-9.1/precise-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/ref/pg_ctl-ref.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/ref/pg_ctl-ref.sgml
 
1
<!--
 
2
doc/src/sgml/ref/pg_ctl-ref.sgml
 
3
PostgreSQL documentation
 
4
-->
 
5
 
 
6
<refentry id="app-pg-ctl">
 
7
 <refmeta>
 
8
  <refentrytitle><application>pg_ctl</application></refentrytitle>
 
9
  <manvolnum>1</manvolnum>
 
10
  <refmiscinfo>Application</refmiscinfo>
 
11
 </refmeta>
 
12
 
 
13
 <refnamediv>
 
14
  <refname>pg_ctl</refname>
 
15
  <refpurpose>initialize, start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
 
16
 </refnamediv>
 
17
 
 
18
 <indexterm zone="app-pg-ctl">
 
19
  <primary>pg_ctl</primary>
 
20
 </indexterm>
 
21
 
 
22
 <refsynopsisdiv>
 
23
  <cmdsynopsis>
 
24
   <command>pg_ctl</command>
 
25
   <arg choice="plain">init[db]</arg>
 
26
   <arg>-s</arg>
 
27
   <arg>-D <replaceable>datadir</replaceable></arg>
 
28
   <arg>-o <replaceable>initdb-options</replaceable></arg>
 
29
  </cmdsynopsis>
 
30
 
 
31
  <cmdsynopsis>
 
32
   <command>pg_ctl</command>
 
33
   <arg choice="plain">start</arg>
 
34
   <arg>-w</arg>
 
35
   <arg>-t <replaceable>seconds</replaceable></arg>
 
36
   <arg>-s</arg>
 
37
   <arg>-D <replaceable>datadir</replaceable></arg>
 
38
   <arg>-l <replaceable>filename</replaceable></arg>
 
39
   <arg>-o <replaceable>options</replaceable></arg>
 
40
   <arg>-p <replaceable>path</replaceable></arg>
 
41
   <arg>-c</arg>
 
42
  </cmdsynopsis>
 
43
 
 
44
  <cmdsynopsis>
 
45
   <command>pg_ctl</command>
 
46
   <arg choice="plain">stop</arg>
 
47
   <arg>-W</arg>
 
48
   <arg>-t <replaceable>seconds</replaceable></arg>
 
49
   <arg>-s</arg>
 
50
   <arg>-D <replaceable>datadir</replaceable></arg>
 
51
   <arg>-m
 
52
     <group choice="plain">
 
53
       <arg>s[mart]</arg>
 
54
       <arg>f[ast]</arg>
 
55
       <arg>i[mmediate]</arg>
 
56
     </group>
 
57
   </arg>
 
58
  </cmdsynopsis>
 
59
 
 
60
  <cmdsynopsis>
 
61
   <command>pg_ctl</command>
 
62
   <arg choice="plain">restart</arg>
 
63
   <arg>-w</arg>
 
64
   <arg>-t <replaceable>seconds</replaceable></arg>
 
65
   <arg>-s</arg>
 
66
   <arg>-D <replaceable>datadir</replaceable></arg>
 
67
   <arg>-c</arg>
 
68
   <arg>-m
 
69
     <group choice="plain">
 
70
       <arg>s[mart]</arg>
 
71
       <arg>f[ast]</arg>
 
72
       <arg>i[mmediate]</arg>
 
73
     </group>
 
74
   </arg>
 
75
   <arg>-o <replaceable>options</replaceable></arg>
 
76
  </cmdsynopsis>
 
77
 
 
78
  <cmdsynopsis>
 
79
   <command>pg_ctl</command>
 
80
   <arg choice="plain">promote</arg>
 
81
   <arg>-s</arg>
 
82
   <arg>-D <replaceable>datadir</replaceable></arg>
 
83
  </cmdsynopsis>
 
84
 
 
85
  <cmdsynopsis>
 
86
   <command>pg_ctl</command>
 
87
   <arg choice="plain">reload</arg>
 
88
   <arg>-s</arg>
 
89
   <arg>-D <replaceable>datadir</replaceable></arg>
 
90
  </cmdsynopsis>
 
91
 
 
92
  <cmdsynopsis>
 
93
   <command>pg_ctl</command>
 
94
   <arg choice="plain">status</arg>
 
95
   <arg>-D <replaceable>datadir</replaceable></arg>
 
96
  </cmdsynopsis>
 
97
 
 
98
  <cmdsynopsis>
 
99
   <command>pg_ctl</command>
 
100
   <arg choice="plain">kill</arg>
 
101
   <arg><replaceable>signal_name</replaceable></arg>
 
102
   <arg><replaceable>process_id</replaceable></arg>
 
103
  </cmdsynopsis>
 
104
 
 
105
  <cmdsynopsis>
 
106
   <command>pg_ctl</command>
 
107
   <arg choice="plain">register</arg>
 
108
   <arg>-N <replaceable>servicename</replaceable></arg>
 
109
   <arg>-U <replaceable>username</replaceable></arg>
 
110
   <arg>-P <replaceable>password</replaceable></arg>
 
111
   <arg>-D <replaceable>datadir</replaceable></arg>
 
112
   <arg>-S
 
113
     <group choice="plain">
 
114
       <arg>a[uto]</arg>
 
115
       <arg>d[emand]</arg>
 
116
     </group>
 
117
   </arg>
 
118
   <arg>-w</arg>
 
119
   <arg>-t <replaceable>seconds</replaceable></arg>
 
120
   <arg>-o <replaceable>options</replaceable></arg>
 
121
  </cmdsynopsis>
 
122
 
 
123
  <cmdsynopsis>
 
124
   <command>pg_ctl</command>
 
125
   <arg choice="plain">unregister</arg>
 
126
   <arg>-N <replaceable>servicename</replaceable></arg>
 
127
  </cmdsynopsis>
 
128
 </refsynopsisdiv>
 
129
 
 
130
 
 
131
 <refsect1 id="app-pg-ctl-description">
 
132
  <title>Description</title>
 
133
  <para>
 
134
   <application>pg_ctl</application> is a utility for initializing a
 
135
   <productname>PostgreSQL</productname> database cluster, starting,
 
136
   stopping, or restarting the <productname>PostgreSQL</productname>
 
137
   database server (<xref linkend="app-postgres">), or displaying the
 
138
   status of a running server.  Although the server can be started
 
139
   manually, <application>pg_ctl</application> encapsulates tasks such
 
140
   as redirecting log output and properly detaching from the terminal
 
141
   and process group. It also provides convenient options for
 
142
   controlled shutdown.
 
143
  </para>
 
144
 
 
145
  <para>
 
146
   The <option>init</option> or <option>initdb</option> mode creates a new
 
147
   <productname>PostgreSQL</productname> database cluster.  A database
 
148
   cluster is a collection of databases that are managed by a single
 
149
   server instance.  This mode invokes the <command>initdb</command>
 
150
   command.  See <xref linkend="app-initdb"> for details.
 
151
  </para>
 
152
 
 
153
  <para>
 
154
   In <option>start</option> mode, a new server is launched.  The
 
155
   server is started in the background, and its standard input is attached
 
156
   to <filename>/dev/null</filename> (or <literal>nul</> on Windows).
 
157
   On Unix-like systems, by default, the server's standard output and
 
158
   standard error are sent to <application>pg_ctl</application>'s
 
159
   standard output (not standard error).  The standard output of
 
160
   <application>pg_ctl</application> should then be redirected to a
 
161
   file or piped to another process such as a log rotating program
 
162
   like <application>rotatelogs</>; otherwise <command>postgres</command>
 
163
   will write its output to the controlling terminal (from the
 
164
   background) and will not leave the shell's process group.  On
 
165
   Windows, by default the server's standard output and standard error
 
166
   are sent to the terminal.  These default behaviors can be changed
 
167
   by using <option>-l</option> to append the server's output to a log file.
 
168
   Use of either <option>-l</option> or output redirection is recommended.
 
169
  </para>
 
170
 
 
171
  <para>
 
172
   In <option>stop</option> mode, the server that is running in
 
173
   the specified data directory is shut down.  Three different
 
174
   shutdown methods can be selected with the <option>-m</option>
 
175
   option.  <quote>Smart</quote> mode (the default) waits for all active
 
176
   clients to disconnect and any online backup to finish.
 
177
   If the server is in hot standby, recovery and streaming replication
 
178
   will be terminated once all clients have disconnected.
 
179
   <quote>Fast</quote> mode does not wait for clients to disconnect and
 
180
   will terminate an online backup in progress.  All active transactions are
 
181
   rolled back and clients are forcibly disconnected, then the
 
182
   server is shut down.  <quote>Immediate</quote> mode will abort
 
183
   all server processes immediately, without a clean shutdown.
 
184
   This will lead to a crash-recovery run on the next restart.
 
185
  </para>
 
186
 
 
187
  <para>
 
188
   <option>restart</option> mode effectively executes a stop followed
 
189
   by a start.  This allows changing the <command>postgres</command>
 
190
   command-line options.
 
191
  </para>
 
192
 
 
193
  <para>
 
194
   In <option>promote</option> mode, the standby server that is
 
195
   running in the specified data directory is commanded to exit
 
196
   recovery and begin read-write operations.
 
197
  </para>
 
198
 
 
199
  <para>
 
200
   <option>reload</option> mode simply sends the
 
201
   <command>postgres</command> process a <systemitem>SIGHUP</>
 
202
   signal, causing it to reread its configuration files
 
203
   (<filename>postgresql.conf</filename>,
 
204
   <filename>pg_hba.conf</filename>, etc.).  This allows changing of
 
205
   configuration-file options that do not require a complete restart
 
206
   to take effect.
 
207
  </para>
 
208
 
 
209
  <para>
 
210
   <option>status</option> mode checks whether a server is running in
 
211
   the specified data directory. If it is, the <acronym>PID</acronym>
 
212
   and the command line options that were used to invoke it are
 
213
   displayed.
 
214
  </para>
 
215
 
 
216
  <para>
 
217
   <option>kill</option> mode allows you to send a signal to a specified
 
218
    process.  This is particularly valuable for <productname>Microsoft Windows</>
 
219
    which does not have a <application>kill</> command.  Use
 
220
    <literal>--help</> to see a list of supported signal names.
 
221
  </para>
 
222
 
 
223
  <para>
 
224
   <option>register</option> mode allows you to register a system service
 
225
   on <productname>Microsoft Windows</>.  The <option>-S</option> option
 
226
   allows selection of service start type, either <quote>auto</quote> (start
 
227
   service automatically on system startup) or <quote>demand</quote> (start
 
228
   service on demand).
 
229
  </para>
 
230
 
 
231
  <para>
 
232
   <option>unregister</option> mode allows you to unregister a system service
 
233
   on <productname>Microsoft Windows</>.  This undoes the effects of the
 
234
   <option>register</option> command.
 
235
  </para>
 
236
 </refsect1>
 
237
 
 
238
 <refsect1 id="app-pg-ctl-options">
 
239
  <title>Options</title>
 
240
 
 
241
    <variablelist>
 
242
 
 
243
     <varlistentry>
 
244
      <term><option>-c</option></term>
 
245
      <listitem>
 
246
       <para>
 
247
        Attempt to allow server crashes to produce core files, on platforms
 
248
        where this is possible, by lifting any soft resource limit placed on
 
249
        core files.
 
250
        This is useful in debugging or diagnosing problems by allowing a
 
251
        stack trace to be obtained from a failed server process.
 
252
       </para>
 
253
      </listitem>
 
254
     </varlistentry>
 
255
 
 
256
     <varlistentry>
 
257
      <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
 
258
      <listitem>
 
259
       <para>
 
260
        Specifies the file system location of the database files.  If
 
261
        this is omitted, the environment variable
 
262
        <envar>PGDATA</envar> is used.
 
263
       </para>
 
264
      </listitem>
 
265
     </varlistentry>
 
266
 
 
267
     <varlistentry>
 
268
      <term><option>-l <replaceable class="parameter">filename</replaceable></option></term>
 
269
      <listitem>
 
270
       <para>
 
271
        Append the server log output to
 
272
        <replaceable>filename</replaceable>.  If the file does not
 
273
        exist, it is created.  The <systemitem>umask</> is set to 077,
 
274
        so access to the log file is disallowed to other users by default.
 
275
       </para>
 
276
      </listitem>
 
277
     </varlistentry>
 
278
 
 
279
     <varlistentry>
 
280
      <term><option>-m <replaceable class="parameter">mode</replaceable></option></term>
 
281
      <listitem>
 
282
       <para>
 
283
        Specifies the shutdown mode.  <replaceable>mode</replaceable>
 
284
        can be <literal>smart</literal>, <literal>fast</literal>, or
 
285
        <literal>immediate</literal>, or the first letter of one of
 
286
        these three.  If this is omitted, <literal>smart</literal> is used.
 
287
       </para>
 
288
      </listitem>
 
289
     </varlistentry>
 
290
 
 
291
     <varlistentry>
 
292
      <term><option>-o <replaceable class="parameter">options</replaceable></option></term>
 
293
      <listitem>
 
294
       <para>
 
295
        Specifies options to be passed directly to the
 
296
        <command>postgres</command> command.
 
297
       </para>
 
298
       <para>
 
299
        The options should usually be surrounded by single or double
 
300
        quotes to ensure that they are passed through as a group.
 
301
       </para>
 
302
      </listitem>
 
303
     </varlistentry>
 
304
 
 
305
     <varlistentry>
 
306
      <term><option>-o <replaceable class="parameter">initdb-options</replaceable></option></term>
 
307
      <listitem>
 
308
       <para>
 
309
        Specifies options to be passed directly to the
 
310
        <command>initdb</command> command.
 
311
       </para>
 
312
       <para>
 
313
        The options should usually be surrounded by single or double
 
314
        quotes to ensure that they are passed through as a group.
 
315
       </para>
 
316
      </listitem>
 
317
     </varlistentry>
 
318
 
 
319
     <varlistentry>
 
320
      <term><option>-p <replaceable class="parameter">path</replaceable></option></term>
 
321
      <listitem>
 
322
       <para>
 
323
        Specifies the location of the <filename>postgres</filename>
 
324
        executable.  By default the <filename>postgres</filename> executable is taken from the same
 
325
        directory as <command>pg_ctl</command>, or failing that, the hard-wired
 
326
        installation directory.  It is not necessary to use this
 
327
        option unless you are doing something unusual and get errors
 
328
        that the <filename>postgres</filename> executable was not found.
 
329
       </para>
 
330
 
 
331
       <para>
 
332
        In <literal>init</literal> mode, this option analogously
 
333
        specifies the location of the <filename>initdb</filename>
 
334
        executable.
 
335
       </para>
 
336
      </listitem>
 
337
     </varlistentry>
 
338
 
 
339
     <varlistentry>
 
340
      <term><option>-s</option></term>
 
341
      <listitem>
 
342
       <para>
 
343
        Print only errors, no informational messages.
 
344
       </para>
 
345
      </listitem>
 
346
     </varlistentry>
 
347
 
 
348
     <varlistentry>
 
349
      <term><option>-t</option></term>
 
350
      <listitem>
 
351
       <para>
 
352
        The maximum number of seconds to wait when waiting for startup or
 
353
        shutdown to complete.  The default is 60 seconds.
 
354
       </para>
 
355
      </listitem>
 
356
     </varlistentry>
 
357
 
 
358
     <varlistentry>
 
359
      <term><option>-w</option></term>
 
360
      <listitem>
 
361
       <para>
 
362
        Wait for the startup or shutdown to complete.
 
363
        Waiting is the default option for shutdowns, but not startups.
 
364
        When waiting for startup, <command>pg_ctl</command> repeatedly
 
365
        attempts to connect to the server.
 
366
        When waiting for shutdown, <command>pg_ctl</command> waits for
 
367
        the server to remove its <acronym>PID</acronym> file.
 
368
        <command>pg_ctl</command> returns an exit code based on the
 
369
        success of the startup or shutdown.
 
370
       </para>
 
371
      </listitem>
 
372
     </varlistentry>
 
373
 
 
374
     <varlistentry>
 
375
      <term><option>-W</option></term>
 
376
      <listitem>
 
377
       <para>
 
378
        Do not wait for startup or shutdown to complete.  This is the
 
379
        default for start and restart modes.
 
380
       </para>
 
381
      </listitem>
 
382
     </varlistentry>
 
383
   </variablelist>
 
384
 
 
385
  <refsect2 id="app-pg-ctl-windows-options">
 
386
   <title>Options for Windows</title>
 
387
 
 
388
   <variablelist>
 
389
    <varlistentry>
 
390
     <term><option>-N <replaceable class="parameter">servicename</replaceable></option></term>
 
391
     <listitem>
 
392
      <para>
 
393
       Name of the system service to register. The name will be used
 
394
       as both the service name and the display name.
 
395
      </para>
 
396
     </listitem>
 
397
    </varlistentry>
 
398
 
 
399
    <varlistentry>
 
400
     <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
 
401
     <listitem>
 
402
      <para>
 
403
       User name for the user to start the service. For domain users, use the
 
404
       format <literal>DOMAIN\username</literal>.
 
405
      </para>
 
406
     </listitem>
 
407
    </varlistentry>
 
408
 
 
409
    <varlistentry>
 
410
     <term><option>-P <replaceable class="parameter">password</replaceable></option></term>
 
411
     <listitem>
 
412
      <para>
 
413
       Password for the user to start the service.
 
414
      </para>
 
415
     </listitem>
 
416
    </varlistentry>
 
417
 
 
418
    <varlistentry>
 
419
     <term><option>-S <replaceable class="parameter">start-type</replaceable></option></term>
 
420
     <listitem>
 
421
      <para>
 
422
       Start type of the system service to register.  start-type can
 
423
       be <literal>auto</literal>, or <literal>demand</literal>, or
 
424
       the first letter of one of these two. If this is omitted,
 
425
       <literal>auto</literal> is used.
 
426
      </para>
 
427
     </listitem>
 
428
    </varlistentry>
 
429
   </variablelist>
 
430
  </refsect2>
 
431
 
 
432
 </refsect1>
 
433
 
 
434
 
 
435
 <refsect1>
 
436
  <title>Environment</title>
 
437
 
 
438
  <variablelist>
 
439
   <varlistentry>
 
440
    <term><envar>PGDATA</envar></term>
 
441
 
 
442
    <listitem>
 
443
     <para>
 
444
      Default data directory location.
 
445
     </para>
 
446
    </listitem>
 
447
   </varlistentry>
 
448
 
 
449
  </variablelist>
 
450
 
 
451
  <para>
 
452
   <command>pg_ctl</command>, like most other <productname>PostgreSQL</>
 
453
   utilities,
 
454
   also uses the environment variables supported by <application>libpq</>
 
455
   (see <xref linkend="libpq-envars">).
 
456
   For additional server variables, see <xref linkend="app-postgres">.
 
457
  </para>
 
458
 </refsect1>
 
459
 
 
460
 
 
461
 <refsect1>
 
462
  <title>Files</title>
 
463
 
 
464
  <variablelist>
 
465
   <varlistentry>
 
466
    <term><filename>postmaster.pid</filename></term>
 
467
 
 
468
    <listitem>
 
469
     <para>
 
470
      The existence of this file in the data directory is used to help
 
471
      <application>pg_ctl</application> determine if the server is
 
472
      currently running.
 
473
     </para>
 
474
    </listitem>
 
475
   </varlistentry>
 
476
 
 
477
   <varlistentry>
 
478
    <term><filename>postmaster.opts</filename></term>
 
479
 
 
480
    <listitem>
 
481
     <para>If this file exists in the data directory,
 
482
      <application>pg_ctl</application> (in <option>restart</option> mode)
 
483
      will pass the contents of the file as options to
 
484
      <application>postgres</application>, unless overridden
 
485
      by the <option>-o</option> option. The contents of this file
 
486
      are also displayed in <option>status</option> mode.
 
487
     </para>
 
488
    </listitem>
 
489
   </varlistentry>
 
490
 
 
491
  </variablelist>
 
492
 </refsect1>
 
493
 
 
494
 
 
495
 <refsect1 id="R1-APP-PGCTL-2">
 
496
  <title>Examples</title>
 
497
 
 
498
  <refsect2 id="R2-APP-PGCTL-3">
 
499
   <title>Starting the Server</title>
 
500
 
 
501
   <para>
 
502
    To start the server:
 
503
<screen>
 
504
<prompt>$</prompt> <userinput>pg_ctl start</userinput>
 
505
</screen>
 
506
   </para>
 
507
 
 
508
   <para>
 
509
    To start the server, waiting until the server is
 
510
    accepting connections:
 
511
<screen>
 
512
<prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
 
513
</screen>
 
514
   </para>
 
515
 
 
516
   <para>
 
517
    To start the server using port 5433, and
 
518
    running without <function>fsync</function>, use:
 
519
<screen>
 
520
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
 
521
</screen>
 
522
   </para>
 
523
  </refsect2>
 
524
 
 
525
  <refsect2 id="R2-APP-PGCTL-4">
 
526
   <title>Stopping the Server</title>
 
527
   <para>
 
528
    To stop the server, use:
 
529
<screen>
 
530
<prompt>$</prompt> <userinput>pg_ctl stop</userinput>
 
531
</screen>
 
532
    The <option>-m</option> option allows control over
 
533
    <emphasis>how</emphasis> the server shuts down:
 
534
<screen>
 
535
<prompt>$</prompt> <userinput>pg_ctl stop -m fast</userinput>
 
536
</screen>
 
537
   </para>
 
538
  </refsect2>
 
539
 
 
540
  <refsect2 id="R2-APP-PGCTL-5">
 
541
   <title>Restarting the Server</title>
 
542
 
 
543
   <para>
 
544
    Restarting the server is almost equivalent to stopping the
 
545
    server and starting it again,
 
546
    except that <command>pg_ctl</command> saves and reuses the command line options that
 
547
    were passed to the previously running instance.  To restart
 
548
    the server in the simplest form, use:
 
549
<screen>
 
550
<prompt>$</prompt> <userinput>pg_ctl restart</userinput>
 
551
</screen>
 
552
   </para>
 
553
 
 
554
   <para>
 
555
    To restart the server,
 
556
    waiting for it to shut down and restart:
 
557
<screen>
 
558
<prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
 
559
</screen>
 
560
   </para>
 
561
 
 
562
   <para>
 
563
    To restart using port 5433, disabling <function>fsync</> upon restart:
 
564
<screen>
 
565
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
 
566
</screen>
 
567
   </para>
 
568
  </refsect2>
 
569
 
 
570
  <refsect2 id="R2-APP-PGCTL-6">
 
571
   <title>Showing the Server Status</title>
 
572
 
 
573
   <para>
 
574
    Here is sample status output from
 
575
    <application>pg_ctl</application>:
 
576
<screen>
 
577
<prompt>$</prompt> <userinput>pg_ctl status</userinput>
 
578
<computeroutput>
 
579
pg_ctl: server is running (PID: 13718)
 
580
/usr/local/pgsql/bin/postgres "-D" "/usr/local/pgsql/data" "-p" "5433" "-B" "128"
 
581
</computeroutput>
 
582
</screen>
 
583
    This is the command line that would be invoked in restart mode.
 
584
   </para>
 
585
  </refsect2>
 
586
 </refsect1>
 
587
 
 
588
 
 
589
 <refsect1>
 
590
  <title>See Also</title>
 
591
 
 
592
  <simplelist type="inline">
 
593
   <member><xref linkend="app-initdb"></member>
 
594
   <member><xref linkend="app-postgres"></member>
 
595
  </simplelist>
 
596
 </refsect1>
 
597
 
 
598
</refentry>