doc/src/sgml/ref/postgres-ref.sgml

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