-B

Sets the number of shared buffers for use by the server processes. The default value of this parameter ischosen automatically by initdb. Specifying this option is equivalent to setting the shared_buffersconfiguration parameter.

-c

Sets a named run-time parameter. The configuration parameters supported by PostgreSQL are described inChapter 19. Most of the other command line options are in fact short forms of such a parameter assignment.

-C

Prints the value of the named run-time parameter, and exits. (See the -c option above for details.) Thiscan be used on a running server, and returns values from postgresql.conf, modified by any parameterssupplied in this invocation. It does not reflect parameters supplied when the cluster was started.This option is meant for other programs that interact with a server instance, such as pg_ctl(1), to queryconfiguration parameter values. User-facing applications should instead use SHOW(7) or the pg_settingsview.

-d

Sets the debug level. The higher this value is set, the more debugging output is written to the serverlog. Values are from 1 to 5. It is also possible to pass -d 0 for a specific session, which will preventthe server log level of the parent postgres process from being propagated to this session.

-D

Specifies the file system location of the database configuration files. See Section 19.2 for details.

-e

Sets the default date style to “European”, that is DMY ordering of input date fields. This also causes theday to be printed before the month in certain date output formats. See Section 8.5 for more information.

-F

Disables fsync calls for improved performance, at the risk of data corruption in the event of a systemcrash. Specifying this option is equivalent to disabling the fsync configuration parameter. Read thedetailed documentation before using this!

-h

Specifies the IP host name or address on which postgres is to listen for TCP/IP connections from clientapplications. The value can also be a comma-separated list of addresses, or * to specify listening on allavailable interfaces. An empty value specifies not listening on any IP addresses, in which case onlyUnix-domain sockets can be used to connect to the server. Defaults to listening only on localhost.Specifying this option is equivalent to setting the listen_addresses configuration parameter.

-i

Allows remote clients to connect via TCP/IP (Internet domain) connections. Without this option, only localconnections are accepted. This option is equivalent to setting listen_addresses to * in postgresql.conf orvia -h.This option is deprecated since it does not allow access to the full functionality of listen_addresses.It's usually better to set listen_addresses directly.

-k

Specifies the directory of the Unix-domain socket on which postgres is to listen for connections fromclient applications. The value can also be a comma-separated list of directories. An empty value specifiesnot listening on any Unix-domain sockets, in which case only TCP/IP sockets can be used to connect to theserver. The default value is normally /tmp, but that can be changed at build time. Specifying this optionis equivalent to setting the unix_socket_directories configuration parameter.

-l

Enables secure connections using SSL. PostgreSQL must have been compiled with support for SSL for thisoption to be available. For more information on using SSL, refer to Section 18.9.

-N

Sets the maximum number of client connections that this server will accept. The default value of thisparameter is chosen automatically by initdb. Specifying this option is equivalent to setting themax_connections configuration parameter.

-o

The command-line-style arguments specified in extra-options are passed to all server processes started bythis postgres process.Spaces within extra-options are considered to separate arguments, unless escaped with a backslash (\);write \\ to represent a literal backslash. Multiple arguments can also be specified via multiple uses of

-o.

The use of this option is obsolete; all command-line options for server processes can be specifieddirectly on the postgres command line.

-p

Specifies the TCP/IP port or local Unix domain socket file extension on which postgres is to listen forconnections from client applications. Defaults to the value of the PGPORT environment variable, or ifPGPORT is not set, then defaults to the value established during compilation (normally 5432). If youspecify a port other than the default port, then all client applications must specify the same port usingeither command-line options or PGPORT.

-s

Print time information and other statistics at the end of each command. This is useful for benchmarking orfor use in tuning the number of buffers.

-S

Specifies the amount of memory to be used by internal sorts and hashes before resorting to temporary diskfiles. See the description of the work_mem configuration parameter in Section 19.4.1.

--version

Print the postgres version and exit.

--name

Sets a named run-time parameter; a shorter form of -c.

--describe-config

This option dumps out the server's internal configuration variables, descriptions, and defaults intab-delimited COPY format. It is designed primarily for use by administration tools.

--help

Show help about postgres command line arguments, and exit.Semi-internal OptionsThe options described here are used mainly for debugging purposes, and in some cases to assist with recoveryof severely damaged databases. There should be no reason to use them in a production database setup. They arelisted here only for use by PostgreSQL system developers. Furthermore, these options might change or beremoved in a future release without notice.

-f

Forbids the use of particular scan and join methods: s and i disable sequential and index scansrespectively, o, b and t disable index-only scans, bitmap index scans, and TID scans respectively, whilen, m, and h disable nested-loop, merge and hash joins respectively.Neither sequential scans nor nested-loop joins can be disabled completely; the -fs and -fn options simplydiscourage the optimizer from using those plan types if it has any other alternative.

-n

This option is for debugging problems that cause a server process to die abnormally. The ordinary strategyin this situation is to notify all other server processes that they must terminate and then reinitializethe shared memory and semaphores. This is because an errant server process could have corrupted someshared state before terminating. This option specifies that postgres will not reinitialize shared datastructures. A knowledgeable system programmer can then use a debugger to examine shared memory andsemaphore state.

-O

Allows the structure of system tables to be modified. This is used by initdb.

-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.

-t

Print timing statistics for each query relating to each of the major system modules. This option cannot beused together with the -s option.

-T

This option is for debugging problems that cause a server process to die abnormally. The ordinary strategyin this situation is to notify all other server processes that they must terminate and then reinitializethe shared memory and semaphores. This is because an errant server process could have corrupted someshared state before terminating. This option specifies that postgres will stop all other server processesby sending the signal SIGSTOP, but will not cause them to terminate. This permits system programmers tocollect core dumps from all server processes by hand.

-v

Specifies the version number of the frontend/backend protocol to be used for a particular session. Thisoption is for internal use only.

-W

A delay of this many seconds occurs when a new server process is started, after it conducts theauthentication procedure. This is intended to give an opportunity to attach to the server process with adebugger.Options for Single-User ModeThe following options only apply to the single-user mode (see SINGLE-USER MODE).

--single

Selects the single-user mode. This must be the first argument on the command line.databaseSpecifies the name of the database to be accessed. This must be the last argument on the command line. Ifit is omitted it defaults to the user name.

-E

Echo all commands to standard output before executing them.

-j

Use semicolon followed by two newlines, rather than just newline, as the command entry terminator.

-r

Send all server log output to filename. This option is only honored when supplied as a command-lineoption.ENVIRONMENTPGCLIENTENCODINGDefault character encoding used by clients. (The clients can override this individually.) This value canalso be set in the configuration file.PGDATADefault data directory locationPGDATESTYLEDefault value of the DateStyle run-time parameter. (The use of this environment variable is deprecated.)PGPORTDefault port number (preferably set in the configuration file)DIAGNOSTICSA failure message mentioning semget or shmget probably indicates you need to configure your kernel to provideadequate shared memory and semaphores. For more discussion see Section 18.4. You might be able to postponereconfiguring your kernel by decreasing shared_buffers to reduce the shared memory consumption of PostgreSQL,and/or by reducing max_connections to reduce the semaphore consumption.A failure message suggesting that another server is already running should be checked carefully, for exampleby using the command$ ps ax | grep postgresor$ ps -ef | grep postgresdepending on your system. If you are certain that no conflicting server is running, you can remove the lockfile mentioned in the message and try again.A failure message indicating inability to bind to a port might indicate that that port is already in use bysome non-PostgreSQL process. You might also get this error if you terminate postgres and immediately restartit using the same port; in this case, you must simply wait a few seconds until the operating system closes theport before trying again. Finally, you might get this error if you specify a port number that your operatingsystem considers to be reserved. For example, many versions of Unix consider port numbers under 1024 to be“trusted” and only permit the Unix superuser to access them.NOTESThe utility command pg_ctl(1) can be used to start and shut down the postgres server safely and comfortably.If at all possible, do not use SIGKILL to kill the main postgres server. Doing so will prevent postgres fromfreeing the system resources (e.g., shared memory and semaphores) that it holds before terminating. This mightcause problems for starting a fresh postgres run.To terminate the postgres server normally, the signals SIGTERM, SIGINT, or SIGQUIT can be used. The first willwait for all clients to terminate before quitting, the second will forcefully disconnect all clients, and thethird will quit immediately without proper shutdown, resulting in a recovery run during restart.The SIGHUP signal will reload the server configuration files. It is also possible to send SIGHUP to anindividual server process, but that is usually not sensible.To cancel a running query, send the SIGINT signal to the process running that command. To terminate a backendprocess cleanly, send SIGTERM to that process. See also pg_cancel_backend and pg_terminate_backend inSection 9.26.2 for the SQL-callable equivalents of these two actions.The postgres server uses SIGQUIT to tell subordinate server processes to terminate without normal cleanup.This signal should not be used by users. It is also unwise to send SIGKILL to a server process — the mainpostgres process will interpret this as a crash and will force all the sibling processes to quit as part ofits standard crash-recovery procedure.BUGSThe -- options will not work on FreeBSD or OpenBSD. Use -c instead. This is a bug in the affected operatingsystems; a future release of PostgreSQL will provide a workaround if this is not fixed.SINGLE-USER MODETo start a single-user mode server, use a command likepostgres --single -D /usr/local/pgsql/data other-options my_databaseProvide the correct path to the database directory with -D, or make sure that the environment variable PGDATAis set. Also specify the name of the particular database you want to work in.Normally, the single-user mode server treats newline as the command entry terminator; there is no intelligenceabout semicolons, as there is in psql. To continue a command across multiple lines, you must type backslashjust before each newline except the last one. The backslash and adjacent newline are both dropped from theinput command. Note that this will happen even when within a string literal or comment.But if you use the -j command line switch, a single newline does not terminate command entry; instead, thesequence semicolon-newline-newline does. That is, type a semicolon immediately followed by a completely emptyline. Backslash-newline is not treated specially in this mode. Again, there is no intelligence about such asequence appearing within a string literal or comment.In either input mode, if you type a semicolon that is not just before or part of a command entry terminator,it is considered a command separator. When you do type a command entry terminator, the multiple statementsyou've entered will be executed as a single transaction.To quit the session, type EOF (Control+D, usually). If you've entered any text since the last command entryterminator, then EOF will be taken as a command entry terminator, and another EOF will be needed to exit.Note that the single-user mode server does not provide sophisticated line-editing features (no commandhistory, for example). Single-user mode also does not do any background processing, such as automaticcheckpoints or replication.EXAMPLESTo start postgres in the background using default values, type:$ nohup postgres >logfile 2>&1 </dev/null &To start postgres with a specific port, e.g. 1234:$ postgres -p 1234To connect to this server using psql, specify this port with the -p option:$ psql -p 1234or set the environment variable PGPORT:$ export PGPORT=1234$ psqlNamed run-time parameters can be set in either of these styles:$ postgres -c work_mem=1234$ postgres --work-mem=1234Either form overrides whatever setting might exist for work_mem in postgresql.conf. Notice that underscores inparameter names can be written as either underscore or dash on the command line. Except for short-termexperiments, it's probably better practice to edit the setting in postgresql.conf than to rely on acommand-line switch to set a parameter.