Databases - Practical PostgreSQL

Databases - Practical PostgreSQL
Previous Page	Home	Next Page

Using pg_ctl

The pg_ctl script is provided with PostgreSQL as a general control application. With it, you can start, stop, restart, or check on the status of PostgreSQL.

Here is the syntax for pg_ctl , from the - -help option:

  pg_ctl start   [-w] [-D 
DATADIR
 ] [-s] [-l 
FILENAME
 ] [-o "
OPTIONS
"]
  pg_ctl stop    [-W] [-D 
DATADIR
 ] [-s] [-m 
SHUTDOWN-MODE
 ]
  pg_ctl restart [-w] [-D 
DATADIR
 ] [-s] [-m 
SHUTDOWN-MODE
 ] [-o "
OPTIONS
"]
  pg_ctl status  [-D 
DATADIR
]

The following options may be passed to pg_ctl :

-w

Causes the pg_ctl application to wait until the operation has finished before returning to a command line. This option may be passed to either the start or restart action; by default, the application sends the command on to the postmaster and exits immediately for these actions.

-W

Causes the pg_ctl application not to wait until the operation has finished before returning to a command line. This option may only be passed to the stop action; by default, the application sends the stop command on to the postmaster , and waits for the action to finish before exiting.

-D DATADIR

Specifies the directory that contains the default database files. This is optional, because you may have this value already set in the PGDATA environment variable. If the PGDATA environment variable is not set, the -D flag is required.

-s

Suppresses any output from the pg_ctl application, aside from system errors. If this flag is not specified, information about the activity within the database (or specific information about startup or shutdown, depending on the action) will be displayed to the screen of the user who initiated the command.

-l FILENAME

Specifies a file FILENAME to append database activity to. This option is only available with the start action.

-m SHUTDOWN-MODE

Sets the SHUTDOWN-MODE with which to shut down the postmaster backend.

smart: Makes postmaster wait for all clients to disconnect before shutting down.
fast: Shuts postmaster down without waiting for clients to disconnect.
immediate: Shuts postmaster down more abruptly than fast mode, bypassing normal shutdown procedures. This mode causes the database to restart in recovery mode the next time it starts, which verifies the integrity of the system.

This option is of course only available to the stop and restart actions.

-o "OPTIONS"

Passes the options specified by OPTIONS (within double quotes) to be passed directly through to the postmaster (e.g., the -i flag to enable TCP/IP connections). See the Section called Calling postmaster Directly " later in this chapter for a complete list of these flags.

Note: Many of the run-time configuration options for postmaster can be found in the postgresql.conf file, which is stored in the PostgreSQL data path (e.g., /usr/local/pgsql/data ). The options in this file are of a more technical nature, and should not be modified unless you are sure you understand their purpose.

Starting PostgreSQL with pg_ctl

To start PostgreSQL's postmaster backend, the start argument must be passed to pg_ctl . Remember that pg_ctl must be run by the postgres user (or whatever user you have configured to own the PostgreSQL data path).

Example 9-1 starts the postmaster backend, using the data path of /usr/local/pgsql/data . The database system starts up successfully, reports the last time the database system was shut down, and provides various debugging statements before returning the postgres user to a shell prompt.

Example 9-1. Starting PostgreSQL with pg_ctl

[postgres@booktown ~]$ 
pg_ctl -D /usr/local/pgsql/data start

postmaster successfully started
DEBUG:  database system was shut down at 2001-09-17 08:06:34 PDT
DEBUG:  CheckPoint record at (0, 1000524052)
DEBUG:  Redo record at (0, 1000524052); Undo record at (0, 0); Shutdown TRUE
DEBUG:  NextTransactionId: 815832; NextOid: 3628113
DEBUG:  database system is in production state

[postgres@booktown ~]$

Stopping PostgreSQL with pg_ctl

The PostgreSQL postmaster backend can be stopped in the same fashion that it is started—by passing the stop argument to pg_ctl . The application pg_ctl checks for the running postmaster process, and, if the stop command was executed by the user who owns the running processes (e.g., postgres ) the server is shut down.

There are three ways in which PostgreSQL can shut down the backend: smart , fast , and immediate . These arguments are passed to pg_ctl following the -m flag, to indicate the desired shutdown mode.

A smart shutdown (the default) causes PostgreSQL to wait for all clients to first cancel their connections before shutting down. A fast shutdown causes PostgreSQL to simply shut down through its normal routine, without checking client status. An immediate shutdown bypasses the normal shutdown procedure, and will require the system to go through a recovery mode when restarted.

Warning

Never use kill -9 ( kill -KILL ) on the postmaster process. This can result in lost or corrupted data.

Example 9-2 calls the pg_ctl script to stop the postmaster process in fast mode. The postmaster backend will not wait for any client connections to disconnect before shutting down.

Example 9-2. Stopping PostgreSQL with pg_ctl

[postgres@booktown ~]$ 
pg_ctl -D /usr/local/pgsql/data stop -m fast

Fast Shutdown request at Mon Sep 17 09:23:39 2001
DEBUG:  shutting down
waiting for postmaster to shut down.....
DEBUG:  database system is shut down
done
postmaster successfully shut down
[postgres@booktown ~]$

Note: The smart shutdown is equivalent to a kill -TERM on the running postmaster process, while fast is equivalent to a kill -INT , and immediate is equivalent to a kill -QUIT .

Restarting PostgreSQL with pg_ctl

You may pass the restart argument to pg_ctl as shorthand for sequential stop and start calls to pg_ctl . This argument may also specify the -m flag to indicate the preferred shutdown mode.

PostgreSQL stores the most recently used start-up options in a temporary file called postmaster.opts , within the PostgreSQL data path (PGDATA). This file is used when pg_ctl is invoked with the restart argument to ensure that your run-time options are preserved. Avoid placing your own configurations on the postmaster.opts file, as it will be overwritten when pg_ctl is executed with the start argument.

Example 9-3 restarts the Book Town database server with the postgres user.

Example 9-3. Restarting PostgreSQL with pg_ctl

[postgres@booktown ~]$ 
pg_ctl -D /usr/local/pgsql/data restart

Smart Shutdown request at Mon Sep 17 08:33:51 2001
DEBUG:  shutting down
waiting for postmaster to shut down.....DEBUG:  database system is shut down
done
postmaster successfully shut down
postmaster successfully started
[postgres@booktown ~]$
DEBUG:  database system was shut down at 2001-09-17 08:33:53 PDT
DEBUG:  CheckPoint record at (0, 1000524116)
DEBUG:  Redo record at (0, 1000524116); Undo record at (0, 0); Shutdown TRUE
DEBUG:  NextTransactionId: 815832; NextOid: 3628113
DEBUG:  database system is in production state

[postgres@booktown ~]$

Checking status of PostgreSQL with pg_ctl

You may use the status argument to check the status of a running postmaster process. While not having any effect on the data itself, the data path must be known to pg_ctl . If the PGDATA environmental variable is not set, the -D flag must be passed to pg_ctl .

Example 9-4 checks the status of the Book Town PostgreSQL server.

Example 9-4. Checking status with pg_ctl

[postgres@booktown ~]$ 
pg_ctl -D /usr/local/pgsql/data status

pg_ctl: postmaster is running (pid: 11575)
Command line was:
/usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-i' '-s'
[postgres@booktown ~]$

Note: A lot of typing can be saved by making sure the PGDATA variable is set. If you intend to always use the same data directory, you may set the PGDATA variable (e.g., in the /etc/profile file, as is recommended in Chapter 2) and never have to apply the -D flag.

Databases - Practical PostgreSQL
Previous Page	Home	Next Page