2 $PostgreSQL: pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.45 2004/02/03 17:34:02 tgl Exp $
3 PostgreSQL documentation
6 <refentry id="app-postmaster">
8 <refentrytitle id="APP-POSTMASTER-TITLE"><application>postmaster</application></refentrytitle>
9 <manvolnum>1</manvolnum>
10 <refmiscinfo>Application</refmiscinfo>
14 <refname id="postmaster-ref">postmaster</refname>
15 <refpurpose><productname>PostgreSQL</productname> multiuser database server</refpurpose>
18 <indexterm zone="app-postmaster">
19 <primary>postmaster</primary>
24 <command>postmaster</command>
25 <arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
26 <arg>-B <replaceable>nbuffers</replaceable></arg>
27 <arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
28 <arg>-d <replaceable>debug-level</replaceable></arg>
29 <arg>-D <replaceable>datadir</replaceable></arg>
31 <arg>-h <replaceable>hostname</replaceable></arg>
33 <arg>-k <replaceable>directory</replaceable></arg>
35 <arg>-N <replaceable>max-connections</replaceable></arg>
36 <arg>-o <replaceable>extra-options</replaceable></arg>
37 <arg>-p <replaceable>port</replaceable></arg>
39 <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
40 <group><arg>-n</arg><arg>-s</arg></group>
45 <title>Description</title>
48 <command>postmaster</command> is the
49 <productname>PostgreSQL</productname> multiuser database server.
50 In order for a client application to access a database it connects
51 (over a network or locally) to a running
52 <command>postmaster</command>. The
53 <command>postmaster</command> then starts a separate server
54 process (<quote><xref linkend="app-postgres"></quote>) to handle
55 the connection. The <command>postmaster</command> also
56 manages the communication among server processes.
60 By default the <command>postmaster</command> starts in the
61 foreground and prints log messages to the standard error stream. In
62 practical applications the <command>postmaster</command>
63 should be started as a background process, perhaps at boot time.
67 One <command>postmaster</command> always manages the data
68 from exactly one database cluster. A database cluster is a
69 collection of databases that is stored at a common file system
70 location. When the <command>postmaster</command> starts it needs to know the location
71 of the database cluster files (<quote>data area</quote>). This is
72 done with the <option>-D</option> invocation option or the
73 <envar>PGDATA</envar> environment variable; there is no default.
74 More than one <command>postmaster</command> process can run on a system at one time,
75 as long as they use different data areas and different
76 communication ports (see below). A data area is created with <xref
77 linkend="app-initdb">.
81 <refsect1 id="app-postmaster-options">
82 <title>Options</title>
85 <command>postmaster</command> accepts the following
86 command line arguments. For a detailed discussion of the options
87 consult <xref linkend="runtime-config">. You can also save typing most of these
88 options by setting up a configuration file.
92 <term><option>-A 0|1</option></term>
95 Enables run-time assertion checks, which is a debugging aid to
96 detect programming mistakes. This is only available if it was
97 enabled during compilation. If so, the default is on.
103 <term><option>-B <replaceable class="parameter">nbuffers</replaceable></option></term>
106 Sets the number of shared buffers for use by the server
107 processes. This value defaults to 64 buffers, where each
114 <term><option>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
117 Sets a named run-time parameter. Consult <xref linkend="runtime-config"> for
118 a list and descriptions. Most of the other command line
119 options are in fact short forms of such a parameter
120 assignment. <option>-c</> can appear multiple times to set
127 <term><option>-d <replaceable>debug-level</replaceable></option></term>
130 Sets the debug level. The higher this value is set, the more
131 debugging output is written to the server log. Values are from
138 <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
141 Specifies the file system location of the data directory. See
148 <term><option>-F</option></term>
151 Disables <function>fsync</function> calls for performance
152 improvement, at the risk of data corruption in event of a
153 system crash. This option corresponds to setting
154 <literal>fsync=false</> in <filename>postgresql.conf</>. Read the detailed
155 documentation before using this!
158 <option>--fsync=true</option> has the opposite effect
165 <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term>
168 Specifies the IP host name or address on which the
169 <command>postmaster</command> is to listen for
170 connections from client applications. Defaults to
171 listening on all configured addresses (including
172 <systemitem class="systemname">localhost</systemitem>).
178 <term><option>-i</option></term>
181 Allows clients to connect via TCP/IP (Internet domain)
182 connections. Without this option, only local Unix domain
183 socket connections are accepted. This option corresponds
184 to setting <literal>tcpip_socket=true</> in <filename>postgresql.conf</>.
187 <option>--tcpip-socket=false</option> has the opposite
188 effect of this option.
194 <term><option>-k <replaceable class="parameter">directory</replaceable></option></term>
197 Specifies the directory of the Unix-domain socket on which the
198 <command>postmaster</command> is to listen for
199 connections from client applications. The default is normally
200 <filename>/tmp</filename>, but can be changed at build time.
206 <term><option>-l</option></term>
209 Enables secure connections using SSL. The <option>-i</option>
210 option is also required. You must have compiled with SSL
211 enabled to use this option.
217 <term><option>-N <replaceable class="parameter">max-connections</replaceable></option></term>
220 Sets the maximum number of client connections that this
221 <command>postmaster</command> will accept. By
222 default, this value is 32, but it can be set as high as your
223 system will support. (Note that
224 <option>-B</option> is required to be at least twice
225 <option>-N</option>. See <xref linkend="kernel-resources"> for a discussion of
226 system resource requirements for large numbers of client
233 <term><option>-o <replaceable class="parameter">extra-options</replaceable></option></term>
236 The command line-style options specified in <replaceable
237 class="parameter">extra-options</replaceable> are passed to
238 all server processes started by this
239 <command>postmaster</command>. See <xref
240 linkend="app-postgres"> for possibilities. If the option
241 string contains any spaces, the entire string must be quoted.
247 <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
250 Specifies the TCP/IP port or local Unix domain socket file
251 extension on which the <command>postmaster</command>
252 is to listen for connections from client applications.
253 Defaults to the value of the <envar>PGPORT</envar> environment
254 variable, or if <envar>PGPORT</envar> is not set, then
255 defaults to the value established during compilation (normally
256 5432). If you specify a port other than the default port,
257 then all client applications must specify the same port using
258 either command-line options or <envar>PGPORT</envar>.
264 <term><option>-S</option></term>
267 Specifies that the <command>postmaster</command>
268 process should start up in silent mode. That is, it will
269 disassociate from the user's (controlling) terminal, start its
270 own process group, and redirect its standard output and
271 standard error to <filename>/dev/null</filename>.
274 Using this switch discards all logging output, which is
275 probably not what you want, since it makes it very difficult
276 to troubleshoot problems. See below for a better way to start
277 the <command>postmaster</command> in the background.
280 <option>--silent-mode=false</option> has the opposite effect
287 <term><option>--<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
290 Sets a named run-time parameter; a shorter form of
300 Two additional command line options are available for debugging
301 problems that cause a server process to die abnormally. The
302 ordinary strategy in this situation is to notify all other server
303 processes that they must terminate and then reinitialize the
304 shared memory and semaphores. This is because an errant server
305 process could have corrupted some shared state before terminating.
306 These options select alternative behaviors of the
307 <command>postmaster</command> in this situation.
308 <emphasis>Neither option is intended for use in ordinary
309 operation.</emphasis>
316 These special-case options are:
320 <term><option>-n</option></term>
323 <command>postmaster</command>
324 will not reinitialize shared data structures. A knowledgeable system
325 programmer can then use a debugger
326 to examine shared memory and semaphore state.
332 <term><option>-s</option></term>
335 <command>postmaster</command>
336 will stop all other server processes by sending the signal
337 <literal>SIGSTOP</literal>,
338 but will not cause them to terminate. This permits system programmers
339 to collect core dumps from all server processes by hand.
349 <title>Environment</title>
353 <term><envar>PGCLIENTENCODING</envar></term>
357 Default character encoding used by clients. (The clients may
358 override this individually.) This value can also be set in the
365 <term><envar>PGDATA</envar></term>
369 Default data direction location
375 <term><envar>PGDATESTYLE</envar></term>
379 Default value of the <varname>DateStyle</varname> run-time
380 parameter. (The use of this environment variable is deprecated.)
386 <term><envar>PGPORT</envar></term>
390 Default port (preferably set in the configuration file)
396 <term><envar>TZ</envar></term>
410 Other environment variables may be used to designate alternative
411 data storage locations. See <xref linkend="manage-ag-alternate-locs"> for more
421 <title>Diagnostics</title>
424 A failure message mentioning <literal>semget</> or <literal>shmget</>
425 probably indicates you need to configure your kernel to provide adequate
426 shared memory and semaphores. For more discussion see <xref
427 linkend="kernel-resources">.
432 You may be able to postpone reconfiguring your kernel by decreasing
433 <varname>shared_buffers</varname> to reduce the shared memory consumption
434 of <productname>PostgreSQL</>, and/or by reducing
435 <varname>max_connections</varname> to reduce the semaphore consumption.
440 A failure message suggesting that another postmaster is already running
441 should be checked carefully, for example by using the command
443 <prompt>$</prompt> <userinput>ps ax | grep postmaster</userinput>
447 <prompt>$</prompt> <userinput>ps -ef | grep postmaster</userinput>
449 depending on your system. If you are certain that no conflicting
450 postmaster is running, you may remove the lock file mentioned in the
451 message and try again.
455 A failure message indicating inability to bind to a port may
456 indicate that that port is already in use by some
457 non-<productname>PostgreSQL</productname> process. You may also
458 get this error if you terminate the <command>postmaster</command>
459 and immediately restart it using the same port; in this case, you
460 must simply wait a few seconds until the operating system closes
461 the port before trying again. Finally, you may get this error if
462 you specify a port number that your operating system considers to
463 be reserved. For example, many versions of Unix consider port
464 numbers under 1024 to be <quote>trusted</quote> and only permit
465 the Unix superuser to access them.
474 If at all possible, <emphasis>do not</emphasis> use
475 <literal>SIGKILL</literal> to kill the
476 <command>postmaster</command>. Doing so will prevent
477 <command>postmaster</command> from freeing the system
478 resources (e.g., shared memory and semaphores) that it holds before
479 terminating. This may cause problems for starting a fresh
480 <command>postmaster</command> run.
484 To terminate the <command>postmaster</command> normally,
485 the signals <literal>SIGTERM</literal>, <literal>SIGINT</literal>,
486 or <literal>SIGQUIT</literal> can be used. The first will wait for
487 all clients to terminate before quitting, the second will
488 forcefully disconnect all clients, and the third will quit
489 immediately without proper shutdown, resulting in a recovery run
490 during restart. The <literal>SIGHUP</literal> signal will
491 reload the server configuration files.
495 The utility command <xref linkend="app-pg-ctl"> can be used to
496 start and shut down the <command>postmaster</command>
497 safely and comfortably.
501 The <option>--</> options will not work on <systemitem
502 class="osname">FreeBSD</> or <systemitem class="osname">OpenBSD</>.
503 Use <option>-c</> instead. This is a bug in the affected operating
504 systems; a future release of <productname>PostgreSQL</productname>
505 will provide a workaround if this is not fixed.
510 <refsect1 id="app-postmaster-examples">
511 <title>Examples</title>
513 To start <command>postmaster</command> in the background
514 using default values, type:
517 <prompt>$</prompt> <userinput>nohup postmaster >logfile 2>&1 </dev/null &</userinput>
522 To start <command>postmaster</command> with a specific
525 <prompt>$</prompt> <userinput>postmaster -p 1234</userinput>
527 This command will start up <command>postmaster</command>
528 communicating through the port 1234. In order to connect to this
529 <command>postmaster</command> using <application>psql</>, you would need to
532 <prompt>$</prompt> <userinput>psql -p 1234</userinput>
534 or set the environment variable <envar>PGPORT</envar>:
536 <prompt>$</prompt> <userinput>export PGPORT=1234</userinput>
537 <prompt>$</prompt> <userinput>psql</userinput>
542 Named run-time parameters can be set in either of these styles:
544 <prompt>$</prompt> <userinput>postmaster -c work_mem=1234</userinput>
545 <prompt>$</prompt> <userinput>postmaster --work-mem=1234</userinput>
547 Either form overrides whatever setting might exist for <varname>work_mem</>
548 in <filename>postgresql.conf</>. Notice that underscores in parameter
549 names can be written as either underscore or dash on the command line.
554 Except for short-term experiments,
555 it's probably better practice to edit the setting in
556 <filename>postgresql.conf</> than to rely on a command-line switch
563 <title>See Also</title>
566 <xref linkend="app-initdb">,
567 <xref linkend="app-pg-ctl">
572 <!-- Keep this comment at the end of the file
577 sgml-minimize-attributes:nil
578 sgml-always-quote-attributes:t
581 sgml-parent-document:nil
582 sgml-default-dtd-file:"../reference.ced"
583 sgml-exposed-tags:nil
584 sgml-local-catalogs:"/usr/lib/sgml/catalog"
585 sgml-local-ecat-files:nil