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 — 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 >logfile 2>&1 </dev/null &</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