2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.37 2003/09/24 18:54:01 tgl Exp $
3 PostgreSQL documentation
6 <refentry id="APP-POSTGRES">
8 <refentrytitle id="APP-POSTGRES-TITLE"><application>postgres</application></refentrytitle>
9 <manvolnum>1</manvolnum>
10 <refmiscinfo>Application</refmiscinfo>
14 <refname>postgres</refname>
15 <refpurpose>run a <productname>PostgreSQL</productname> server in single-user mode</refpurpose>
18 <indexterm zone="app-postgres">
19 <primary>postgres (the program)</primary>
24 <!-- standalone call -->
25 <command>postgres</command>
26 <arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
27 <arg>-B <replaceable>nbuffers</replaceable></arg>
28 <arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
29 <arg>-d <replaceable>debug-level</replaceable></arg>
30 <arg>-D <replaceable>datadir</replaceable></arg>
33 <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>
36 <arg>-o <replaceable>filename</replaceable></arg>
41 <arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
43 <arg>-S <replaceable>sort-mem</replaceable></arg>
44 <arg>-W <replaceable>seconds</replaceable></arg>
45 <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
46 <arg choice="plain"><replaceable>database</replaceable></arg>
48 <!-- postmaster fork -->
49 <command>postgres</command>
50 <arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
51 <arg>-B <replaceable>nbuffers</replaceable></arg>
52 <arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
53 <arg>-d <replaceable>debug-level</replaceable></arg>
54 <arg>-D <replaceable>datadir</replaceable></arg>
56 <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>
58 <arg>-o <replaceable>filename</replaceable></arg>
60 <arg>-p <replaceable>database</replaceable></arg>
64 <arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
66 <arg>-S <replaceable>sort-mem</replaceable></arg>
67 <arg>-v <replaceable>protocol</replaceable></arg>
68 <arg>-W <replaceable>seconds</replaceable></arg>
69 <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
74 <title>Description</title>
77 The <command>postgres</command> executable is the actual
78 <productname>PostgreSQL</productname> server process that processes
79 queries. It is normally not called directly; instead a <xref
80 linkend="app-postmaster"> multiuser server is started.
84 The second form above is how
85 <command>postgres</command> is invoked by the <xref
86 linkend="app-postmaster"> (only
87 conceptually, since both <filename>postmaster</filename> and
88 <filename>postgres</filename> are in fact the same program); it
89 should not be invoked directly this way. The first form invokes
90 the server directly in interactive single-user mode. The primary use
91 for this mode is during bootstrapping by <xref linkend="app-initdb">.
92 Sometimes it is used for debugging or disaster recovery.
96 When invoked in interactive mode from the shell, the user can enter
97 queries and the results will be printed to the screen, but in a
98 form that is more useful for developers than end users. But note
99 that running a single-user server is not truly suitable for
100 debugging the server since no realistic interprocess communication
101 and locking will happen.
105 When running a stand-alone server, the session user will be set to
106 the user with ID 1. This user does not actually have to exist, so
107 a stand-alone server can be used to manually recover from certain
108 kinds of accidental damage to the system catalogs. Implicit
109 superuser powers are granted to the user with ID 1 in stand-alone
115 <title>Options</title>
118 When <command>postgres</command> is started by a <xref
119 linkend="app-postmaster"> then it
120 inherits all options set by the latter. Additionally,
121 <command>postgres</command>-specific options can be passed
122 from the <command>postmaster</command> with the
123 <option>-o</option> switch.
127 You can avoid having to type these options by setting up a
128 configuration file. See <xref linkend="runtime-config"> for details. Some
129 (safe) options can also be set from the connecting client in an
130 application-dependent way. For example, if the environment
131 variable <envar>PGOPTIONS</envar> is set, then
132 <application>libpq</>-based clients will pass that string to the
133 server, which will interpret it as
134 <command>postgres</command> command-line options.
138 <title>General Purpose</title>
141 The options <option>-A</option>, <option>-B</option>,
142 <option>-c</option>, <option>-d</option>, <option>-D</option>,
143 <option>-F</option>, and <option>--<replaceable>name</></option> have the same meanings
144 as the <xref linkend="app-postmaster"> except that
145 <literal>-d 0</> prevents the server log level of
146 the <command>postmaster</> from being propagated to <command>postgres</>.
151 <term><option>-e</option></term>
154 Sets the default date style to <quote>European</quote>, that is
155 <literal>DMY</> ordering of input date fields. This also causes
156 the day to be printed before the month in certain date output formats.
157 See <xref linkend="datatype-datetime"> for more information.
163 <term><option>-o</option> <replaceable class="parameter">filename</replaceable></term>
166 Send all server log output to
167 <replaceable class="parameter">filename</replaceable>.
168 If <command>postgres</command> is running under the
169 <command>postmaster</command>, this option is ignored,
170 and the <systemitem>stderr</> inherited from the
171 <command>postmaster</command> is used.
177 <term><option>-P</option></term>
180 Ignore system indexes when reading system tables (but still update
181 the indexes when modifying the tables). This is useful when
182 recovering from damaged system indexes.
188 <term><option>-s</option></term>
191 Print time information and other statistics at the end of each command.
192 This is useful for benchmarking or for use in tuning the number of
199 <term><option>-S</option> <replaceable class="parameter">sort-mem</replaceable></term>
202 Specifies the amount of memory to be used by internal sorts and hashes
203 before resorting to temporary disk files. The value is specified in
204 kilobytes, and defaults to 1024. Note that for a complex query,
205 several sorts and/or hashes might be running in parallel, and each one
206 will be allowed to use as much as
207 <replaceable class="parameter">sort-mem</replaceable> kilobytes
208 before it starts to put data into temporary files.
217 <title>Options for stand-alone mode</title>
221 <term><replaceable class="parameter">database</replaceable></term>
224 Specifies the name of the database to be accessed. If it is
225 omitted it defaults to the user name.
231 <term><option>-E</option></term>
240 <term><option>-N</option></term>
243 Disables use of newline as a statement delimiter.
251 <title>Semi-internal Options</title>
254 There are several other options that may be specified, used
255 mainly for debugging purposes. These are listed here only for
256 the use by <productname>PostgreSQL</productname> system
257 developers. <emphasis>Use of any of these options is highly
258 discouraged.</emphasis> Furthermore, any of these options may
259 disappear or change in a future release without notice.
264 <term><option>-f</option> <literal>{ s | i | m | n | h }</literal></term>
267 Forbids the use of particular scan and join methods:
268 <literal>s</literal> and <literal>i</literal>
269 disable sequential and index scans respectively, while
270 <literal>n</literal>, <literal>m</literal>, and <literal>h</literal>
271 disable nested-loop, merge and hash joins respectively.
276 Neither sequential scans nor nested-loop joins can be disabled completely;
277 the <literal>-fs</literal> and <literal>-fn</literal>
278 options simply discourage the optimizer from using those
279 plan types if it has any other alternative.
286 <term><option>-O</option></term>
289 Allows the structure of system tables to be modified. This is
290 used by <command>initdb</command>.
296 <term><option>-p</option> <replaceable class="parameter">database</replaceable></term>
299 Indicates that this process has been started by a
300 <command>postmaster</command> and specifies the database to use.
307 <term><option>-t</option> <literal>pa[rser] | pl[anner] | e[xecutor]</literal></term>
310 Print timing statistics for each query relating to each of the
311 major system modules. This option cannot be used together
312 with the <option>-s</option> option.
318 <term><option>-v</option> <replaceable class="parameter">protocol</replaceable></term>
321 Specifies the version number of the frontend/backend protocol
322 to be used for this particular session.
328 <term><option>-W</option> <replaceable class="parameter">seconds</replaceable></term>
331 As soon as this option is encountered, the process sleeps for
332 the specified amount of seconds. This gives developers time
333 to attach a debugger to the server process.
343 <title>Environment</title>
347 <term><envar>PGDATA</envar></term>
351 Default data direction location
359 For others, which have little influence during single-user mode,
360 see <xref linkend="app-postmaster">.
368 To cancel a running query, send the <literal>SIGINT</literal> signal
369 to the <command>postgres</command> process running that command.
373 To tell <command>postgres</command> to reread the configuration file,
374 send a <literal>SIGHUP</literal> signal. Normally it's best to
375 <literal>SIGHUP</literal> the <command>postmaster</command> instead;
376 the <command>postmaster</command> will in turn <literal>SIGHUP</literal>
377 each of its children. But in some cases it might be desirable to have only
378 one <command>postgres</command> process reread the configuration file.
382 The <command>postmaster</command> uses <literal>SIGTERM</literal>
383 to tell a <command>postgres</command> process to quit normally and
384 <literal>SIGQUIT</literal> to terminate without the normal cleanup.
385 These signals <emphasis>should not</emphasis> be used by users. It is also
386 unwise to send <literal>SIGKILL</literal> to a <command>postgres</command>
387 process --- the <command>postmaster</command> will interpret this as
388 a crash in <command>postgres</command>, and will force all the sibling
389 <command>postgres</command> processes to quit as part of its standard
390 crash-recovery procedure.
399 Start a stand-alone server with a command like
401 <userinput>postgres -D /usr/local/pgsql/data <replaceable>other-options</> my_database</userinput>
403 Provide the correct path to the database directory with <option>-D</>, or
404 make sure that the environment variable <envar>PGDATA</> is set.
405 Also specify the name of the particular database you want to work in.
409 Normally, the stand-alone server treats newline as the command
410 entry terminator; there is no intelligence about semicolons,
411 as there is in <application>psql</>. To continue a command
412 across multiple lines, you must type backslash just before each
413 newline except the last one.
417 But if you use the <option>-N</> command line switch, then newline does
418 not terminate command entry. In this case, the server will read the standard input
419 until the end-of-file (<acronym>EOF</>) marker, then
420 process the input as a single command string. Backslash-newline is not
421 treated specially in this case.
425 To quit the session, type <acronym>EOF</acronym>
426 (<keycombo action="simul"><keycap>Control</><keycap>D</></>, usually).
428 used <option>-N</>, two consecutive <acronym>EOF</>s are needed to exit.
432 Note that the stand-alone server does not provide sophisticated
433 line-editing features (no command history, for example).
439 <title>See Also</title>
442 <xref linkend="app-initdb">,
443 <xref linkend="app-ipcclean">,
444 <xref linkend="app-postmaster">
450 <!-- Keep this comment at the end of the file
455 sgml-minimize-attributes:nil
456 sgml-always-quote-attributes:t
459 sgml-parent-document:nil
460 sgml-default-dtd-file:"../reference.ced"
461 sgml-exposed-tags:nil
462 sgml-local-catalogs:"/usr/lib/sgml/catalog"
463 sgml-local-ecat-files:nil