The first task you need to be familiar with is starting and stopping your database server. When you start PostgreSQL, what you are doing is launching the postmaster executable, which fires up a process for itself, as well as two subprocesses, one for statistics processing and one for
594 C H A P T E R 2 6 ■ P O S T G R E S Q L A D M I N I S T R A T I O N
buffer processing. While you can call this postmaster executable process directly, the recom- mended way is to use the pg_ctl program.
Using pg_ctl
This program can be used for both starting and stopping PostgreSQL, and provides a number of options for doing so. First, take a look at Table 26-1, which lists and describes the different command types that can be involved with pg_ctl.
As you can see, the pg_ctl command is quite versatile for controlling your PostgreSQL database server. In addition to these command modes, pg_ctl also takes a number of different options, which are listed and described in Table 26-2.
Table 26-1. pg_ctl Command Modes Command Explanation
start Starts a new postmaster process stop Stops a running postmaster process
restart Stops a running postmaster and then starts it again
reload Sends a signal to the postmaster to reload its configuration files status Determines if a postmaster is currently running
kill Sends a specific signal to a specified process (new in PostgreSQL 8.0) register Allows you to register a system service on Windows platforms
unregister Allows you to unregister a system service that was previously registered
Table 26-2. pg_ctl Options Option Explanation
–D datadir Specifies the location of the PostgreSQL database files. Defaults to whatever PGDATA is set to.
–l filename Logs server output to the file specified. Creates the file if it does not exist.
–m mode Specifies the shutdown mode (smart, fast, or immediate).
–o options Allows specific options to be passed directly to the postmaster process.
–p path Specifies the location of the postmaster executable. Defaults to the same directory as pg_ctl.
–s Specifies that no informational messages will be output, only errors.
–w Waits (up to 60 seconds) for the start or shutdown to complete. Defaults to shutdown.
–W Do not wait for start or shutdown to complete. Defaults to start and restart.
–N On Windows, specifies the name of the system service to register.
Since there are a number of command modes and options, there are bound to be some cases that do not apply to your situation. However, let’s take a closer look at some common examples to better show how the command syntax comes together.
The following command starts PostgreSQL, waiting for the server to complete startup before returning, and logging any output to the file called my_log:
pg_ctl -w -l my_log start
The following is the most aggressive of the three ways to stop PostgreSQL using pg_ctl:
pg_ctl stop -m immediate
The different stop modes work as follows:
• Smart mode: The default stop mode; it waits for all clients to disconnect and then shuts down the server.
• Fast mode: Causes all active transactions to be rolled back, forcibly disconnects any client connections, and then shuts down the server.
• Immediate mode: Simply aborts all active server processes before shutting down. Since this is not a clean shutdown, the server goes through a recovery run upon restart.
In general, it is best to attempt to stop PostgreSQL with the least forcible stop mode, and then increase its aggressiveness if needed.
The following command would restart the PostgreSQL server, making it run on port 5480 after restart:
pg_ctl -o "port=5480" restart
The following command causes the database initialized in /var/lib/pgsql/data to reread its configuration files. This is a commonly executed command when changing configuration settings in the postgresql.conf or pg_hba.conf files.
pg_ctl -D /var/lib/pgsql/data reload
Operating System Commands
Many operating systems (OSs) have their own ways to start and stop a PostgreSQL server. Usually, these options are created by packages for that specific operating system. Since those options are platform-dependent, we won’t go into the details of each of these methods. However, you should be aware that there may be another method for starting and stopping your server.
Table 26-3 lists several operating systems and their alternative methods for starting the PostgreSQL server. For more details on these methods, please consult the documentation provided with either your OS or the package that installs PostgreSQL on your system.
–U On Windows, specifies the username for the user to start the service.
–P On Windows, specifies the password for the user to start the service.
Table 26-2. pg_ctl Options Option Explanation
596 C H A P T E R 2 6 ■ P O S T G R E S Q L A D M I N I S T R A T I O N