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
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>postgres</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-pgresetxlog.html" title="pg_resetxlog">
<link rel="next" href="app-postmaster.html" title="postmaster">
<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-postgres"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>Name</h2>
<p>postgres — run a <span class="productname">PostgreSQL</span> server in single-user mode</p>
</div>
<a name="id811705"></a><div class="refsynopsisdiv">
<h2>Synopsis</h2>
<div class="cmdsynopsis"><p><code class="command">postgres</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>] [--describe-config] [-D <em class="replaceable"><code>datadir</code></em>] [-e] [-E] [-f [s] | [i] | [t] | [n] | [m] | [h] ] [-F] [-N] [-o <em class="replaceable"><code>filename</code></em>] [-O] [-P] [[-s] | [-t [pa] | [pl] | [ex] ]] [-S <em class="replaceable"><code>work-mem</code></em>] [-W <em class="replaceable"><code>seconds</code></em>] [--<em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em>] <em class="replaceable"><code>database</code></em> <br><code class="command">postgres</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>] [-e] [-f [s] | [i] | [t] | [n] | [m] | [h] ] [-F] [-o <em class="replaceable"><code>filename</code></em>] [-O] [-p <em class="replaceable"><code>database</code></em>] [-P] [[-s] | [-t [pa] | [pl] | [ex] ]] [-S <em class="replaceable"><code>work-mem</code></em>] [-v <em class="replaceable"><code>protocol</code></em>] [-W <em class="replaceable"><code>seconds</code></em>] [--<em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em>]</p></div>
</div>
<div class="refsect1" lang="en">
<a name="id812272"></a><h2>Description</h2>
<p> The <code class="command">postgres</code> executable is the actual
<span class="productname">PostgreSQL</span> server process that processes
queries. It is normally not called directly; instead a <a href="app-postmaster.html" title="postmaster"><span class="refentrytitle"><a name="app-postmaster-title"></a><span class="application">postmaster</span></span></a> multiuser server is started.
</p>
<p> The second form above is how
<code class="command">postgres</code> is invoked by the <a href="app-postmaster.html" title="postmaster"><span class="refentrytitle"><a name="app-postmaster-title"></a><span class="application">postmaster</span></span></a> (only
conceptually, since both <code class="filename">postmaster</code> and
<code class="filename">postgres</code> are in fact the same program); it
should not be invoked directly this way. The first form invokes
the server directly in interactive single-user mode. The primary use
for this mode is during bootstrapping by <a href="app-initdb.html" title="initdb"><span class="refentrytitle"><a name="app-initdb-title"></a>initdb</span></a>.
Sometimes it is used for debugging or disaster recovery.
</p>
<p> When invoked in interactive mode from the shell, the user can enter
queries and the results will be printed to the screen, but in a
form that is more useful for developers than end users. But note
that running a single-user server is not truly suitable for
debugging the server since no realistic interprocess communication
and locking will happen.
</p>
<p> When running a stand-alone server, the session user will be set to
the user with ID 1. This user does not actually have to exist, so
a stand-alone server can be used to manually recover from certain
kinds of accidental damage to the system catalogs. Implicit
superuser powers are granted to the user with ID 1 in stand-alone
mode.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id812361"></a><h2>Options</h2>
<p> When <code class="command">postgres</code> is started by a <a href="app-postmaster.html" title="postmaster"><span class="refentrytitle"><a name="app-postmaster-title"></a><span class="application">postmaster</span></span></a> then it
inherits all options set by the latter. Additionally,
<code class="command">postgres</code>-specific options can be passed
from the <code class="command">postmaster</code> with the
<code class="option">-o</code> switch.
</p>
<p> You can avoid having to type these options by setting up a
configuration file. See <a href="runtime-config.html" title="Chapter17.Server Configuration">Chapter17, <i>Server Configuration</i></a> for details. Some
(safe) options can also be set from the connecting client in an
application-dependent way. For example, if the environment
variable <code class="envar">PGOPTIONS</code> is set, then
<span class="application">libpq</span>-based clients will pass that string to the
server, which will interpret it as
<code class="command">postgres</code> command-line options.
</p>
<div class="refsect2" lang="en">
<a name="id812433"></a><h3>General Purpose</h3>
<p> The options <code class="option">-A</code>, <code class="option">-B</code>,
<code class="option">-c</code>, <code class="option">-d</code>, <code class="option">-D</code>,
<code class="option">-F</code>, and <code class="option">--<em class="replaceable"><code>name</code></em></code> have the same meanings
as the <a href="app-postmaster.html" title="postmaster"><span class="refentrytitle"><a name="app-postmaster-title"></a><span class="application">postmaster</span></span></a> except that
<code class="literal">-d 0</code> prevents the server log level of
the <code class="command">postmaster</code> from being propagated to <code class="command">postgres</code>.
</p>
<div class="variablelist"><dl>
<dt><span class="term"><code class="option">-e</code></span></dt>
<dd><p> Sets the default date style to “<span class="quote">European</span>”, that is
<code class="literal">DMY</code> ordering of input date fields. This also causes
the day to be printed before the month in certain date output formats.
See <a href="datatype-datetime.html" title="8.5.Date/Time Types">Section8.5, “Date/Time Types”</a> for more information.
</p></dd>
<dt><span class="term"><code class="option">-o</code> <em class="replaceable"><code>filename</code></em></span></dt>
<dd><p> Send all server log output to
<em class="replaceable"><code>filename</code></em>.
If <code class="command">postgres</code> is running under the
<code class="command">postmaster</code>, this option is ignored,
and the <span class="systemitem">stderr</span> inherited from the
<code class="command">postmaster</code> is used.
</p></dd>
<dt><span class="term"><code class="option">-P</code></span></dt>
<dd><p> Ignore system indexes when reading system tables (but still update
the indexes when modifying the tables). This is useful when
recovering from damaged system indexes.
</p></dd>
<dt><span class="term"><code class="option">-s</code></span></dt>
<dd><p> Print time information and other statistics at the end of each command.
This is useful for benchmarking or for use in tuning the number of
buffers.
</p></dd>
<dt><span class="term"><code class="option">-S</code> <em class="replaceable"><code>work-mem</code></em></span></dt>
<dd><p> Specifies the amount of memory to be used by internal sorts and hashes
before resorting to temporary disk files. See the description of the
<code class="varname">work_mem</code> configuration parameter in <a href="runtime-config-resource.html#runtime-config-resource-memory" title="17.4.1.Memory">Section17.4.1, “Memory”</a>.
</p></dd>
</dl></div>
</div>
<div class="refsect2" lang="en">
<a name="id812632"></a><h3>Options for stand-alone mode</h3>
<div class="variablelist"><dl>
<dt><span class="term"><em class="replaceable"><code>database</code></em></span></dt>
<dd><p> Specifies the name of the database to be accessed. If it is
omitted it defaults to the user name.
</p></dd>
<dt><span class="term"><code class="option">-E</code></span></dt>
<dd><p> Echo all commands.
</p></dd>
<dt><span class="term"><code class="option">-N</code></span></dt>
<dd><p> Disables use of newline as a statement delimiter.
</p></dd>
</dl></div>
</div>
<div class="refsect2" lang="en">
<a name="id812669"></a><h3>Semi-internal Options</h3>
<p> There are several other options that may be specified, used
mainly for debugging purposes. These are listed here only for
the use by <span class="productname">PostgreSQL</span> system
developers. <span class="emphasis"><em>Use of any of these options is highly
discouraged.</em></span> Furthermore, any of these options may
disappear or change in a future release without notice.
</p>
<div class="variablelist"><dl>
<dt><span class="term"><code class="option">-f</code> <code class="literal">{ s | i | m | n | h }</code></span></dt>
<dd>
<p> Forbids the use of particular scan and join methods:
<code class="literal">s</code> and <code class="literal">i</code>
disable sequential and index scans respectively, while
<code class="literal">n</code>, <code class="literal">m</code>, and <code class="literal">h</code>
disable nested-loop, merge and hash joins respectively.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p> Neither sequential scans nor nested-loop joins can be disabled completely;
the <code class="literal">-fs</code> and <code class="literal">-fn</code>
options simply discourage the optimizer from using those
plan types if it has any other alternative.
</p>
</div>
</dd>
<dt><span class="term"><code class="option">-O</code></span></dt>
<dd><p> Allows the structure of system tables to be modified. This is
used by <code class="command">initdb</code>.
</p></dd>
<dt><span class="term"><code class="option">-p</code> <em class="replaceable"><code>database</code></em></span></dt>
<dd><p> Indicates that this process has been started by a
<code class="command">postmaster</code> and specifies the database to use.
etc.
</p></dd>
<dt><span class="term"><code class="option">-t</code> <code class="literal">pa[rser] | pl[anner] | e[xecutor]</code></span></dt>
<dd><p> Print timing statistics for each query relating to each of the
major system modules. This option cannot be used together
with the <code class="option">-s</code> option.
</p></dd>
<dt><span class="term"><code class="option">-v</code> <em class="replaceable"><code>protocol</code></em></span></dt>
<dd><p> Specifies the version number of the frontend/backend protocol
to be used for this particular session.
</p></dd>
<dt><span class="term"><code class="option">-W</code> <em class="replaceable"><code>seconds</code></em></span></dt>
<dd><p> As soon as this option is encountered, the process sleeps for
the specified amount of seconds. This gives developers time
to attach a debugger to the server process.
</p></dd>
<dt><span class="term"><code class="option">--describe-config</code></span></dt>
<dd><p> This option dumps out the server's internal configuration variables,
descriptions, and defaults in tab-delimited <code class="command">COPY</code> format.
It is designed primarily for use by administration tools.
</p></dd>
</dl></div>
</div>
</div>
<div class="refsect1" lang="en">
<a name="id812877"></a><h2>Environment</h2>
<div class="variablelist"><dl>
<dt><span class="term"><code class="envar">PGDATA</code></span></dt>
<dd><p> Default data directory location
</p></dd>
</dl></div>
<p> For others, which have little influence during single-user mode,
see <a href="app-postmaster.html" title="postmaster"><span class="refentrytitle"><a name="app-postmaster-title"></a><span class="application">postmaster</span></span></a>.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id812903"></a><h2>Notes</h2>
<p> To cancel a running query, send the <code class="literal">SIGINT</code> signal
to the <code class="command">postgres</code> process running that command.
</p>
<p> To tell <code class="command">postgres</code> to reload the configuration files,
send a <code class="literal">SIGHUP</code> signal. Normally it's best to
<code class="literal">SIGHUP</code> the <code class="command">postmaster</code> instead;
the <code class="command">postmaster</code> will in turn <code class="literal">SIGHUP</code>
each of its children. But in some cases it might be desirable to have only
one <code class="command">postgres</code> process reload the configuration files.
</p>
<p> The <code class="command">postmaster</code> uses <code class="literal">SIGTERM</code>
to tell a <code class="command">postgres</code> process to quit normally and
<code class="literal">SIGQUIT</code> to terminate without the normal cleanup.
These signals <span class="emphasis"><em>should not</em></span> be used by users. It is also
unwise to send <code class="literal">SIGKILL</code> to a <code class="command">postgres</code>
process [mdash ] the <code class="command">postmaster</code> will interpret this as
a crash in <code class="command">postgres</code>, and will force all the sibling
<code class="command">postgres</code> processes to quit as part of its standard
crash-recovery procedure.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id813048"></a><h2>Usage</h2>
<p> Start a stand-alone server with a command like
</p>
<pre class="screen"><strong class="userinput"><code>postgres -D /usr/local/pgsql/data <em class="replaceable"><code>other-options</code></em> my_database</code></strong></pre>
<p>
Provide the correct path to the database directory with <code class="option">-D</code>, or
make sure that the environment variable <code class="envar">PGDATA</code> is set.
Also specify the name of the particular database you want to work in.
</p>
<p> Normally, the stand-alone server treats newline as the command
entry terminator; there is no intelligence about semicolons,
as there is in <span class="application">psql</span>. To continue a command
across multiple lines, you must type backslash just before each
newline except the last one.
</p>
<p> But if you use the <code class="option">-N</code> command line switch, then newline does
not terminate command entry. In this case, the server will read the standard input
until the end-of-file (<acronym class="acronym">EOF</acronym>) marker, then
process the input as a single command string. Backslash-newline is not
treated specially in this case.
</p>
<p> To quit the session, type <acronym class="acronym">EOF</acronym>
(<span><strong class="keycap">Control</strong></span>+<span><strong class="keycap">D</strong></span>, usually).
If you've
used <code class="option">-N</code>, two consecutive <acronym class="acronym">EOF</acronym>s are needed to exit.
</p>
<p> Note that the stand-alone server does not provide sophisticated
line-editing features (no command history, for example).
</p>
</div>
<div class="refsect1" lang="en">
<a name="id813149"></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-ipcclean.html" title="ipcclean"><span class="refentrytitle"><a name="app-ipcclean-title"></a><span class="application">ipcclean</span></span></a>,
<a href="app-postmaster.html" title="postmaster"><span class="refentrytitle"><a name="app-postmaster-title"></a><span class="application">postmaster</span></span></a>
</p>
</div>
</div></body>
</html>
|
