From 5266f221a2e1358cc2bb208b3d25e9dec427c757 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Sun, 18 Jun 2006 15:38:37 +0000 Subject: Merge postmaster and postgres command into just postgres. postmaster symlink is kept for now for compatibility. To call single-user mode, use postgres --single. --- doc/src/sgml/ref/postgres-ref.sgml | 775 ++++++++++++++++++++++++++++++------- 1 file changed, 644 insertions(+), 131 deletions(-) (limited to 'doc/src/sgml/ref/postgres-ref.sgml') diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml index 1cf8521bebb..bbc3d29e5d6 100644 --- a/doc/src/sgml/ref/postgres-ref.sgml +++ b/doc/src/sgml/ref/postgres-ref.sgml @@ -1,29 +1,28 @@ - + - postgres + postgres 1 Application postgres - run a PostgreSQL server in single-user mode + PostgreSQL database server - postgres (the program) + postgres postgres option - database @@ -31,123 +30,337 @@ PostgreSQL documentation Description - The postgres executable is the actual - PostgreSQL server process that processes - SQL statements. It is normally not called directly; instead a - multiuser server is started. - Conceptually, the postmaster starts a new - postgres process for each connection. - (postmaster and postgres - are in fact the same program, and on most platforms the connection - process is forked). + postgres is the + PostgreSQL database server. In order + for a client application to access a database it connects (over a + network or locally) to a running postgres process. + The postgres instance then starts a separate server + process to handle the connection. - If the postgres command is called directly, it - invokes the server in interactive single-user mode. The primary - use for this mode is during bootstrapping by . Sometimes it is used for debugging or - disaster recovery. - 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. + One postgres instance always manages the data from + 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 one + postgres process can run on a system at one + time, so long as they use different data areas and different + communication ports (see below). When + postgres starts it needs to know the location + of the data area. The location must be specified by the + option or the PGDATA environment + variable; there is no default. Typically, or + PGDATA points directly to the data area directory + created by initdb. Other possible file layouts are + discussed in . A + data area is created with . - 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 + By default postgres starts in the + foreground and prints log messages to the standard error stream. In + practical applications the postgres + should be started as a background process, perhaps at boot time. + + + + The postgres command can also be called in + single-user mode. The primary use for this mode is during + bootstrapping by . Sometimes it is used + for debugging or disaster recovery. 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. 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 + superuser powers are granted to the user with ID 1 in single-user mode. - + Options - When postgres is started by a then it inherits all options set by the - latter. In single-user mode, postgres accepts - all the options that postmaster would accept. - - - - You can avoid having to type these options by setting up a - configuration file. See for details. Some - (safe) options can also be set from the connecting client in an - application-dependent way. For example, if the environment - variable PGOPTIONS is set, then - libpq-based clients will pass that string to the - server, which will interpret it as + postgres accepts the following command-line + arguments. For a detailed discussion of the options consult . 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 variable PGOPTIONS is + set, then libpq-based clients will pass that + string to the server, which will interpret it as postgres command-line options. General Purpose + + + + + + + Enables run-time assertion checks, which is a debugging aid to + detect programming mistakes. This option is only available if + assertions were enabled when PostgreSQL was + compiled. If so, the default is on. + + + - - The options , , - , , , - , , , - , and - have the same meanings as with the - except that -d 0 prevents the server log level of the - postmaster from being propagated to - postgres. Other postmaster - options are also accepted but will have no noticeable effect - because they only apply to the multiuser server mode, namely - , , , - , and . - - + + + + + Sets the number of shared buffers for use by the server + processes. The default value of this parameter is chosen + automatically by initdb; refer to for more information. + + + - - Options for stand-alone mode + + + + + Sets a named run-time parameter. The configuration parameters + supported by PostgreSQL are + described in . Most of the + other command line options are in fact short forms of such a + parameter assignment. + + - - database + - Specifies the name of the database to be accessed. If it is - omitted it defaults to the user name. + Sets the debug level. The higher this value is set, the more + debugging output is written to the server log. Values are + from 1 to 5. It is also possible to pass -d + 0 for a specific session, which will prevent the + server log level of the postgres from being + propagated to this session. - + - Echo all commands. + Specifies the file system location of the data directory or + configuration file(s). See + for details. - + - Disables use of newline as a statement delimiter. + Sets the default date style to European, that is + DMY ordering of input date fields. This also causes + the day to be printed before the month in certain date output formats. + See for more information. - filename + + + + Disables fsync calls for improved + performance, at the risk of data corruption in the event of a + system crash. Specifying this option is equivalent to + disabling the configuration + parameter. Read the detailed documentation before using this! + + + + has the opposite effect + of this option. + + + + + + + + + Specifies the IP host name or address on which + postgres is to listen for TCP/IP + connections from client applications. The value can also be a + comma-separated list of addresses, or * to specify + listening on all available interfaces. An empty value + specifies not listening on any IP addresses, in which case + only Unix-domain sockets can be used to connect to the + postgres. Defaults to listening only on + localhost. + Specifying this option is equivalent to setting the configuration parameter. + + + + + + + + + Allows remote clients to connect via TCP/IP (Internet domain) + connections. Without this option, only local connections are + accepted. This option is equivalent to setting + listen_addresses to * in + postgresql.conf or via + + This option is deprecated since it does not allow access to the + full functionality of . + It's usually better to set listen_addresses directly. + + + + + + + + + Specifies the directory of the Unix-domain socket on which + postgres is to listen for + connections from client applications. The default is normally + /tmp, but can be changed at build time. + + + + + + + + + Enables secure connections using SSL. + PostgreSQL must have been compiled with + support for SSL for this option to be + available. For more information on using SSL, + refer to . + + + + + + - Send all server log output to - filename. - If postgres is running under the - postmaster, this option is ignored, - and the stderr inherited from the - postmaster is used. + Sets the maximum number of client connections that this + postgres will accept. By + default, this value is 32, but it can be set as high as your + system will support. (Note that + is required to be at least twice + . See for a discussion of + system resource requirements for large numbers of client + connections.) Specifying this option is equivalent to setting the + configuration parameter. + + + + + + + + + The command line-style options specified in extra-options are passed to + all server processes started by this + postgres. If the option string contains + any spaces, the entire string must be quoted. + + + + The use of this option is obsolete; all command-line options + for server processes can be specified directly on the + postgres command line + + + + + + + + + Specifies the TCP/IP port or local Unix domain socket file + extension on which postgres + is to listen for connections from client applications. + Defaults to the value of the PGPORT environment + variable, or if PGPORT is not set, then + defaults to the value established during compilation (normally + 5432). If you specify a port other than the default port, + then all client applications must specify the same port using + either command-line options or PGPORT. + + + + + + + + + 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. + + + + + + + + + Specifies that the postgres + process should start up in silent mode. That is, it will + disassociate from the user's (controlling) terminal, start its + own process group, and redirect its standard output and + standard error to /dev/null. + + + Using this switch discards all logging output, which is + probably not what you want, since it makes it very difficult + to troubleshoot problems. See below for a better way to start + postgres in the background. + + + has the opposite effect + of this option. + + + + + + + + + Sets a named run-time parameter; a shorter form of + + + + + + + + + This option dumps out the server's internal configuration variables, + descriptions, and defaults in tab-delimited COPY format. + It is designed primarily for use by administration tools. @@ -158,46 +371,199 @@ PostgreSQL documentation Semi-internal Options - The options , , - , , and - have the same meanings as with the and are reserved for debugging and - disaster recovery. Further options for internal use are: + There are several other options that may be specified, used + mainly for debugging purposes and in some cases to assist with + recovery of severely damaged databases. There should be no reason + to use them in a production database setup. These are listed + here only for the use by PostgreSQL + system developers. Furthermore, any of these options may + disappear or change in a future release without notice. + + + { s | i | m | n | h } + + + Forbids the use of particular scan and join methods: + s and i + disable sequential and index scans respectively, while + n, 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 simply discourage the optimizer + from using those plan types if it has any other alternative. + + + + + + + + + This option is for debugging problems that cause a server + process to die abnormally. The ordinary strategy in this + situation is to notify all other server processes that they + must terminate and then reinitialize the shared memory and + semaphores. This is because an errant server process could + have corrupted some shared state before terminating. This + option specifies that postgres will + not reinitialize shared data structures. A knowledgeable + system programmer can then use a debugger to examine shared + memory and semaphore state. + + + + + + + + + Allows the structure of system tables to be modified. This is + used by initdb. + + + + + + + + + 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. + + + + + + pa[rser] | pl[anner] | e[xecutor] + + + Print timing statistics for each query relating to each of the + major system modules. This option cannot be used together + with the option. + + + + + + + + + This option is for debugging problems that cause a server + process to die abnormally. The ordinary strategy in this + situation is to notify all other server processes that they + must terminate and then reinitialize the shared memory and + semaphores. This is because an errant server process could + have corrupted some shared state before terminating. This + option specifies that postgres will + stop all other server processes by sending the signal + SIGSTOP, but will not cause them to + terminate. This permits system programmers to collect core + dumps from all server processes by hand. + + + + protocol Specifies the version number of the frontend/backend protocol - to be used for this particular session. + to be used for a particular session. This option is for + internal use only. - database + seconds - Indicates that this process has been started by a - postmaster and specifies the database to use. - etc. + A delay of this many seconds occurs when a new server process + is started, after it conducts the authentication procedure. + This is intended to give an opportunity to attach to the + server process with a debugger. - + database - This option dumps out the server's internal configuration variables, - descriptions, and defaults in tab-delimited COPY format. - It is designed primarily for use by administration tools. + Indicates that this is a subprocess started by + postgres and specifies the database to + use. This option is for internal use only. + + + + Options for single-user mode + + + The following options only apply to the single-user mode. + + + + + + + Selects the single-user mode. This must be the first argument + on the command line. + + + + + + database + + + Specifies the name of the database to be accessed. If it is + omitted it defaults to the user name. + + + + + + + + + Echo all commands. + + + + + + + + + Disables use of newline as a statement delimiter. + + + + + + filename + + + Send all server log output to filename. In normal multiuser + mode, this option is ignored, and stderr is + used by all processes. + + + + @@ -205,6 +571,18 @@ PostgreSQL documentation Environment + + PGCLIENTENCODING + + + + Default character encoding used by clients. (The clients may + override this individually.) This value can also be set in the + configuration file. + + + + PGDATA @@ -214,47 +592,154 @@ PostgreSQL documentation + + + PGDATESTYLE + + + + Default value of the run-time + parameter. (The use of this environment variable is deprecated.) + + + + + + PGPORT + + + + Default port (preferably set in the configuration file) + + + + + + TZ + + + + Server time zone + + + + + + Diagnostics + + + A failure message mentioning semget or + shmget probably indicates you need to configure your + kernel to provide adequate shared memory and semaphores. For more + discussion see . You may be able + to postpone reconfiguring your kernel by decreasing to reduce the shared memory + consumption of PostgreSQL, and/or by reducing + 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 may remove the lock file mentioned in the + message and try again. + + + + A failure message indicating inability to bind to a port may + indicate that that port is already in use by some + non-PostgreSQL process. You may also + get this error if you terminate postgres + 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 may 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 + + + If at all possible, do not use + SIGKILL to kill the main + postgres server. Doing so will prevent + postgres from freeing the system + resources (e.g., shared memory and semaphores) that it holds before + terminating. This may cause problems for starting a fresh + postgres run. + - To cancel a running query, send the SIGINT signal - to the postgres process running that command. + To terminate the postgres server normally, the + signals SIGTERM, SIGINT, or + SIGQUIT 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. The SIGHUP signal will reload + the server configuration files. It is also possible to send + SIGHUP to an individual server process, but that + is usually not sensible. + + + + The utility command can be used to + start and shut down the postgres server + safely and comfortably. - To tell postgres to reload the configuration files, - send a SIGHUP signal. Normally it's best to - SIGHUP the postmaster instead; - the postmaster will in turn SIGHUP - each of its children. But in some cases it might be desirable to have only - one postgres process reload the configuration files. + To cancel a running query, send the SIGINT signal + to the process running that command. - The postmaster uses SIGTERM - to tell a postgres process to quit normally and + The postgres server uses SIGTERM + to tell subordinate server processes to quit normally and SIGQUIT to terminate without the normal cleanup. - These signals should not be used by users. It is also - unwise to send SIGKILL to a postgres - process — the postmaster will interpret this as - a crash in postgres, and will force all the sibling - postgres processes to quit as part of its standard - crash-recovery procedure. + These signals should not be used by users. It + is also unwise to send SIGKILL to a server + process — the main postgres 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 Usage - Start a stand-alone server with a command like + To start a single-user mode server, use a command like -postgres -D /usr/local/pgsql/data other-options my_database +postgres --single -D /usr/local/pgsql/data other-options my_database Provide the correct path to the database directory with - Normally, the stand-alone server treats newline as the command + Normally, the single-user mode server treats newline as the command entry terminator; there is no intelligence about semicolons, as there is in psql. To continue a command across multiple lines, you must type backslash just before each @@ -285,10 +770,57 @@ PostgreSQL documentation - Note that the stand-alone server does not provide sophisticated + Note that the single-user mode server does not provide sophisticated line-editing features (no command history, for example). + + + + Examples + + To start postgres in the background + using default values, type: + + +$ nohup postgres >logfile 2>&1 </dev/null & + + + + + To start postgres with a specific + port: + +$ postgres -p 1234 + + This command will start up postgres + communicating through the port 1234. In order to connect to this + postgres using psql, you would need to + run it as + +$ psql -p 1234 + + or set the environment variable PGPORT: + +$ 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 for + work_mem in postgresql.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 in + postgresql.conf than to rely on a command-line switch + to set a parameter. + @@ -296,26 +828,7 @@ PostgreSQL documentation , - , - + - - - -- cgit v1.2.3