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