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
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>pg_ctl</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-pgcontroldata.html" title="pg_controldata">
<link rel="next" href="app-pgresetxlog.html" title="pg_resetxlog">
<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-pg-ctl"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>Name</h2>
<p>pg_ctl — start, stop, or restart a <span class="productname">PostgreSQL</span> server</p>
</div>
<a name="id809665"></a><div class="refsynopsisdiv">
<h2>Synopsis</h2>
<div class="cmdsynopsis"><p><code class="command">pg_ctl</code> start [-w] [-s] [-D <em class="replaceable"><code>datadir</code></em>] [-l <em class="replaceable"><code>filename</code></em>] [-o <em class="replaceable"><code>options</code></em>] [-p <em class="replaceable"><code>path</code></em>]<br><code class="command">pg_ctl</code> stop [-W] [-s] [-D <em class="replaceable"><code>datadir</code></em>] [-m
[s[mart]] | [f[ast]] | [i[mmediate]]
]<br><code class="command">pg_ctl</code> restart [-w] [-s] [-D <em class="replaceable"><code>datadir</code></em>] [-m
[s[mart]] | [f[ast]] | [i[mmediate]]
] [-o <em class="replaceable"><code>options</code></em>]<br><code class="command">pg_ctl</code> reload [-s] [-D <em class="replaceable"><code>datadir</code></em>]<br><code class="command">pg_ctl</code> status [-D <em class="replaceable"><code>datadir</code></em>]<br><code class="command">pg_ctl</code> kill [<em class="replaceable"><code>signal_name</code></em>] [<em class="replaceable"><code>process_id</code></em>]<br><code class="command">pg_ctl</code> register [-N <em class="replaceable"><code>servicename</code></em>] [-U <em class="replaceable"><code>username</code></em>] [-P <em class="replaceable"><code>password</code></em>] [-D <em class="replaceable"><code>datadir</code></em>] [-w] [-o <em class="replaceable"><code>options</code></em>]<br><code class="command">pg_ctl</code> unregister [-N <em class="replaceable"><code>servicename</code></em>]</p></div>
</div>
<div class="refsect1" lang="en">
<a name="app-pg-ctl-description"></a><h2>Description</h2>
<p> <span class="application">pg_ctl</span> is a utility for starting,
stopping, or restarting the <span class="productname">PostgreSQL</span>
backend server (<a href="app-postmaster.html" title="postmaster"><span class="refentrytitle"><a name="app-postmaster-title"></a><span class="application">postmaster</span></span></a>), or displaying the
status of a running server. Although the server can be started
manually, <span class="application">pg_ctl</span> encapsulates tasks such
as redirecting log output and properly detaching from the terminal
and process group. It also provides convenient options for
controlled shutdown.
</p>
<p> In <code class="option">start</code> mode, a new server is launched. The
server is started in the background, and standard input is attached to
<code class="filename">/dev/null</code>. The standard output and standard
error are either appended to a log file (if the <code class="option">-l</code>
option is used), or redirected to <span class="application">pg_ctl</span>'s
standard output (not standard error). If no log file is chosen, the
standard output of <span class="application">pg_ctl</span> should be redirected
to a file or piped to another process such as a log rotating program
like <span class="application">rotatelogs</span>; otherwise the <code class="command">postmaster</code>
will write its output to the controlling terminal (from the background)
and will not leave the shell's process group.
</p>
<p> In <code class="option">stop</code> mode, the server that is running in
the specified data directory is shut down. Three different
shutdown methods can be selected with the <code class="option">-m</code>
option: “<span class="quote">Smart</span>” mode waits for all the clients to
disconnect. This is the default. “<span class="quote">Fast</span>” mode does
not wait for clients to disconnect. All active transactions are
rolled back and clients are forcibly disconnected, then the
server is shut down. “<span class="quote">Immediate</span>” mode will abort
all server processes without a clean shutdown. This will lead to
a recovery run on restart.
</p>
<p> <code class="option">restart</code> mode effectively executes a stop followed
by a start. This allows changing the <code class="command">postmaster</code>
command-line options.
</p>
<p> <code class="option">reload</code> mode simply sends the
<code class="command">postmaster</code> process a <span class="systemitem">SIGHUP</span>
signal, causing it to reread its configuration files
(<code class="filename">postgresql.conf</code>,
<code class="filename">pg_hba.conf</code>, etc.). This allows changing of
configuration-file options that do not require a complete restart
to take effect.
</p>
<p> <code class="option">status</code> mode checks whether a server is running in
the specified data directory. If it is, the <acronym class="acronym">PID</acronym>
and the command line options that were used to invoke it are
displayed.
</p>
<p> <code class="option">kill</code> mode allows you to send a signal to a specified
process. This is particularly valuable for <span class="productname">Microsoft Windows</span>
which does not have a <span class="application">kill</span> command. Use
<code class="literal">--help</code> to see a list of supported signal names.
</p>
<p> <code class="option">register</code> mode allows you to register a system service
on <span class="productname">Microsoft Windows</span>.
</p>
<p> <code class="option">unregister</code> mode allows you to unregister a system service
on <span class="productname">Microsoft Windows</span>, previously registered with the
<code class="option">register</code> command.
</p>
</div>
<div class="refsect1" lang="en">
<a name="app-pg-ctl-options"></a><h2>Options</h2>
<p>
</p>
<div class="variablelist"><dl>
<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 database files. If
this is omitted, the environment variable
<code class="envar">PGDATA</code> is used.
</p></dd>
<dt><span class="term"><code class="option">-l <em class="replaceable"><code>filename</code></em></code></span></dt>
<dd><p> Append the server log output to
<em class="replaceable"><code>filename</code></em>. If the file does not
exist, it is created. The <span class="systemitem">umask</span> is set to 077, so access to
the log file from other users is disallowed by default.
</p></dd>
<dt><span class="term"><code class="option">-m <em class="replaceable"><code>mode</code></em></code></span></dt>
<dd><p> Specifies the shutdown mode. <em class="replaceable"><code>mode</code></em>
may be <code class="literal">smart</code>, <code class="literal">fast</code>, or
<code class="literal">immediate</code>, or the first letter of one of
these three.
</p></dd>
<dt><span class="term"><code class="option">-o <em class="replaceable"><code>options</code></em></code></span></dt>
<dd>
<p> Specifies options to be passed directly to the
<code class="command">postmaster</code> command.
</p>
<p> The options are usually surrounded by single or double
quotes to ensure that they are passed through as a group.
</p>
</dd>
<dt><span class="term"><code class="option">-p <em class="replaceable"><code>path</code></em></code></span></dt>
<dd><p> Specifies the location of the <code class="filename">postmaster</code>
executable. By default the <code class="filename">postmaster</code> executable is taken from the same
directory as <code class="command">pg_ctl</code>, or failing that, the hard-wired
installation directory. It is not necessary to use this
option unless you are doing something unusual and get errors
that the <code class="filename">postmaster</code> executable was not found.
</p></dd>
<dt><span class="term"><code class="option">-s</code></span></dt>
<dd><p> Only print errors, no informational messages.
</p></dd>
<dt><span class="term"><code class="option">-w</code></span></dt>
<dd><p> Wait for the start or shutdown to complete. Times out after
60 seconds. This is the default for shutdowns. A successful
shutdown is indicated by removal of the <acronym class="acronym">PID</acronym>
file. For starting up, a successful <code class="command">psql -l</code>
indicates success. <code class="command">pg_ctl</code> will attempt to
use the proper port for <span class="application">psql</span>. If the environment variable
<code class="envar">PGPORT</code> exists, that is used. Otherwise, it will see if a port
has been set in the <code class="filename">postgresql.conf</code> file.
If neither of those is used, it will use the default port that
<span class="productname">PostgreSQL</span> was compiled with
(5432 by default). When waiting, <code class="command">pg_ctl</code> will
return an accurate exit code based on the success of the startup
or shutdown.
</p></dd>
<dt><span class="term"><code class="option">-W</code></span></dt>
<dd><p> Do not wait for start or shutdown to complete. This is the
default for starts and restarts.
</p></dd>
</dl></div>
<p>
</p>
</div>
<div class="refsect1" lang="en">
<a name="app-pg-ctl-svcoptions"></a><h2>Windows options</h2>
<p> </p>
<div class="variablelist"><dl>
<dt><span class="term"><code class="option">-N <em class="replaceable"><code>servicename</code></em></code></span></dt>
<dd><p> Name of the system service to register. The name will be used
as both the service name and the display name.
</p></dd>
<dt><span class="term"><code class="option">-P <em class="replaceable"><code>password</code></em></code></span></dt>
<dd><p> Password for the user to start the service.
</p></dd>
<dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code></span></dt>
<dd><p> User name for the user to start the service. For domain users, use the
format <code class="literal">DOMAIN\username</code>.
</p></dd>
</dl></div>
<p>
</p>
</div>
<div class="refsect1" lang="en">
<a name="id810664"></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>
<dt><span class="term"><code class="envar">PGPORT</code></span></dt>
<dd><p> Default port for <a href="app-psql.html" title="psql"><span class="refentrytitle"><a name="app-psql-title"></a><span class="application">psql</span></span></a> (used by the -w option).
</p></dd>
</dl></div>
<p> For others, 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="id810705"></a><h2>Files</h2>
<div class="variablelist"><dl>
<dt><span class="term"><code class="filename">postmaster.pid</code></span></dt>
<dd><p> The existence of this file in the data directory is used to help
<span class="application">pg_ctl</span> determine if the server is
currently running or not.
</p></dd>
<dt><span class="term"><code class="filename">postmaster.opts.default</code></span></dt>
<dd><p> If this file exists in the data directory,
<span class="application">pg_ctl</span> (in <code class="option">start</code>
mode) will pass the contents of the file as options to the
<code class="command">postmaster</code> command, unless overridden by the
<code class="option">-o</code> option.
</p></dd>
<dt><span class="term"><code class="filename">postmaster.opts</code></span></dt>
<dd><p>If this file exists in the data directory,
<span class="application">pg_ctl</span> (in <code class="option">restart</code> mode)
will pass the contents of the file as options to the
<span class="application">postmaster</span>, unless overridden
by the <code class="option">-o</code> option. The contents of this file
are also displayed in <code class="option">status</code> mode.
</p></dd>
<dt><span class="term"><code class="filename">postgresql.conf</code></span></dt>
<dd><p> This file, located in the data directory, is parsed to find the
proper port to use with <span class="application">psql</span> when the
<code class="option">-w</code> is given in <code class="option">start</code> mode.
</p></dd>
</dl></div>
</div>
<div class="refsect1" lang="en">
<a name="id810834"></a><h2>Notes</h2>
<p> Waiting for complete start is not a well-defined operation and may
fail if access control is set up so that a local client cannot
connect without manual interaction (e.g., password authentication).
</p>
</div>
<div class="refsect1" lang="en">
<a name="r1-app-pgctl-2"></a><h2>Examples</h2>
<div class="refsect2" lang="en">
<a name="r2-app-pgctl-3"></a><h3>Starting the Server</h3>
<p> To start up a server:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>pg_ctl start</code></strong></pre>
<p>
</p>
<p> An example of starting the server, blocking until the server has
come up is:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>pg_ctl -w start</code></strong></pre>
<p>
</p>
<p> For a server using port 5433, and
running without <code class="function">fsync</code>, use:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>pg_ctl -o "-F -p 5433" start</code></strong></pre>
<p>
</p>
</div>
<div class="refsect2" lang="en">
<a name="r2-app-pgctl-4"></a><h3>Stopping the Server</h3>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>pg_ctl stop</code></strong></pre>
<p>
stops the server. Using the <code class="option">-m</code> switch allows one
to control <span class="emphasis"><em>how</em></span> the backend shuts down.
</p>
</div>
<div class="refsect2" lang="en">
<a name="r2-app-pgctl-5"></a><h3>Restarting the Server</h3>
<p> Restarting the server is almost equivalent to stopping the
server and starting it again
except that <code class="command">pg_ctl</code> saves and reuses the command line options that
were passed to the previously running instance. To restart
the server in the simplest form, use:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>pg_ctl restart</code></strong></pre>
<p>
</p>
<p> To restart server,
waiting for it to shut down and to come up:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>pg_ctl -w restart</code></strong></pre>
<p>
</p>
<p> To restart using port 5433 and disabling <code class="function">fsync</code> after restarting:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>pg_ctl -o "-F -p 5433" restart</code></strong></pre>
<p>
</p>
</div>
<div class="refsect2" lang="en">
<a name="r2-app-pgctl-6"></a><h3>Showing the Server Status</h3>
<p> Here is a sample status output from
<span class="application">pg_ctl</span>:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>pg_ctl status</code></strong>
<code class="computeroutput">pg_ctl: postmaster is running (pid: 13718)
Command line was:
/usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'</code></pre>
<p>
This is the command line that would be invoked in restart mode.
</p>
</div>
</div>
<div class="refsect1" lang="en">
<a name="id811090"></a><h2>See Also</h2>
<p> <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>
|
