postgres-ref.sgml 15.2 KB
Newer Older
1
<!--
2
$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.44 2004/10/08 01:36:32 tgl Exp $
3
PostgreSQL documentation
4 5
-->

Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
6 7
<refentry id="APP-POSTGRES">
 <refmeta>
8 9
  <refentrytitle id="APP-POSTGRES-TITLE"><application>postgres</application></refentrytitle>
  <manvolnum>1</manvolnum>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
10 11
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>
12

Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
13
 <refnamediv>
14
  <refname>postgres</refname>
15
  <refpurpose>run a <productname>PostgreSQL</productname> server in single-user mode</refpurpose>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
16
 </refnamediv>
17

Peter Eisentraut's avatar
Peter Eisentraut committed
18 19 20 21
 <indexterm zone="app-postgres">
  <primary>postgres (the program)</primary>
 </indexterm>

Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
22
 <refsynopsisdiv>
23 24 25 26 27 28 29
  <cmdsynopsis>
   <!-- standalone call -->
   <command>postgres</command>
   <arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
   <arg>-B <replaceable>nbuffers</replaceable></arg>
   <arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
   <arg>-d <replaceable>debug-level</replaceable></arg>
30
   <arg>--describe-config</arg>
31 32 33 34 35 36
   <arg>-D <replaceable>datadir</replaceable></arg>
   <arg>-e</arg>
   <arg>-E</arg>
   <arg>-f<group choice="plain"><arg>s</arg><arg>i</arg><arg>t</arg><arg>n</arg><arg>m</arg><arg>h</arg></group></arg>
   <arg>-F</arg>
   <arg>-N</arg>
37
   <arg>-o <replaceable>filename</replaceable></arg>
38 39 40 41 42 43
   <arg>-O</arg>
   <arg>-P</arg>
   <group>
    <arg>-s</arg>
    <arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
   </group>
44
   <arg>-S <replaceable>work-mem</replaceable></arg>
45
   <arg>-W <replaceable>seconds</replaceable></arg>
46
   <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
47 48 49 50 51 52 53 54 55 56 57 58
   <arg choice="plain"><replaceable>database</replaceable></arg>
   <sbr>
   <!-- postmaster fork -->
   <command>postgres</command>
   <arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
   <arg>-B <replaceable>nbuffers</replaceable></arg>
   <arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
   <arg>-d <replaceable>debug-level</replaceable></arg>
   <arg>-D <replaceable>datadir</replaceable></arg>
   <arg>-e</arg>
   <arg>-f<group choice="plain"><arg>s</arg><arg>i</arg><arg>t</arg><arg>n</arg><arg>m</arg><arg>h</arg></group></arg>
   <arg>-F</arg>
59
   <arg>-o <replaceable>filename</replaceable></arg>
60 61 62 63 64 65 66
   <arg>-O</arg>
   <arg>-p <replaceable>database</replaceable></arg>
   <arg>-P</arg>
   <group>
    <arg>-s</arg>
    <arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
   </group>
67
   <arg>-S <replaceable>work-mem</replaceable></arg>
68
   <arg>-v <replaceable>protocol</replaceable></arg>
69
   <arg>-W <replaceable>seconds</replaceable></arg>
70
   <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
71 72
  </cmdsynopsis>
 </refsynopsisdiv>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
73

74 75
 <refsect1>
  <title>Description</title>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
76

77
  <para>
78
   The <command>postgres</command> executable is the actual
79
   <productname>PostgreSQL</productname> server process that processes
Peter Eisentraut's avatar
Peter Eisentraut committed
80
   queries.  It is normally not called directly; instead a <xref
81
   linkend="app-postmaster"> multiuser server is started.
Peter Eisentraut's avatar
Peter Eisentraut committed
82 83 84 85
  </para>

  <para>
   The second form above is how
86
   <command>postgres</command> is invoked by the <xref
87
   linkend="app-postmaster"> (only
88 89 90
   conceptually, since both <filename>postmaster</filename> and
   <filename>postgres</filename> are in fact the same program); it
   should not be invoked directly this way.  The first form invokes
91 92 93
   the server directly in interactive single-user mode.  The primary use
   for this mode is during bootstrapping by <xref linkend="app-initdb">.
   Sometimes it is used for debugging or disaster recovery.
94
  </para>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
95

96 97 98 99
  <para>
   When invoked in interactive mode from the shell, the user can enter
   queries and the results will be printed to the screen, but in a
   form that is more useful for developers than end users.  But note
100
   that running a single-user server is not truly suitable for
Peter Eisentraut's avatar
Peter Eisentraut committed
101
   debugging the server since no realistic interprocess communication
102 103
   and locking will happen.
  </para>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
104

105
  <para>
106
   When running a stand-alone server, the session user will be set to
107
   the user with ID 1.  This user does not actually have to exist, so
108
   a stand-alone server can be used to manually recover from certain
109
   kinds of accidental damage to the system catalogs.  Implicit
110
   superuser powers are granted to the user with ID 1 in stand-alone
111
   mode.
112
  </para>
113
 </refsect1>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
114

115 116
 <refsect1>
  <title>Options</title>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
117

118
   <para>
119
    When <command>postgres</command> is started by a <xref
120
    linkend="app-postmaster"> then it
121
    inherits all options set by the latter.  Additionally,
122 123
    <command>postgres</command>-specific options can be passed
    from the <command>postmaster</command> with the
124 125
    <option>-o</option> switch.
   </para>
126

127 128
   <para>
    You can avoid having to type these options by setting up a
129
    configuration file.  See <xref linkend="runtime-config"> for details.  Some
130 131 132 133
    (safe) options can also be set from the connecting client in an
    application-dependent way.  For example, if the environment
    variable <envar>PGOPTIONS</envar> is set, then
    <application>libpq</>-based clients will pass that string to the
134
    server, which will interpret it as
135
    <command>postgres</command> command-line options.
136
   </para>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
137

138
   <refsect2>
139
    <title>General Purpose</title>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
140

141 142 143
    <para>
     The options <option>-A</option>, <option>-B</option>,
     <option>-c</option>, <option>-d</option>, <option>-D</option>,
144
     <option>-F</option>, and <option>--<replaceable>name</></option> have the same meanings
145
     as the <xref linkend="app-postmaster"> except that
146 147
     <literal>-d 0</> prevents the server log level of
     the <command>postmaster</> from being propagated to <command>postgres</>.
148
    </para>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
149

150
    <variablelist>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
151
     <varlistentry>
152
      <term><option>-e</option></term>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
153 154
      <listitem>
       <para>
155 156 157 158
        Sets the default date style to <quote>European</quote>, that is
	<literal>DMY</> ordering of input date fields.  This also causes
	the day to be printed before the month in certain date output formats.
	See <xref linkend="datatype-datetime"> for more information.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
159 160 161 162 163
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
164
      <term><option>-o</option> <replaceable class="parameter">filename</replaceable></term>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
165 166
      <listitem>
       <para>
167
	Send all server log output to 
168
	<replaceable class="parameter">filename</replaceable>.
169 170
	If <command>postgres</command> is running under the
	<command>postmaster</command>, this option is ignored,
171
	and the <systemitem>stderr</> inherited from the
172
	<command>postmaster</command> is used.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
173 174 175 176
       </para>
      </listitem>
     </varlistentry>

177
     <varlistentry>
178
      <term><option>-P</option></term>
179 180
      <listitem>
       <para>
181 182 183
	Ignore system indexes when reading system tables (but still update
	the indexes when modifying the tables).  This is useful when
	recovering from damaged system indexes.
184 185 186 187
       </para>
      </listitem>
     </varlistentry>

Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
188
     <varlistentry>
189
      <term><option>-s</option></term>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
190 191
      <listitem>
       <para>
192
	Print time information and other statistics at the end of each command.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
193 194 195 196 197 198 199
	This is useful for benchmarking or for use in tuning the number of
	buffers.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
200
      <term><option>-S</option> <replaceable class="parameter">work-mem</replaceable></term>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
201 202
      <listitem>
       <para>
203
	Specifies the amount of memory to be used by internal sorts and hashes
204 205 206
	before resorting to temporary disk files.  See the description of the
	<varname>work_mem</> configuration parameter in <xref
	linkend="runtime-config-resource-memory">.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
207 208 209 210
       </para>
      </listitem>
     </varlistentry>

211
    </variablelist>
212
   </refsect2>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
213

214
   <refsect2>
215
    <title>Options for stand-alone mode</title>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
216 217 218

    <variablelist>
     <varlistentry>
219
      <term><replaceable class="parameter">database</replaceable></term>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
220 221
      <listitem>
       <para>
222 223
	Specifies the name of the database to be accessed.  If it is
	omitted it defaults to the user name.	
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
224
       </para>
225 226
      </listitem>
     </varlistentry>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
227 228

     <varlistentry>
229
      <term><option>-E</option></term>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
230 231
      <listitem>
       <para>
232
	Echo all commands.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
233 234 235 236 237
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
238
      <term><option>-N</option></term>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
239 240
      <listitem>
       <para>
241
	Disables use of newline as a statement delimiter.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
242 243 244
       </para>
      </listitem>
     </varlistentry>
245
    </variablelist>
246
   </refsect2>
247

248
   <refsect2>
249 250 251 252 253 254 255 256 257 258 259
    <title>Semi-internal Options</title>

    <para>
     There are several other options that may be specified, used
     mainly for debugging purposes.  These are listed here only for
     the use by <productname>PostgreSQL</productname> system
     developers.  <emphasis>Use of any of these options is highly
     discouraged.</emphasis>  Furthermore, any of these options may
     disappear or change in a future release without notice.
   </para>
    <variablelist>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
260 261

     <varlistentry>
262
      <term><option>-f</option> <literal>{ s | i | m | n | h }</literal></term>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
263 264 265 266 267 268 269
      <listitem>
       <para>
	Forbids the use of particular scan and join methods:
	<literal>s</literal> and <literal>i</literal>
	disable sequential and index scans respectively, while
	<literal>n</literal>, <literal>m</literal>, and <literal>h</literal>
	disable nested-loop, merge and hash joins respectively.
270
       </para>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
271 272 273 274 275 276 277 278 279 280 281 282 283
	
	<note>
	 <para>
	  Neither sequential scans nor nested-loop joins can be disabled completely;
	  the <literal>-fs</literal> and <literal>-fn</literal>
	  options simply discourage the optimizer from using those
	  plan types if it has any other alternative.
	 </para>
	</note>
      </listitem>
     </varlistentry>

     <varlistentry>
284
      <term><option>-O</option></term>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
285 286
      <listitem>
       <para>
287
	Allows the structure of system tables to be modified.  This is
288
	used by <command>initdb</command>.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
289 290 291 292
       </para>
      </listitem>
     </varlistentry>

293
     <varlistentry>
294
      <term><option>-p</option> <replaceable class="parameter">database</replaceable></term>
295 296
      <listitem>
       <para>
297 298
	Indicates that this process has been started by a
	<command>postmaster</command> and specifies the database to use.
299 300 301 302
	etc.
       </para>
      </listitem>
     </varlistentry>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
303 304

     <varlistentry>
305
      <term><option>-t</option> <literal>pa[rser] | pl[anner] | e[xecutor]</literal></term>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
306 307
      <listitem>
       <para>
308 309 310 311 312 313
	Print timing statistics for each query relating to each of the
	major system modules.  This option cannot be used together
	with the <option>-s</option> option.
       </para>
      </listitem>
     </varlistentry>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
314

315
     <varlistentry>
316
      <term><option>-v</option> <replaceable class="parameter">protocol</replaceable></term>
317 318 319 320
      <listitem>
       <para>
	Specifies the version number of the frontend/backend protocol
	to be used for this particular session.
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
321 322 323 324
       </para>
      </listitem>
     </varlistentry>

325
     <varlistentry>
326
      <term><option>-W</option> <replaceable class="parameter">seconds</replaceable></term>
327 328 329 330
      <listitem>
       <para>
	As soon as this option is encountered, the process sleeps for
	the specified amount of seconds.  This gives developers time
331
	to attach a debugger to the server process.
332 333 334
       </para>
      </listitem>
     </varlistentry>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
335

Bruce Momjian's avatar
Bruce Momjian committed
336 337 338 339 340 341 342 343 344 345 346
     <varlistentry>
      <term><option>--describe-config</option></term>
      <listitem>
       <para>
        This option dumps out the server's internal configuration variables, 
        descriptions, and defaults in tab-delimited <command>COPY</> format.
        It is designed primarily for use by administration tools.
       </para>
      </listitem>
     </varlistentry>

347
    </variablelist>
348
   </refsect2>
349
 </refsect1>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
350

351
 <refsect1>
352 353 354 355 356 357 358 359
  <title>Environment</title>

  <variablelist>
   <varlistentry>
    <term><envar>PGDATA</envar></term>

    <listitem>
     <para>
360
      Default data directory location
361 362 363 364 365 366 367 368 369 370 371 372 373
     </para>
    </listitem>
   </varlistentry>

  </variablelist>

  <para>
   For others, which have little influence during single-user mode,
   see <xref linkend="app-postmaster">.
  </para>
 </refsect1>

 <refsect1>
374 375 376
  <title>Notes</title>

  <para>
377 378 379 380 381
   To cancel a running query, send the <literal>SIGINT</literal> signal
   to the <command>postgres</command> process running that command.
  </para>

  <para>
382
   To tell <command>postgres</command> to reload the configuration files,
383 384 385 386
   send a <literal>SIGHUP</literal> signal.  Normally it's best to
   <literal>SIGHUP</literal> the <command>postmaster</command> instead;
   the <command>postmaster</command> will in turn <literal>SIGHUP</literal>
   each of its children.  But in some cases it might be desirable to have only
387
   one <command>postgres</command> process reload the configuration files.
388 389 390 391
  </para>

  <para>
   The <command>postmaster</command> uses <literal>SIGTERM</literal>
392
   to tell a <command>postgres</command> process to quit normally and
393
   <literal>SIGQUIT</literal> to terminate without the normal cleanup.
394 395 396 397 398 399
   These signals <emphasis>should not</emphasis> be used by users.  It is also
   unwise to send <literal>SIGKILL</literal> to a <command>postgres</command>
   process --- the <command>postmaster</command> will interpret this as
   a crash in <command>postgres</command>, and will force all the sibling
   <command>postgres</command> processes to quit as part of its standard
   crash-recovery procedure.
400 401 402 403 404
  </para>

 </refsect1>

 <refsect1>
405 406 407
  <title>Usage</title>

   <para>
408
    Start a stand-alone server with a command like
409
<screen>
410
<userinput>postgres -D /usr/local/pgsql/data <replaceable>other-options</> my_database</userinput>
411
</screen>
412
    Provide the correct path to the database directory with <option>-D</>, or
413 414 415 416 417
    make sure that the environment variable <envar>PGDATA</> is set.
    Also specify the name of the particular database you want to work in.
   </para>

   <para>
418
    Normally, the stand-alone server treats newline as the command
419 420 421 422 423 424 425 426
    entry terminator; there is no intelligence about semicolons,
    as there is in <application>psql</>.  To continue a command
    across multiple lines, you must type backslash just before each
    newline except the last one.
   </para>

   <para>
    But if you use the <option>-N</> command line switch, then newline does
427
    not terminate command entry.  In this case, the server will read the standard input
428
    until the end-of-file (<acronym>EOF</>) marker, then
429
    process the input as a single command string.  Backslash-newline is not
430 431 432 433
    treated specially in this case.
   </para>

   <para>
434
    To quit the session, type <acronym>EOF</acronym>
Peter Eisentraut's avatar
Peter Eisentraut committed
435 436
    (<keycombo action="simul"><keycap>Control</><keycap>D</></>, usually).
    If you've
437
    used <option>-N</>, two consecutive <acronym>EOF</>s are needed to exit.
438 439 440
   </para>

   <para>
441
    Note that the stand-alone server does not provide sophisticated
Peter Eisentraut's avatar
Peter Eisentraut committed
442
    line-editing features (no command history, for example).
443 444 445 446
   </para>

 </refsect1>

447
 <refsect1>
448
  <title>See Also</title>
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
449 450

  <para>
451 452 453
   <xref linkend="app-initdb">,
   <xref linkend="app-ipcclean">,
   <xref linkend="app-postmaster">
Thomas G. Lockhart's avatar
Thomas G. Lockhart committed
454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474
  </para>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->