1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>postmaster</title>
<link rel="stylesheet" href="stylesheet.css" type="text/css">
<link rev="made" href="pgsql-docs@postgresql.org">
<meta name="generator" content="DocBook XSL Stylesheets V1.70.0">
<link rel="start" href="index.html" title="PostgreSQL 8.1.4 Documentation">
<link rel="up" href="reference-server.html" title="PostgreSQL Server Applications">
<link rel="prev" href="app-postgres.html" title="postgres">
<link rel="next" href="internals.html" title="PartVII.Internals">
<link rel="copyright" href="ln-legalnotice.html" title="Legal Notice">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
<a name="app-postmaster"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>Name</h2>
<p>postmaster — <span class="productname">PostgreSQL</span> multiuser database server</p>
</div>
<a name="id813213"></a><div class="refsynopsisdiv">
<h2>Synopsis</h2>
<div class="cmdsynopsis"><p><code class="command">postmaster</code> [-A [0] | [1] ] [-B <em class="replaceable"><code>nbuffers</code></em>] [-c <em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em>] [-d <em class="replaceable"><code>debug-level</code></em>] [-D <em class="replaceable"><code>datadir</code></em>] [-F] [-h <em class="replaceable"><code>hostname</code></em>] [-i] [-k <em class="replaceable"><code>directory</code></em>] [-l] [-N <em class="replaceable"><code>max-connections</code></em>] [-o <em class="replaceable"><code>extra-options</code></em>] [-p <em class="replaceable"><code>port</code></em>] [-S] [--<em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em>] [[-n] | [-s]]</p></div>
</div>
<div class="refsect1" lang="en">
<a name="id813415"></a><h2>Description</h2>
<p> <code class="command">postmaster</code> is the
<span class="productname">PostgreSQL</span> multiuser database server.
In order for a client application to access a database it connects
(over a network or locally) to a running
<code class="command">postmaster</code>. The
<code class="command">postmaster</code> then starts a separate server
process (“<span class="quote"><a href="app-postgres.html" title="postgres"><span class="refentrytitle"><a name="app-postgres-title"></a><span class="application">postgres</span></span></a></span>”) to handle
the connection. The <code class="command">postmaster</code> also
manages the communication among server processes.
</p>
<p> By default the <code class="command">postmaster</code> starts in the
foreground and prints log messages to the standard error stream. In
practical applications the <code class="command">postmaster</code>
should be started as a background process, perhaps at boot time.
</p>
<p> One <code class="command">postmaster</code> always manages the data
from exactly one database cluster. A database cluster is a
collection of databases that is stored at a common file system
location (the “<span class="quote">data area</span>”).
More than one <code class="command">postmaster</code> process can run on a system
at one time, so long as they use different data areas and different
communication ports (see below). A data area is created with <a href="app-initdb.html" title="initdb"><span class="refentrytitle"><a name="app-initdb-title"></a>initdb</span></a>.
</p>
<p> When the <code class="command">postmaster</code> starts it needs
to know the location of the data area.
The location must be specified by the <code class="option">-D</code> option
or the <code class="envar">PGDATA</code> environment variable; there is no default.
Typically, <code class="option">-D</code> or <code class="envar">PGDATA</code> points
directly to the data area directory created by <span class="application">initdb</span>.
Other possible file layouts are discussed in
<a href="runtime-config-file-locations.html" title="17.2.File Locations">Section17.2, “File Locations”</a>.
</p>
</div>
<div class="refsect1" lang="en">
<a name="app-postmaster-options"></a><h2>Options</h2>
<p> <code class="command">postmaster</code> accepts the following
command line arguments. For a detailed discussion of the options
consult <a href="runtime-config.html" title="Chapter17.Server Configuration">Chapter17, <i>Server Configuration</i></a>. You can also save typing most of these
options by setting up a configuration file.
</p>
<div class="variablelist"><dl>
<dt><span class="term"><code class="option">-A 0|1</code></span></dt>
<dd><p> Enables run-time assertion checks, which is a debugging aid to
detect programming mistakes. This option is only available if
assertions were enabled when <span class="productname">PostgreSQL</span> was
compiled. If so, the default is on.
</p></dd>
<dt><span class="term"><code class="option">-B <em class="replaceable"><code>nbuffers</code></em></code></span></dt>
<dd><p> Sets the number of shared buffers for use by the server
processes. The default value of this parameter is chosen
automatically by <span class="application">initdb</span>; refer to <a href="runtime-config-resource.html#runtime-config-resource-memory" title="17.4.1.Memory">Section17.4.1, “Memory”</a> for more information.
</p></dd>
<dt><span class="term"><code class="option">-c <em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em></code></span></dt>
<dd><p> Sets a named run-time parameter. The configuration parameters
supported by <span class="productname">PostgreSQL</span> are
described in <a href="runtime-config.html" title="Chapter17.Server Configuration">Chapter17, <i>Server Configuration</i></a>. Most of the
other command line options are in fact short forms of such a
parameter assignment. <code class="option">-c</code> can appear multiple times
to set multiple parameters.
</p></dd>
<dt><span class="term"><code class="option">-d <em class="replaceable"><code>debug-level</code></em></code></span></dt>
<dd><p> Sets the debug level. The higher this value is set, the more
debugging output is written to the server log. Values are from
1 to 5.
</p></dd>
<dt><span class="term"><code class="option">-D <em class="replaceable"><code>datadir</code></em></code></span></dt>
<dd><p> Specifies the file system location of the data directory or
configuration file(s). See
<a href="runtime-config-file-locations.html" title="17.2.File Locations">Section17.2, “File Locations”</a> for details.
</p></dd>
<dt><span class="term"><code class="option">-F</code></span></dt>
<dd>
<p> Disables <code class="function">fsync</code> calls for improved
performance, at the risk of data corruption in the event of a
system crash. Specifying this option is equivalent to
disabling the <a href="runtime-config-wal.html#guc-fsync">fsync</a> configuration
parameter. Read the detailed documentation before using this!
</p>
<p> <code class="option">--fsync=true</code> has the opposite effect
of this option.
</p>
</dd>
<dt><span class="term"><code class="option">-h <em class="replaceable"><code>hostname</code></em></code></span></dt>
<dd><p> Specifies the IP host name or address on which the
<code class="command">postmaster</code> is to listen for TCP/IP
connections from client applications. The value can also be a
comma-separated list of addresses, or <code class="literal">*</code> to specify
listening on all available interfaces. An empty value
specifies not listening on any IP addresses, in which case
only Unix-domain sockets can be used to connect to the
<code class="command">postmaster</code>. Defaults to listening only on
<span class="systemitem">localhost</span>.
Specifying this option is equivalent to setting the <a href="runtime-config-connection.html#guc-listen-addresses">listen_addresses</a> configuration parameter.
</p></dd>
<dt><span class="term"><code class="option">-i</code></span></dt>
<dd>
<p> Allows remote clients to connect via TCP/IP (Internet domain)
connections. Without this option, only local connections are
accepted. This option is equivalent to setting
<code class="varname">listen_addresses</code> to <code class="literal">*</code> in
<code class="filename">postgresql.conf</code> or via <code class="option">-h</code>.
</p>
<p> This option is deprecated since it does not allow access to the
full functionality of <a href="runtime-config-connection.html#guc-listen-addresses">listen_addresses</a>.
It's usually better to set <code class="varname">listen_addresses</code> directly.
</p>
</dd>
<dt><span class="term"><code class="option">-k <em class="replaceable"><code>directory</code></em></code></span></dt>
<dd><p> Specifies the directory of the Unix-domain socket on which the
<code class="command">postmaster</code> is to listen for
connections from client applications. The default is normally
<code class="filename">/tmp</code>, but can be changed at build time.
</p></dd>
<dt><span class="term"><code class="option">-l</code></span></dt>
<dd><p> Enables secure connections using <acronym class="acronym">SSL</acronym>.
<span class="productname">PostgreSQL</span> must have been compiled with
support for <acronym class="acronym">SSL</acronym> for this option to be
available. For more information on using <acronym class="acronym">SSL</acronym>,
refer to <a href="ssl-tcp.html" title="16.7.Secure TCP/IP Connections with SSL">Section16.7, “Secure TCP/IP Connections with SSL”</a>.
</p></dd>
<dt><span class="term"><code class="option">-N <em class="replaceable"><code>max-connections</code></em></code></span></dt>
<dd><p> Sets the maximum number of client connections that this
<code class="command">postmaster</code> will accept. By
default, this value is 32, but it can be set as high as your
system will support. (Note that
<code class="option">-B</code> is required to be at least twice
<code class="option">-N</code>. See <a href="kernel-resources.html" title="16.4.Managing Kernel Resources">Section16.4, “Managing Kernel Resources”</a> for a discussion of
system resource requirements for large numbers of client
connections.) Specifying this option is equivalent to setting the
<a href="runtime-config-connection.html#guc-max-connections">max_connections</a> configuration parameter.
</p></dd>
<dt><span class="term"><code class="option">-o <em class="replaceable"><code>extra-options</code></em></code></span></dt>
<dd><p> The command line-style options specified in <em class="replaceable"><code>extra-options</code></em> are passed to
all server processes started by this
<code class="command">postmaster</code>. See <a href="app-postgres.html" title="postgres"><span class="refentrytitle"><a name="app-postgres-title"></a><span class="application">postgres</span></span></a> for possibilities. If the option
string contains any spaces, the entire string must be quoted.
</p></dd>
<dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code></span></dt>
<dd><p> Specifies the TCP/IP port or local Unix domain socket file
extension on which the <code class="command">postmaster</code>
is to listen for connections from client applications.
Defaults to the value of the <code class="envar">PGPORT</code> environment
variable, or if <code class="envar">PGPORT</code> is not set, then
defaults to the value established during compilation (normally
5432). If you specify a port other than the default port,
then all client applications must specify the same port using
either command-line options or <code class="envar">PGPORT</code>.
</p></dd>
<dt><span class="term"><code class="option">-S</code></span></dt>
<dd>
<p> Specifies that the <code class="command">postmaster</code>
process should start up in silent mode. That is, it will
disassociate from the user's (controlling) terminal, start its
own process group, and redirect its standard output and
standard error to <code class="filename">/dev/null</code>.
</p>
<p> Using this switch discards all logging output, which is
probably not what you want, since it makes it very difficult
to troubleshoot problems. See below for a better way to start
the <code class="command">postmaster</code> in the background.
</p>
<p> <code class="option">--silent-mode=false</code> has the opposite effect
of this option.
</p>
</dd>
<dt><span class="term"><code class="option">--<em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em></code></span></dt>
<dd><p> Sets a named run-time parameter; a shorter form of
<code class="option">-c</code>.
</p></dd>
</dl></div>
<p>
</p>
<p> Two additional command line options are available for debugging
problems that cause a server process to die abnormally. The
ordinary strategy in this situation is to notify all other server
processes that they must terminate and then reinitialize the
shared memory and semaphores. This is because an errant server
process could have corrupted some shared state before terminating.
These options select alternative behaviors of the
<code class="command">postmaster</code> in this situation.
<span class="emphasis"><em>Neither option is intended for use in ordinary
operation.</em></span>
</p>
<p> </p>
<p> These special-case options are:
</p>
<div class="variablelist"><dl>
<dt><span class="term"><code class="option">-n</code></span></dt>
<dd><p> <code class="command">postmaster</code>
will not reinitialize shared data structures. A knowledgeable system
programmer can then use a debugger
to examine shared memory and semaphore state.
</p></dd>
<dt><span class="term"><code class="option">-s</code></span></dt>
<dd><p> <code class="command">postmaster</code>
will stop all other server processes by sending the signal
<code class="literal">SIGSTOP</code>,
but will not cause them to terminate. This permits system programmers
to collect core dumps from all server processes by hand.
</p></dd>
</dl></div>
<p>
</p>
</div>
<div class="refsect1" lang="en">
<a name="id814191"></a><h2>Environment</h2>
<div class="variablelist"><dl>
<dt><span class="term"><code class="envar">PGCLIENTENCODING</code></span></dt>
<dd><p> Default character encoding used by clients. (The clients may
override this individually.) This value can also be set in the
configuration file.
</p></dd>
<dt><span class="term"><code class="envar">PGDATA</code></span></dt>
<dd><p> Default data directory location
</p></dd>
<dt><span class="term"><code class="envar">PGDATESTYLE</code></span></dt>
<dd><p> Default value of the <a href="runtime-config-client.html#guc-datestyle">DateStyle</a> run-time
parameter. (The use of this environment variable is deprecated.)
</p></dd>
<dt><span class="term"><code class="envar">PGPORT</code></span></dt>
<dd><p> Default port (preferably set in the configuration file)
</p></dd>
<dt><span class="term"><code class="envar">TZ</code></span></dt>
<dd><p> Server time zone
</p></dd>
</dl></div>
</div>
<div class="refsect1" lang="en">
<a name="id814254"></a><h2>Diagnostics</h2>
<p> A failure message mentioning <code class="literal">semget</code> or <code class="literal">shmget</code>
probably indicates you need to configure your kernel to provide adequate
shared memory and semaphores. For more discussion see <a href="kernel-resources.html" title="16.4.Managing Kernel Resources">Section16.4, “Managing Kernel Resources”</a>.
</p>
<div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Tip</h3>
<p> You may be able to postpone reconfiguring your kernel by
decreasing <a href="runtime-config-resource.html#guc-shared-buffers">shared_buffers</a> to reduce the
shared memory consumption of <span class="productname">PostgreSQL</span>, and/or
by reducing <a href="runtime-config-connection.html#guc-max-connections">max_connections</a> to reduce the
semaphore consumption.
</p>
</div>
<p> A failure message suggesting that another postmaster is already running
should be checked carefully, for example by using the command
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>ps ax | grep postmaster</code></strong></pre>
<p>
or
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>ps -ef | grep postmaster</code></strong></pre>
<p>
depending on your system. If you are certain that no conflicting
postmaster is running, you may remove the lock file mentioned in the
message and try again.
</p>
<p> A failure message indicating inability to bind to a port may
indicate that that port is already in use by some
non-<span class="productname">PostgreSQL</span> process. You may also
get this error if you terminate the <code class="command">postmaster</code>
and immediately restart it using the same port; in this case, you
must simply wait a few seconds until the operating system closes
the port before trying again. Finally, you may get this error if
you specify a port number that your operating system considers to
be reserved. For example, many versions of Unix consider port
numbers under 1024 to be “<span class="quote">trusted</span>” and only permit
the Unix superuser to access them.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id814382"></a><h2>Notes</h2>
<p> If at all possible, <span class="emphasis"><em>do not</em></span> use
<code class="literal">SIGKILL</code> to kill the
<code class="command">postmaster</code>. Doing so will prevent
<code class="command">postmaster</code> from freeing the system
resources (e.g., shared memory and semaphores) that it holds before
terminating. This may cause problems for starting a fresh
<code class="command">postmaster</code> run.
</p>
<p> To terminate the <code class="command">postmaster</code> normally,
the signals <code class="literal">SIGTERM</code>, <code class="literal">SIGINT</code>,
or <code class="literal">SIGQUIT</code> can be used. The first will wait for
all clients to terminate before quitting, the second will
forcefully disconnect all clients, and the third will quit
immediately without proper shutdown, resulting in a recovery run
during restart. The <code class="literal">SIGHUP</code> signal will
reload the server configuration files.
</p>
<p> The utility command <a href="app-pg-ctl.html" title="pg_ctl"><span class="refentrytitle"><a name="app-pg-ctl-title"></a><span class="application">pg_ctl</span></span></a> can be used to
start and shut down the <code class="command">postmaster</code>
safely and comfortably.
</p>
<p> The <code class="option">--</code> options will not work on <span class="systemitem">FreeBSD</span> or <span class="systemitem">OpenBSD</span>.
Use <code class="option">-c</code> instead. This is a bug in the affected operating
systems; a future release of <span class="productname">PostgreSQL</span>
will provide a workaround if this is not fixed.
</p>
</div>
<div class="refsect1" lang="en">
<a name="app-postmaster-examples"></a><h2>Examples</h2>
<p> To start <code class="command">postmaster</code> in the background
using default values, type:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>nohup postmaster >logfile 2>&1 </dev/null &</code></strong></pre>
<p>
</p>
<p> To start <code class="command">postmaster</code> with a specific
port:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>postmaster -p 1234</code></strong></pre>
<p>
This command will start up <code class="command">postmaster</code>
communicating through the port 1234. In order to connect to this
<code class="command">postmaster</code> using <span class="application">psql</span>, you would need to
run it as
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>psql -p 1234</code></strong></pre>
<p>
or set the environment variable <code class="envar">PGPORT</code>:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>export PGPORT=1234</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>psql</code></strong></pre>
<p>
</p>
<p> Named run-time parameters can be set in either of these styles:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>postmaster -c work_mem=1234</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>postmaster --work-mem=1234</code></strong></pre>
<p>
Either form overrides whatever setting might exist for <code class="varname">work_mem</code>
in <code class="filename">postgresql.conf</code>. Notice that underscores in parameter
names can be written as either underscore or dash on the command line.
</p>
<div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Tip</h3>
<p> Except for short-term experiments,
it's probably better practice to edit the setting in
<code class="filename">postgresql.conf</code> than to rely on a command-line switch
to set a parameter.
</p>
</div>
</div>
<div class="refsect1" lang="en">
<a name="id814713"></a><h2>See Also</h2>
<p> <a href="app-initdb.html" title="initdb"><span class="refentrytitle"><a name="app-initdb-title"></a>initdb</span></a>,
<a href="app-pg-ctl.html" title="pg_ctl"><span class="refentrytitle"><a name="app-pg-ctl-title"></a><span class="application">pg_ctl</span></span></a>
</p>
</div>
</div></body>
</html>
|
