1<!--
2doc/src/sgml/ref/postgres-ref.sgml
3PostgreSQL documentation
4-->
5
6<refentry id="app-postgres">
7 <indexterm zone="app-postgres">
8  <primary>postgres</primary>
9 </indexterm>
10
11 <refmeta>
12  <refentrytitle><application>postgres</application></refentrytitle>
13  <manvolnum>1</manvolnum>
14  <refmiscinfo>Application</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18  <refname>postgres</refname>
19  <refpurpose><productname>PostgreSQL</productname> database server</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23  <cmdsynopsis>
24   <command>postgres</command>
25   <arg rep="repeat"><replaceable>option</replaceable></arg>
26  </cmdsynopsis>
27 </refsynopsisdiv>
28
29 <refsect1>
30  <title>Description</title>
31
32  <para>
33   <command>postgres</command> is the
34   <productname>PostgreSQL</productname> database server.  In order
35   for a client application to access a database it connects (over a
36   network or locally) to a running <command>postgres</command> instance.
37   The <command>postgres</command> instance then starts a separate server
38   process to handle the connection.
39  </para>
40
41  <para>
42   One <command>postgres</command> instance always manages the data of
43   exactly one database cluster.  A database cluster is a collection
44   of databases that is stored at a common file system location (the
45   <quote>data area</quote>).  More than one
46   <command>postgres</command> instance can run on a system at one
47   time, so long as they use different data areas and different
48   communication ports (see below).  When
49   <command>postgres</command> starts it needs to know the location
50   of the data area.  The location must be specified by the
51   <option>-D</option> option or the <envar>PGDATA</envar> environment
52   variable; there is no default.  Typically, <option>-D</option> or
53   <envar>PGDATA</envar> points directly to the data area directory
54   created by <xref linkend="app-initdb"/>.  Other possible file layouts are
55   discussed in <xref linkend="runtime-config-file-locations"/>.
56  </para>
57
58  <para>
59   By default <command>postgres</command> starts in the
60   foreground and prints log messages to the standard error stream.  In
61   practical applications <command>postgres</command>
62   should be started as a background process, perhaps at boot time.
63  </para>
64
65  <para>
66   The <command>postgres</command> command can also be called in
67   single-user mode.  The primary use for this mode is during
68   bootstrapping by <xref linkend="app-initdb"/>.  Sometimes it is used
69   for debugging or disaster recovery;  note that running a single-user
70   server is not truly suitable for debugging the server, since no
71   realistic interprocess communication and locking will happen.
72   When invoked in single-user
73   mode from the shell, the user can enter queries and the results
74   will be printed to the screen, but in a form that is more useful
75   for developers than end users.  In the single-user mode,
76   the session user will be set to the user with ID 1, and implicit
77   superuser powers are granted to this user.
78   This user does not actually have to exist, so the single-user mode
79   can be used to manually recover from certain
80   kinds of accidental damage to the system catalogs.
81  </para>
82 </refsect1>
83
84 <refsect1 id="app-postgres-options">
85  <title>Options</title>
86
87   <para>
88    <command>postgres</command> accepts the following command-line
89    arguments.  For a detailed discussion of the options consult <xref
90    linkend="runtime-config"/>.  You can save typing most of these
91    options by setting up a configuration file.  Some (safe) options
92    can also be set from the connecting client in an
93    application-dependent way to apply only for that session.  For
94    example, if the environment variable <envar>PGOPTIONS</envar> is
95    set, then <application>libpq</application>-based clients will pass that
96    string to the server, which will interpret it as
97    <command>postgres</command> command-line options.
98   </para>
99
100   <refsect2>
101    <title>General Purpose</title>
102
103    <variablelist>
104     <varlistentry>
105      <term><option>-B <replaceable class="parameter">nbuffers</replaceable></option></term>
106      <listitem>
107       <para>
108        Sets the number of shared buffers for use by the server
109        processes.  The default value of this parameter is chosen
110        automatically by <application>initdb</application>.
111        Specifying this option is equivalent to setting the
112        <xref linkend="guc-shared-buffers"/> configuration parameter.
113       </para>
114      </listitem>
115     </varlistentry>
116
117     <varlistentry>
118      <term><option>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
119      <listitem>
120       <para>
121        Sets a named run-time parameter. The configuration parameters
122        supported by <productname>PostgreSQL</productname> are
123        described in <xref linkend="runtime-config"/>. Most of the
124        other command line options are in fact short forms of such a
125        parameter assignment.  <option>-c</option> can appear multiple times
126        to set multiple parameters.
127       </para>
128      </listitem>
129     </varlistentry>
130
131     <varlistentry>
132      <term><option>-C <replaceable>name</replaceable></option></term>
133      <listitem>
134       <para>
135        Prints the value of the named run-time parameter, and exits.
136        (See the <option>-c</option> option above for details.)  This can
137        be used on a running server, and returns values from
138        <filename>postgresql.conf</filename>, modified by any parameters
139        supplied in this invocation.  It does not reflect parameters
140        supplied when the cluster was started.
141       </para>
142
143       <para>
144        This option is meant for other programs that interact with a server
145        instance, such as <xref linkend="app-pg-ctl"/>, to query configuration
146        parameter values.  User-facing applications should instead use <xref
147        linkend="sql-show"/> or the <structname>pg_settings</structname> view.
148       </para>
149      </listitem>
150     </varlistentry>
151
152     <varlistentry>
153      <term><option>-d <replaceable>debug-level</replaceable></option></term>
154      <listitem>
155       <para>
156        Sets the debug level.  The higher this value is set, the more
157        debugging output is written to the server log.  Values are
158        from 1 to 5.  It is also possible to pass <literal>-d
159        0</literal> for a specific session, which will prevent the
160        server log level of the parent <command>postgres</command> process from being
161        propagated to this session.
162       </para>
163      </listitem>
164     </varlistentry>
165
166     <varlistentry>
167      <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
168      <listitem>
169       <para>
170        Specifies the file system location of the database
171        configuration files.  See
172        <xref linkend="runtime-config-file-locations"/> for details.
173       </para>
174      </listitem>
175     </varlistentry>
176
177     <varlistentry>
178      <term><option>-e</option></term>
179      <listitem>
180       <para>
181        Sets the default date style to <quote>European</quote>, that is
182        <literal>DMY</literal> ordering of input date fields.  This also causes
183        the day to be printed before the month in certain date output formats.
184        See <xref linkend="datatype-datetime"/> for more information.
185       </para>
186      </listitem>
187     </varlistentry>
188
189     <varlistentry>
190      <term><option>-F</option></term>
191      <listitem>
192       <para>
193        Disables <function>fsync</function> calls for improved
194        performance, at the risk of data corruption in the event of a
195        system crash.  Specifying this option is equivalent to
196        disabling the <xref linkend="guc-fsync"/> configuration
197        parameter. Read the detailed documentation before using this!
198       </para>
199      </listitem>
200     </varlistentry>
201
202     <varlistentry>
203      <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term>
204      <listitem>
205       <para>
206        Specifies the IP host name or address on which
207        <command>postgres</command> is to listen for TCP/IP
208        connections from client applications.  The value can also be a
209        comma-separated list of addresses, or <literal>*</literal> to specify
210        listening on all available interfaces.  An empty value
211        specifies not listening on any IP addresses, in which case
212        only Unix-domain sockets can be used to connect to the
213        server.  Defaults to listening only on
214        <systemitem class="systemname">localhost</systemitem>.
215        Specifying this option is equivalent to setting the <xref
216        linkend="guc-listen-addresses"/> configuration parameter.
217       </para>
218      </listitem>
219     </varlistentry>
220
221     <varlistentry>
222      <term><option>-i</option></term>
223      <listitem>
224       <para>
225        Allows remote clients to connect via TCP/IP (Internet domain)
226        connections.  Without this option, only local connections are
227        accepted.  This option is equivalent to setting
228        <varname>listen_addresses</varname> to <literal>*</literal> in
229        <filename>postgresql.conf</filename> or via <option>-h</option>.
230       </para>
231       <para>
232        This option is deprecated since it does not allow access to the
233        full functionality of <xref linkend="guc-listen-addresses"/>.
234        It's usually better to set <varname>listen_addresses</varname> directly.
235       </para>
236      </listitem>
237     </varlistentry>
238
239     <varlistentry>
240      <term><option>-k <replaceable class="parameter">directory</replaceable></option></term>
241      <listitem>
242       <para>
243        Specifies the directory of the Unix-domain socket on which
244        <command>postgres</command> is to listen for
245        connections from client applications.  The value can also be a
246        comma-separated list of directories.  An empty value
247        specifies not listening on any Unix-domain sockets, in which case
248        only TCP/IP sockets can be used to connect to the server.
249        The default value is normally
250        <filename>/tmp</filename>, but that can be changed at build time.
251        Specifying this option is equivalent to setting the <xref
252        linkend="guc-unix-socket-directories"/> configuration parameter.
253       </para>
254      </listitem>
255     </varlistentry>
256
257     <varlistentry>
258      <term><option>-l</option></term>
259      <listitem>
260       <para>
261        Enables secure connections using <acronym>SSL</acronym>.
262        <productname>PostgreSQL</productname> must have been compiled with
263        support for <acronym>SSL</acronym> for this option to be
264        available. For more information on using <acronym>SSL</acronym>,
265        refer to <xref linkend="ssl-tcp"/>.
266       </para>
267      </listitem>
268     </varlistentry>
269
270     <varlistentry>
271      <term><option>-N <replaceable class="parameter">max-connections</replaceable></option></term>
272      <listitem>
273       <para>
274        Sets the maximum number of client connections that this
275        server will accept.  The default value of this parameter is chosen
276        automatically by <application>initdb</application>.
277        Specifying this option is equivalent to setting the
278        <xref linkend="guc-max-connections"/> configuration parameter.
279       </para>
280      </listitem>
281     </varlistentry>
282
283     <varlistentry>
284      <term><option>-o <replaceable class="parameter">extra-options</replaceable></option></term>
285      <listitem>
286       <para>
287        The command-line-style arguments specified in <replaceable
288        class="parameter">extra-options</replaceable> are passed to
289        all server processes started by this
290        <command>postgres</command> process.
291       </para>
292
293       <para>
294        Spaces within <replaceable class="parameter">extra-options</replaceable> are
295        considered to separate arguments, unless escaped with a backslash
296        (<literal>\</literal>); write <literal>\\</literal> to represent a literal
297        backslash.  Multiple arguments can also be specified via multiple
298        uses of <option>-o</option>.
299       </para>
300
301       <para>
302        The use of this option is obsolete; all command-line options
303        for server processes can be specified directly on the
304        <command>postgres</command> command line.
305       </para>
306      </listitem>
307     </varlistentry>
308
309     <varlistentry>
310      <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
311      <listitem>
312       <para>
313        Specifies the TCP/IP port or local Unix domain socket file
314        extension on which <command>postgres</command>
315        is to listen for connections from client applications.
316        Defaults to the value of the <envar>PGPORT</envar> environment
317        variable, or if <envar>PGPORT</envar> is not set, then
318        defaults to the value established during compilation (normally
319        5432).  If you specify a port other than the default port,
320        then all client applications must specify the same port using
321        either command-line options or <envar>PGPORT</envar>.
322       </para>
323      </listitem>
324     </varlistentry>
325
326     <varlistentry>
327      <term><option>-s</option></term>
328      <listitem>
329       <para>
330        Print time information and other statistics at the end of each command.
331        This is useful for benchmarking or for use in tuning the number of
332        buffers.
333       </para>
334      </listitem>
335     </varlistentry>
336
337     <varlistentry>
338      <term><option>-S</option> <replaceable class="parameter">work-mem</replaceable></term>
339      <listitem>
340       <para>
341        Specifies the base amount of memory to be used by sorts and
342        hash tables before resorting to temporary disk files.  See the
343        description of the <varname>work_mem</varname> configuration
344        parameter in <xref linkend="runtime-config-resource-memory"/>.
345       </para>
346      </listitem>
347     </varlistentry>
348
349     <varlistentry>
350      <term><option>-V</option></term>
351      <term><option>--version</option></term>
352      <listitem>
353       <para>
354        Print the <application>postgres</application> version and exit.
355       </para>
356      </listitem>
357     </varlistentry>
358
359     <varlistentry>
360      <term><option>--<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
361      <listitem>
362       <para>
363        Sets a named run-time parameter; a shorter form of
364        <option>-c</option>.
365       </para>
366      </listitem>
367     </varlistentry>
368
369     <varlistentry>
370      <term><option>--describe-config</option></term>
371      <listitem>
372       <para>
373        This option dumps out the server's internal configuration variables,
374        descriptions, and defaults in tab-delimited <command>COPY</command> format.
375        It is designed primarily for use by administration tools.
376       </para>
377      </listitem>
378     </varlistentry>
379
380     <varlistentry>
381      <term><option>-?</option></term>
382      <term><option>--help</option></term>
383      <listitem>
384       <para>
385        Show help about <application>postgres</application> command line
386        arguments, and exit.
387       </para>
388      </listitem>
389     </varlistentry>
390    </variablelist>
391   </refsect2>
392
393   <refsect2>
394    <title>Semi-Internal Options</title>
395
396    <para>
397     The options described here are used
398     mainly for debugging purposes, and in some cases to assist with
399     recovery of severely damaged databases. There should be no reason
400     to use them in a production database setup.  They are listed
401     here only for use by <productname>PostgreSQL</productname>
402     system developers.  Furthermore, these options might
403     change or be removed in a future release without notice.
404    </para>
405
406    <variablelist>
407     <varlistentry>
408      <term><option>-f</option> <literal>{ s | i | o | b | t | n | m | h }</literal></term>
409      <listitem>
410       <para>
411        Forbids the use of particular scan and join methods:
412        <literal>s</literal> and <literal>i</literal>
413        disable sequential and index scans respectively,
414        <literal>o</literal>, <literal>b</literal> and <literal>t</literal>
415        disable index-only scans, bitmap index scans, and TID scans
416        respectively, while
417        <literal>n</literal>, <literal>m</literal>, and <literal>h</literal>
418        disable nested-loop, merge and hash joins respectively.
419       </para>
420
421       <para>
422        Neither sequential scans nor nested-loop joins can be disabled
423        completely; the <literal>-fs</literal> and
424        <literal>-fn</literal> options simply discourage the optimizer
425        from using those plan types if it has any other alternative.
426       </para>
427      </listitem>
428     </varlistentry>
429
430     <varlistentry>
431      <term><option>-n</option></term>
432      <listitem>
433       <para>
434        This option is for debugging problems that cause a server
435        process to die abnormally.  The ordinary strategy in this
436        situation is to notify all other server processes that they
437        must terminate and then reinitialize the shared memory and
438        semaphores.  This is because an errant server process could
439        have corrupted some shared state before terminating.  This
440        option specifies that <command>postgres</command> will
441        not reinitialize shared data structures.  A knowledgeable
442        system programmer can then use a debugger to examine shared
443        memory and semaphore state.
444       </para>
445     </listitem>
446    </varlistentry>
447
448     <varlistentry>
449      <term><option>-O</option></term>
450      <listitem>
451       <para>
452        Allows the structure of system tables to be modified.  This is
453        used by <command>initdb</command>.
454       </para>
455      </listitem>
456     </varlistentry>
457
458     <varlistentry>
459      <term><option>-P</option></term>
460      <listitem>
461       <para>
462        Ignore system indexes when reading system tables, but still update
463        the indexes when modifying the tables.  This is useful when
464        recovering from damaged system indexes.
465       </para>
466      </listitem>
467     </varlistentry>
468
469     <varlistentry>
470      <term><option>-t</option> <literal>pa[rser] | pl[anner] | e[xecutor]</literal></term>
471      <listitem>
472       <para>
473        Print timing statistics for each query relating to each of the
474        major system modules.  This option cannot be used together
475        with the <option>-s</option> option.
476       </para>
477      </listitem>
478     </varlistentry>
479
480     <varlistentry>
481      <term><option>-T</option></term>
482      <listitem>
483       <para>
484        This option is for debugging problems that cause a server
485        process to die abnormally.  The ordinary strategy in this
486        situation is to notify all other server processes that they
487        must terminate and then reinitialize the shared memory and
488        semaphores.  This is because an errant server process could
489        have corrupted some shared state before terminating.  This
490        option specifies that <command>postgres</command> will
491        stop all other server processes by sending the signal
492        <literal>SIGSTOP</literal>, but will not cause them to
493        terminate.  This permits system programmers to collect core
494        dumps from all server processes by hand.
495       </para>
496      </listitem>
497     </varlistentry>
498
499     <varlistentry>
500      <term><option>-v</option> <replaceable class="parameter">protocol</replaceable></term>
501      <listitem>
502       <para>
503        Specifies the version number of the frontend/backend protocol
504        to be used for a particular session.  This option is for
505        internal use only.
506       </para>
507      </listitem>
508     </varlistentry>
509
510     <varlistentry>
511      <term><option>-W</option> <replaceable class="parameter">seconds</replaceable></term>
512      <listitem>
513       <para>
514        A delay of this many seconds occurs when a new server process
515        is started, after it conducts the authentication procedure.
516        This is intended to give an opportunity to attach to the
517        server process with a debugger.
518       </para>
519      </listitem>
520     </varlistentry>
521    </variablelist>
522   </refsect2>
523
524   <refsect2>
525    <title>Options for Single-User Mode</title>
526
527    <indexterm>
528     <primary>single-user mode</primary>
529    </indexterm>
530
531    <para>
532     The following options only apply to the single-user mode
533     (see <xref linkend="app-postgres-single-user"/> below).
534    </para>
535
536    <variablelist>
537     <varlistentry>
538      <term><option>--single</option></term>
539      <listitem>
540       <para>
541        Selects the single-user mode.  This must be the first argument
542        on the command line.
543       </para>
544      </listitem>
545     </varlistentry>
546
547     <varlistentry>
548      <term><replaceable class="parameter">database</replaceable></term>
549      <listitem>
550       <para>
551        Specifies the name of the database to be accessed.  This must be
552        the last argument on the command line.  If it is
553        omitted it defaults to the user name.
554       </para>
555      </listitem>
556     </varlistentry>
557
558     <varlistentry>
559      <term><option>-E</option></term>
560      <listitem>
561       <para>
562        Echo all commands to standard output before executing them.
563       </para>
564      </listitem>
565     </varlistentry>
566
567     <varlistentry>
568      <term><option>-j</option></term>
569      <listitem>
570       <para>
571        Use semicolon followed by two newlines, rather than just newline,
572        as the command entry terminator.
573       </para>
574      </listitem>
575     </varlistentry>
576
577     <varlistentry>
578      <term><option>-r</option> <replaceable class="parameter">filename</replaceable></term>
579      <listitem>
580       <para>
581        Send all server log output to <replaceable
582        class="parameter">filename</replaceable>.  This option is only
583        honored when supplied as a command-line option.
584       </para>
585      </listitem>
586     </varlistentry>
587    </variablelist>
588   </refsect2>
589 </refsect1>
590
591 <refsect1>
592  <title>Environment</title>
593
594  <variablelist>
595   <varlistentry>
596    <term><envar>PGCLIENTENCODING</envar></term>
597
598    <listitem>
599     <para>
600      Default character encoding used by clients.  (The clients can
601      override this individually.)  This value can also be set in the
602      configuration file.
603     </para>
604    </listitem>
605   </varlistentry>
606
607   <varlistentry>
608    <term><envar>PGDATA</envar></term>
609
610    <listitem>
611     <para>
612      Default data directory location
613     </para>
614    </listitem>
615   </varlistentry>
616
617   <varlistentry>
618    <term><envar>PGDATESTYLE</envar></term>
619
620    <listitem>
621     <para>
622      Default value of the <xref linkend="guc-datestyle"/> run-time
623      parameter.  (The use of this environment variable is deprecated.)
624     </para>
625    </listitem>
626   </varlistentry>
627
628   <varlistentry>
629    <term><envar>PGPORT</envar></term>
630
631    <listitem>
632     <para>
633      Default port number (preferably set in the configuration file)
634     </para>
635    </listitem>
636   </varlistentry>
637
638  </variablelist>
639 </refsect1>
640
641 <refsect1>
642   <title>Diagnostics</title>
643
644   <para>
645    A failure message mentioning <literal>semget</literal> or
646    <literal>shmget</literal> probably indicates you need to configure your
647    kernel to provide adequate shared memory and semaphores.  For more
648    discussion see <xref linkend="kernel-resources"/>.  You might be able
649    to postpone reconfiguring your kernel by decreasing <xref
650    linkend="guc-shared-buffers"/> to reduce the shared memory
651    consumption of <productname>PostgreSQL</productname>, and/or by reducing
652    <xref linkend="guc-max-connections"/> to reduce the semaphore
653    consumption.
654   </para>
655
656   <para>
657    A failure message suggesting that another server is already running
658    should be checked carefully, for example by using the command
659<screen>
660<prompt>$</prompt> <userinput>ps ax | grep postgres</userinput>
661</screen>
662        or
663<screen>
664<prompt>$</prompt> <userinput>ps -ef | grep postgres</userinput>
665</screen>
666    depending on your system.  If you are certain that no conflicting
667    server is running, you can remove the lock file mentioned in the
668    message and try again.
669   </para>
670
671   <para>
672    A failure message indicating inability to bind to a port might
673    indicate that that port is already in use by some
674    non-<productname>PostgreSQL</productname> process.  You might also
675    get this error if you terminate <command>postgres</command>
676    and immediately restart it using the same port; in this case, you
677    must simply wait a few seconds until the operating system closes
678    the port before trying again.  Finally, you might get this error if
679    you specify a port number that your operating system considers to
680    be reserved.  For example, many versions of Unix consider port
681    numbers under 1024 to be <quote>trusted</quote> and only permit
682    the Unix superuser to access them.
683   </para>
684
685 </refsect1>
686
687 <refsect1>
688  <title>Notes</title>
689
690  <para>
691   The utility command <xref linkend="app-pg-ctl"/> can be used to
692   start and shut down the <command>postgres</command> server
693   safely and comfortably.
694  </para>
695
696  <para>
697   If at all possible, <emphasis>do not</emphasis> use
698   <literal>SIGKILL</literal> to kill the main
699   <command>postgres</command> server.  Doing so will prevent
700   <command>postgres</command> from freeing the system
701   resources (e.g., shared memory and semaphores) that it holds before
702   terminating.  This might cause problems for starting a fresh
703   <command>postgres</command> run.
704  </para>
705
706  <para>
707   To terminate the <command>postgres</command> server normally, the
708   signals <literal>SIGTERM</literal>, <literal>SIGINT</literal>, or
709   <literal>SIGQUIT</literal> can be used.  The first will wait for
710   all clients to terminate before quitting, the second will
711   forcefully disconnect all clients, and the third will quit
712   immediately without proper shutdown, resulting in a recovery run
713   during restart.
714  </para>
715
716  <para>
717   The <literal>SIGHUP</literal> signal will reload
718   the server configuration files.  It is also possible to send
719   <literal>SIGHUP</literal> to an individual server process, but that
720   is usually not sensible.
721  </para>
722
723  <para>
724   To cancel a running query, send the <literal>SIGINT</literal> signal
725   to the process running that command. To terminate a backend process
726   cleanly, send <literal>SIGTERM</literal> to that process. See
727   also <function>pg_cancel_backend</function> and <function>pg_terminate_backend</function>
728   in <xref linkend="functions-admin-signal"/> for the SQL-callable equivalents
729   of these two actions.
730  </para>
731
732  <para>
733   The <command>postgres</command> server uses <literal>SIGQUIT</literal>
734   to tell subordinate server processes to terminate without normal
735   cleanup.
736   This signal <emphasis>should not</emphasis> be used by users.  It
737   is also unwise to send <literal>SIGKILL</literal> to a server
738   process &mdash; the main <command>postgres</command> process will
739   interpret this as a crash and will force all the sibling processes
740   to quit as part of its standard crash-recovery procedure.
741  </para>
742 </refsect1>
743
744 <refsect1 id="app-postgres-bugs">
745  <title>Bugs</title>
746  <para>
747   The <option>--</option> options will not work on <systemitem
748   class="osname">FreeBSD</systemitem> or <systemitem class="osname">OpenBSD</systemitem>.
749   Use <option>-c</option> instead. This is a bug in the affected operating
750   systems; a future release of <productname>PostgreSQL</productname>
751   will provide a workaround if this is not fixed.
752  </para>
753 </refsect1>
754
755 <refsect1 id="app-postgres-single-user" xreflabel="Single-User Mode">
756  <title>Single-User Mode</title>
757
758   <para>
759    To start a single-user mode server, use a command like
760<screen>
761<userinput>postgres --single -D /usr/local/pgsql/data <replaceable>other-options</replaceable> my_database</userinput>
762</screen>
763    Provide the correct path to the database directory with <option>-D</option>, or
764    make sure that the environment variable <envar>PGDATA</envar> is set.
765    Also specify the name of the particular database you want to work in.
766   </para>
767
768   <para>
769    Normally, the single-user mode server treats newline as the command
770    entry terminator; there is no intelligence about semicolons,
771    as there is in <application>psql</application>.  To continue a command
772    across multiple lines, you must type backslash just before each
773    newline except the last one.  The backslash and adjacent newline are
774    both dropped from the input command.  Note that this will happen even
775    when within a string literal or comment.
776   </para>
777
778   <para>
779    But if you use the <option>-j</option> command line switch, a single newline
780    does not terminate command entry; instead, the sequence
781    semicolon-newline-newline does.  That is, type a semicolon immediately
782    followed by a completely empty line.  Backslash-newline is not
783    treated specially in this mode.  Again, there is no intelligence about
784    such a sequence appearing within a string literal or comment.
785   </para>
786
787   <para>
788    In either input mode, if you type a semicolon that is not just before or
789    part of a command entry terminator, it is considered a command separator.
790    When you do type a command entry terminator, the multiple statements
791    you've entered will be executed as a single transaction.
792   </para>
793
794   <para>
795    To quit the session, type <acronym>EOF</acronym>
796    (<keycombo action="simul"><keycap>Control</keycap><keycap>D</keycap></keycombo>, usually).
797    If you've entered any text since the last command entry terminator,
798    then <acronym>EOF</acronym> will be taken as a command entry terminator,
799    and another <acronym>EOF</acronym> will be needed to exit.
800   </para>
801
802   <para>
803    Note that the single-user mode server does not provide sophisticated
804    line-editing features (no command history, for example).
805    Single-user mode also does not do any background processing, such as
806    automatic checkpoints or replication.
807   </para>
808 </refsect1>
809
810 <refsect1 id="app-postgres-examples">
811  <title>Examples</title>
812
813  <para>
814   To start <command>postgres</command> in the background
815   using default values, type:
816
817<screen>
818<prompt>$</prompt> <userinput>nohup postgres &gt;logfile 2&gt;&amp;1 &lt;/dev/null &amp;</userinput>
819</screen>
820  </para>
821
822  <para>
823   To start <command>postgres</command> with a specific
824   port, e.g., 1234:
825<screen>
826<prompt>$</prompt> <userinput>postgres -p 1234</userinput>
827</screen>
828   To connect to this server using <application>psql</application>, specify this port with the -p option:
829<screen>
830<prompt>$</prompt> <userinput>psql -p 1234</userinput>
831</screen>
832   or set the environment variable <envar>PGPORT</envar>:
833<screen>
834<prompt>$</prompt> <userinput>export PGPORT=1234</userinput>
835<prompt>$</prompt> <userinput>psql</userinput>
836</screen>
837  </para>
838
839  <para>
840   Named run-time parameters can be set in either of these styles:
841<screen>
842<prompt>$</prompt> <userinput>postgres -c work_mem=1234</userinput>
843<prompt>$</prompt> <userinput>postgres --work-mem=1234</userinput>
844</screen>
845   Either form overrides whatever setting might exist for
846   <varname>work_mem</varname> in <filename>postgresql.conf</filename>.  Notice that
847   underscores in parameter names can be written as either underscore
848   or dash on the command line.  Except for short-term experiments,
849   it's probably better practice to edit the setting in
850   <filename>postgresql.conf</filename> than to rely on a command-line switch
851   to set a parameter.
852  </para>
853 </refsect1>
854
855 <refsect1>
856  <title>See Also</title>
857
858  <para>
859   <xref linkend="app-initdb"/>,
860   <xref linkend="app-pg-ctl"/>
861  </para>
862 </refsect1>
863</refentry>
864