Movatterモバイル変換

postgres

postgres —Postgres Pro database server

Synopsis

Description

postgres is thePostgres Pro database server. In order for a client application to access a database it connects (over a network or locally) to a runningpostgres instance. Thepostgres instance then starts a separate server process to handle the connection.

Onepostgres instance always manages the data of exactly one database cluster. A database cluster is a collection of databases that is stored at a common file system location (the“data area”). More than onepostgres instance can run on a system at one time, so long as they use different data areas and different communication ports (see below). Whenpostgres starts it needs to know the location of the data area. The location must be specified by the-D option or thePGDATA environment variable; there is no default. Typically,-D orPGDATA points directly to the data area directory created byinitdb. Other possible file layouts are discussed inSection 18.2.

By defaultpostgres starts in the foreground and prints log messages to the standard error stream. In practical applicationspostgres should be started as a background process, perhaps at boot time.

Thepostgres command can also be called in single-user mode. The primary use for this mode is during bootstrapping byinitdb. Sometimes it is used for debugging or disaster recovery; note that running a single-user server is not truly suitable for debugging the server, since no realistic interprocess communication and locking will happen. When invoked in single-user 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. In the single-user mode, the session user will be set to the user with ID 1, and implicit superuser powers are granted to this user. This user does not actually have to exist, so the single-user mode can be used to manually recover from certain kinds of accidental damage to the system catalogs.

Options#

postgres accepts the following command-line arguments. For a detailed discussion of the options consultChapter 18. You can save typing most of these options by setting up a configuration file. Some (safe) options can also be set from the connecting client in an application-dependent way to apply only for that session. For example, if the environment variablePGOPTIONS is set, thenlibpq-based clients will pass that string to the server, which will interpret it aspostgres command-line options.

Environment

Diagnostics

A failure message mentioningsemget orshmget probably indicates you need to configure your kernel to provide adequate shared memory and semaphores. For more discussion seeSection 17.4. You might be able to postpone reconfiguring your kernel by decreasingshared_buffers to reduce the shared memory consumption ofPostgres Pro, and/or by reducingmax_connections to reduce the semaphore consumption.

A failure message suggesting that another server is already running should be checked carefully, for example by using the command

$ps ax | grep postgres

or

$ps -ef | grep postgres

depending on your system. If you are certain that no conflicting server is running, you can remove the lock file 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 by some non-Postgres Pro process. You might also get this error if you terminatepostgres 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 might 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“trusted” and only permit the Unix superuser to access them.

Notes

The utility commandpg_ctl can be used to start and shut down thepostgres server safely and comfortably.

If at all possible,do not useSIGKILL to kill the mainpostgres server. Doing so will preventpostgres from freeing the system resources (e.g., shared memory and semaphores) that it holds before terminating. This might cause problems for starting a freshpostgres run.

To terminate thepostgres server normally, the signalsSIGTERM,SIGINT, orSIGQUIT 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.

TheSIGHUP signal will reload the server configuration files. It is also possible to sendSIGHUP to an individual server process, but that is usually not sensible.

To cancel a running query, send theSIGINT signal to the process running that command. To terminate a backend process cleanly, sendSIGTERM to that process. See alsopg_cancel_backend andpg_terminate_backend inSection 9.28.2 for the SQL-callable equivalents of these two actions.

Thepostgres server usesSIGQUIT to tell subordinate server processes to terminate without normal cleanup. This signalshould not be used by users. It is also unwise to sendSIGKILL to a server process — the mainpostgres process will interpret this as a crash and will force all the sibling processes to quit as part of its standard crash-recovery procedure.

Bugs#

The-- options will not work onFreeBSD orOpenBSD. Use-c instead. This is a bug in the affected operating systems; a future release ofPostgres Pro will provide a workaround if this is not fixed.

Single-User Mode#

To start a single-user mode server, use a command like

postgres --single -D /usr/local/pgsql/dataother-options my_database

Provide the correct path to the database directory with-D, or make sure that the environment variablePGDATA is 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 intelligence about semicolons, as there is inpsql. To continue a command across multiple lines, you must type backslash just before each newline except the last one. The backslash and adjacent newline are both dropped from the input 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, the sequence semicolon-newline-newline does. That is, type a semicolon immediately followed by a completely empty line. Backslash-newline is not treated specially in this mode. Again, there is no intelligence about such a sequence 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 statements you've entered will be executed as a single transaction.

To quit the session, typeEOF (Control+D, usually). If you've entered any text since the last command entry terminator, thenEOF will be taken as a command entry terminator, and anotherEOF will be needed to exit.

Note that the single-user mode server does not provide sophisticated line-editing features (no command history, for example). Single-user mode also does not do any background processing, such as automatic checkpoints or replication.

Examples#

To startpostgres in the background using default values, type:

$nohup postgres >logfile 2>&1 </dev/null &

To startpostgres with a specific port, e.g., 1234:

$postgres -p 1234

To connect to this server usingpsql, specify this port with the -p option:

$psql -p 1234

or set the environment variablePGPORT:

$export PGPORT=1234$psql

Named run-time parameters can be set in either of these styles:

$postgres -c work_mem=1234$postgres --work-mem=1234

Either form overrides whatever setting might exist forwork_mem inpostgresql.conf. Notice that underscores in parameter names can be written as either underscore or dash on the command line. Except for short-term experiments, it's probably better practice to edit the setting inpostgresql.conf than to rely on a command-line switch to set a parameter.

See Also

initdb,pg_ctl