1POSTGRES(1)              PostgreSQL 10.7 Documentation             POSTGRES(1)
2
3
4

NAME

6       postgres - PostgreSQL database server
7

SYNOPSIS

9       postgres [option...]
10

DESCRIPTION

12       postgres is the PostgreSQL database server. In order for a client
13       application to access a database it connects (over a network or
14       locally) to a running postgres instance. The postgres instance then
15       starts a separate server process to handle the connection.
16
17       One postgres instance always manages the data of exactly one database
18       cluster. A database cluster is a collection of databases that is stored
19       at a common file system location (the “data area”). More than one
20       postgres instance can run on a system at one time, so long as they use
21       different data areas and different communication ports (see below).
22       When postgres starts it needs to know the location of the data area.
23       The location must be specified by the -D option or the PGDATA
24       environment variable; there is no default. Typically, -D or PGDATA
25       points directly to the data area directory created by initdb(1). Other
26       possible file layouts are discussed in Section 19.2.
27
28       By default postgres starts in the foreground and prints log messages to
29       the standard error stream. In practical applications postgres should be
30       started as a background process, perhaps at boot time.
31
32       The postgres command can also be called in single-user mode. The
33       primary use for this mode is during bootstrapping by initdb(1).
34       Sometimes it is used for debugging or disaster recovery; note that
35       running a single-user server is not truly suitable for debugging the
36       server, since no realistic interprocess communication and locking will
37       happen. When invoked in single-user mode from the shell, the user can
38       enter queries and the results will be printed to the screen, but in a
39       form that is more useful for developers than end users. In the
40       single-user mode, the session user will be set to the user with ID 1,
41       and implicit superuser powers are granted to this user. This user does
42       not actually have to exist, so the single-user mode can be used to
43       manually recover from certain kinds of accidental damage to the system
44       catalogs.
45

OPTIONS

47       postgres accepts the following command-line arguments. For a detailed
48       discussion of the options consult Chapter 19. You can save typing most
49       of these options by setting up a configuration file. Some (safe)
50       options can also be set from the connecting client in an
51       application-dependent way to apply only for that session. For example,
52       if the environment variable PGOPTIONS is set, then libpq-based clients
53       will pass that string to the server, which will interpret it as
54       postgres command-line options.
55
56   General Purpose
57       -B nbuffers
58           Sets the number of shared buffers for use by the server processes.
59           The default value of this parameter is chosen automatically by
60           initdb. Specifying this option is equivalent to setting the
61           shared_buffers configuration parameter.
62
63       -c name=value
64           Sets a named run-time parameter. The configuration parameters
65           supported by PostgreSQL are described in Chapter 19. Most of the
66           other command line options are in fact short forms of such a
67           parameter assignment.  -c can appear multiple times to set multiple
68           parameters.
69
70       -C name
71           Prints the value of the named run-time parameter, and exits. (See
72           the -c option above for details.) This can be used on a running
73           server, and returns values from postgresql.conf, modified by any
74           parameters supplied in this invocation. It does not reflect
75           parameters supplied when the cluster was started.
76
77           This option is meant for other programs that interact with a server
78           instance, such as pg_ctl(1), to query configuration parameter
79           values. User-facing applications should instead use SHOW(7) or the
80           pg_settings view.
81
82       -d debug-level
83           Sets the debug level. The higher this value is set, the more
84           debugging output is written to the server log. Values are from 1 to
85           5. It is also possible to pass -d 0 for a specific session, which
86           will prevent the server log level of the parent postgres process
87           from being propagated to this session.
88
89       -D datadir
90           Specifies the file system location of the database configuration
91           files. See Section 19.2 for details.
92
93       -e
94           Sets the default date style to “European”, that is DMY ordering of
95           input date fields. This also causes the day to be printed before
96           the month in certain date output formats. See Section 8.5 for more
97           information.
98
99       -F
100           Disables fsync calls for improved performance, at the risk of data
101           corruption in the event of a system crash. Specifying this option
102           is equivalent to disabling the fsync configuration parameter. Read
103           the detailed documentation before using this!
104
105       -h hostname
106           Specifies the IP host name or address on which postgres is to
107           listen for TCP/IP connections from client applications. The value
108           can also be a comma-separated list of addresses, or * to specify
109           listening on all available interfaces. An empty value specifies not
110           listening on any IP addresses, in which case only Unix-domain
111           sockets can be used to connect to the server. Defaults to listening
112           only on localhost. Specifying this option is equivalent to setting
113           the listen_addresses configuration parameter.
114
115       -i
116           Allows remote clients to connect via TCP/IP (Internet domain)
117           connections. Without this option, only local connections are
118           accepted. This option is equivalent to setting listen_addresses to
119           * in postgresql.conf or via -h.
120
121           This option is deprecated since it does not allow access to the
122           full functionality of listen_addresses. It's usually better to set
123           listen_addresses directly.
124
125       -k directory
126           Specifies the directory of the Unix-domain socket on which postgres
127           is to listen for connections from client applications. The value
128           can also be a comma-separated list of directories. An empty value
129           specifies not listening on any Unix-domain sockets, in which case
130           only TCP/IP sockets can be used to connect to the server. The
131           default value is normally /tmp, but that can be changed at build
132           time. Specifying this option is equivalent to setting the
133           unix_socket_directories configuration parameter.
134
135       -l
136           Enables secure connections using SSL.  PostgreSQL must have been
137           compiled with support for SSL for this option to be available. For
138           more information on using SSL, refer to Section 18.9.
139
140       -N max-connections
141           Sets the maximum number of client connections that this server will
142           accept. The default value of this parameter is chosen automatically
143           by initdb. Specifying this option is equivalent to setting the
144           max_connections configuration parameter.
145
146       -o extra-options
147           The command-line-style arguments specified in extra-options are
148           passed to all server processes started by this postgres process.
149
150           Spaces within extra-options are considered to separate arguments,
151           unless escaped with a backslash (\); write \\ to represent a
152           literal backslash. Multiple arguments can also be specified via
153           multiple uses of -o.
154
155           The use of this option is obsolete; all command-line options for
156           server processes can be specified directly on the postgres command
157           line.
158
159       -p port
160           Specifies the TCP/IP port or local Unix domain socket file
161           extension on which postgres is to listen for connections from
162           client applications. Defaults to the value of the PGPORT
163           environment variable, or if PGPORT is not set, then defaults to the
164           value established during compilation (normally 5432). If you
165           specify a port other than the default port, then all client
166           applications must specify the same port using either command-line
167           options or PGPORT.
168
169       -s
170           Print time information and other statistics at the end of each
171           command. This is useful for benchmarking or for use in tuning the
172           number of buffers.
173
174       -S work-mem
175           Specifies the amount of memory to be used by internal sorts and
176           hashes before resorting to temporary disk files. See the
177           description of the work_mem configuration parameter in
178           Section 19.4.1.
179
180       -V
181       --version
182           Print the postgres version and exit.
183
184       --name=value
185           Sets a named run-time parameter; a shorter form of -c.
186
187       --describe-config
188           This option dumps out the server's internal configuration
189           variables, descriptions, and defaults in tab-delimited COPY format.
190           It is designed primarily for use by administration tools.
191
192       -?
193       --help
194           Show help about postgres command line arguments, and exit.
195
196   Semi-internal Options
197       The options described here are used mainly for debugging purposes, and
198       in some cases to assist with recovery of severely damaged databases.
199       There should be no reason to use them in a production database setup.
200       They are listed here only for use by PostgreSQL system developers.
201       Furthermore, these options might change or be removed in a future
202       release without notice.
203
204       -f { s | i | o | b | t | n | m | h }
205           Forbids the use of particular scan and join methods: s and i
206           disable sequential and index scans respectively, o, b and t disable
207           index-only scans, bitmap index scans, and TID scans respectively,
208           while n, m, and h disable nested-loop, merge and hash joins
209           respectively.
210
211           Neither sequential scans nor nested-loop joins can be disabled
212           completely; the -fs and -fn options simply discourage the optimizer
213           from using those plan types if it has any other alternative.
214
215       -n
216           This option is for debugging problems that cause a server process
217           to die abnormally. The ordinary strategy in this situation is to
218           notify all other server processes that they must terminate and then
219           reinitialize the shared memory and semaphores. This is because an
220           errant server process could have corrupted some shared state before
221           terminating. This option specifies that postgres will not
222           reinitialize shared data structures. A knowledgeable system
223           programmer can then use a debugger to examine shared memory and
224           semaphore state.
225
226       -O
227           Allows the structure of system tables to be modified. This is used
228           by initdb.
229
230       -P
231           Ignore system indexes when reading system tables, but still update
232           the indexes when modifying the tables. This is useful when
233           recovering from damaged system indexes.
234
235       -t pa[rser] | pl[anner] | e[xecutor]
236           Print timing statistics for each query relating to each of the
237           major system modules. This option cannot be used together with the
238           -s option.
239
240       -T
241           This option is for debugging problems that cause a server process
242           to die abnormally. The ordinary strategy in this situation is to
243           notify all other server processes that they must terminate and then
244           reinitialize the shared memory and semaphores. This is because an
245           errant server process could have corrupted some shared state before
246           terminating. This option specifies that postgres will stop all
247           other server processes by sending the signal SIGSTOP, but will not
248           cause them to terminate. This permits system programmers to collect
249           core dumps from all server processes by hand.
250
251       -v protocol
252           Specifies the version number of the frontend/backend protocol to be
253           used for a particular session. This option is for internal use
254           only.
255
256       -W seconds
257           A delay of this many seconds occurs when a new server process is
258           started, after it conducts the authentication procedure. This is
259           intended to give an opportunity to attach to the server process
260           with a debugger.
261
262   Options for Single-User Mode
263       The following options only apply to the single-user mode (see
264       SINGLE-USER MODE).
265
266       --single
267           Selects the single-user mode. This must be the first argument on
268           the command line.
269
270       database
271           Specifies the name of the database to be accessed. This must be the
272           last argument on the command line. If it is omitted it defaults to
273           the user name.
274
275       -E
276           Echo all commands to standard output before executing them.
277
278       -j
279           Use semicolon followed by two newlines, rather than just newline,
280           as the command entry terminator.
281
282       -r filename
283           Send all server log output to filename. This option is only honored
284           when supplied as a command-line option.
285

ENVIRONMENT

287       PGCLIENTENCODING
288           Default character encoding used by clients. (The clients can
289           override this individually.) This value can also be set in the
290           configuration file.
291
292       PGDATA
293           Default data directory location
294
295       PGDATESTYLE
296           Default value of the DateStyle run-time parameter. (The use of this
297           environment variable is deprecated.)
298
299       PGPORT
300           Default port number (preferably set in the configuration file)
301

DIAGNOSTICS

303       A failure message mentioning semget or shmget probably indicates you
304       need to configure your kernel to provide adequate shared memory and
305       semaphores. For more discussion see Section 18.4. You might be able to
306       postpone reconfiguring your kernel by decreasing shared_buffers to
307       reduce the shared memory consumption of PostgreSQL, and/or by reducing
308       max_connections to reduce the semaphore consumption.
309
310       A failure message suggesting that another server is already running
311       should be checked carefully, for example by using the command
312
313           $ ps ax | grep postgres
314
315       or
316
317           $ ps -ef | grep postgres
318
319       depending on your system. If you are certain that no conflicting server
320       is running, you can remove the lock file mentioned in the message and
321       try again.
322
323       A failure message indicating inability to bind to a port might indicate
324       that that port is already in use by some non-PostgreSQL process. You
325       might also get this error if you terminate postgres and immediately
326       restart it using the same port; in this case, you must simply wait a
327       few seconds until the operating system closes the port before trying
328       again. Finally, you might get this error if you specify a port number
329       that your operating system considers to be reserved. For example, many
330       versions of Unix consider port numbers under 1024 to be “trusted” and
331       only permit the Unix superuser to access them.
332

NOTES

334       The utility command pg_ctl(1) can be used to start and shut down the
335       postgres server safely and comfortably.
336
337       If at all possible, do not use SIGKILL to kill the main postgres
338       server. Doing so will prevent postgres from freeing the system
339       resources (e.g., shared memory and semaphores) that it holds before
340       terminating. This might cause problems for starting a fresh postgres
341       run.
342
343       To terminate the postgres server normally, the signals SIGTERM, SIGINT,
344       or SIGQUIT can be used. The first will wait for all clients to
345       terminate before quitting, the second will forcefully disconnect all
346       clients, and the third will quit immediately without proper shutdown,
347       resulting in a recovery run during restart.
348
349       The SIGHUP signal will reload the server configuration files. It is
350       also possible to send SIGHUP to an individual server process, but that
351       is usually not sensible.
352
353       To cancel a running query, send the SIGINT signal to the process
354       running that command. To terminate a backend process cleanly, send
355       SIGTERM to that process. See also pg_cancel_backend and
356       pg_terminate_backend in Section 9.26.2 for the SQL-callable equivalents
357       of these two actions.
358
359       The postgres server uses SIGQUIT to tell subordinate server processes
360       to terminate without normal cleanup. This signal should not be used by
361       users. It is also unwise to send SIGKILL to a server process — the main
362       postgres process will interpret this as a crash and will force all the
363       sibling processes to quit as part of its standard crash-recovery
364       procedure.
365

BUGS

367       The -- options will not work on FreeBSD or OpenBSD. Use -c instead.
368       This is a bug in the affected operating systems; a future release of
369       PostgreSQL will provide a workaround if this is not fixed.
370

SINGLE-USER MODE

372       To start a single-user mode server, use a command like
373
374           postgres --single -D /usr/local/pgsql/data other-options my_database
375
376       Provide the correct path to the database directory with -D, or make
377       sure that the environment variable PGDATA is set. Also specify the name
378       of the particular database you want to work in.
379
380       Normally, the single-user mode server treats newline as the command
381       entry terminator; there is no intelligence about semicolons, as there
382       is in psql. To continue a command across multiple lines, you must type
383       backslash just before each newline except the last one. The backslash
384       and adjacent newline are both dropped from the input command. Note that
385       this will happen even when within a string literal or comment.
386
387       But if you use the -j command line switch, a single newline does not
388       terminate command entry; instead, the sequence
389       semicolon-newline-newline does. That is, type a semicolon immediately
390       followed by a completely empty line. Backslash-newline is not treated
391       specially in this mode. Again, there is no intelligence about such a
392       sequence appearing within a string literal or comment.
393
394       In either input mode, if you type a semicolon that is not just before
395       or part of a command entry terminator, it is considered a command
396       separator. When you do type a command entry terminator, the multiple
397       statements you've entered will be executed as a single transaction.
398
399       To quit the session, type EOF (Control+D, usually). If you've entered
400       any text since the last command entry terminator, then EOF will be
401       taken as a command entry terminator, and another EOF will be needed to
402       exit.
403
404       Note that the single-user mode server does not provide sophisticated
405       line-editing features (no command history, for example). Single-user
406       mode also does not do any background processing, such as automatic
407       checkpoints or replication.
408

EXAMPLES

410       To start postgres in the background using default values, type:
411
412           $ nohup postgres >logfile 2>&1 </dev/null &
413
414       To start postgres with a specific port, e.g. 1234:
415
416           $ postgres -p 1234
417
418       To connect to this server using psql, specify this port with the -p
419       option:
420
421           $ psql -p 1234
422
423       or set the environment variable PGPORT:
424
425           $ export PGPORT=1234
426           $ psql
427
428       Named run-time parameters can be set in either of these styles:
429
430           $ postgres -c work_mem=1234
431           $ postgres --work-mem=1234
432
433       Either form overrides whatever setting might exist for work_mem in
434       postgresql.conf. Notice that underscores in parameter names can be
435       written as either underscore or dash on the command line. Except for
436       short-term experiments, it's probably better practice to edit the
437       setting in postgresql.conf than to rely on a command-line switch to set
438       a parameter.
439

SEE ALSO

441       initdb(1), pg_ctl(1)
442
443
444
445PostgreSQL 10.7                      2019                          POSTGRES(1)
Impressum