PostgreSQL User's Guide
Prev |  | Next

# pg_ctl

## Name

pg_ctl — Starts, stops, and restarts postmaster

    pg_ctl [-w] [-D datadir][-p path] [-o "options"] start
    pg_ctl [-w] [-D datadir] [-m [s[mart]|f[ast]|i[mmediate]]] stop
    pg_ctl [-w] [-D datadir] [-m [s[mart]|f[ast]|i[mmediate]]
        [-o "options"] restart
    pg_ctl [-D datadir] status

### Inputs

-w

  Wait for the database server comes up, by watching for creation of the pid file (PGDATA/postmaster.pid). Times out after 60 seconds.

-D `datadir`

  Specifies the database location for this database installation.

-p `path`

  Specifies the path to the postmaster image.

-o "`options`"

  Specifies options to be passed directly to postmaster.

  The parameters are usually surrounded by single- or double quotes to ensure that they are passed through as a group.

-m `mode`

  Specifies the shutdown mode.

  smart, s

    smart mode waits for all the clients to logout. This is the default.

  f[ast], f

    Fast mode sends SIGTERM to the backends, that means active transactions get rolled back.

  immediate, i

    Immediate mode sends SIGUSR1 to the backends and lets them abort. In this case, database recovery will be neccessary on the next startup.

start

  Start up postmaster.

stop

  Shut down postmaster.

restart

  Restart the postmaster, performing a stop/start sequence.

status

  Show the current state of postmaster.

### Outputs

`pg_ctl: postmaster is `state` (pid: `#`)`

  Postmaster status.

If there is an error condition, the backend error message will be displayed.

## Description

pg_ctl is a utility for starting, stopping or restarting postmaster.

## Usage

### Starting postmaster

To start up postmaster:

    > pg_ctl start

If -w is supplied, pg_ctl waits for the database server comes up, by watching for creation of the pid file (PGDATA/postmaster.pid), for up to 60 seconds.

Parameters to invoke postmaster are taken from the following sources:

- Path to postmaster: found in the command search path.

- Database directory: `PGDATA` environment variable.

- Other parameters: ``PGDATA`/postmaster.opts.default`.

`postmaster.opts.default` contains parameters for postmaster. With a default installation, the -S option is enabled. So pg_ctl start implies:

    postmaster -S

Note that `postmaster.opts.default` is installed by initdb from `lib/postmaster.opts.default.sample` under the Postgres installation directory (`lib/postmaster.opts.default.sample` is copied from `src/bin/pg_ctl/postmaster.opts.default.sample` while installing Postgres).

To override the default parameters you can use -D, -p and -o options.

An example of starting the postmaster, blocking until postmaster comes up is:

    > pg_ctl -w start

To specify the postmaster binary path, try:

    > pg_ctl -p /usr/local/pgsq/bin/postmaster start

For a postmaster using port 5433, and running without `fsync`, use:

    > pg_ctl -o "-o -F -p 5433" start

### Stopping postmaster

    > pg_ctl stop

stops postmaster. Using the -m switch allows one to control how the backend shuts down. -w waits for postmaster to shut down. -m specifies the shut down mode.

### Restarting postmaster

This is almost equivalent to stopping the postmaster then starting it again except that the parameters used before stopping it would be used too. This is done by saving them in $`PGDATA`/postmaster.opts file. -w, -D, -m, -fast, -immediate and -o can also be used in the restarting mode and they have same meanings as described above.

To restart postmaster in the simplest form:

    > pg_ctl restart

To restart postmaster, waiting for it to shut down and to come up:

    > pg_ctl -w restart

To restart using port 5433 and disabling fsync after restarting:

    > pg_ctl -o "-o -F -p 5433" restart

### postmaster status

To get status information from postmaster:

    > pg_ctl status

Here is a sample output from pg_ctl:

    pg_ctl: postmaster is running (pid: 13718)
    options are:
    /usr/local/src/pgsql/current/bin/postmaster
    -p 5433
    -D /usr/local/src/pgsql/current/data
    -B 64
    -b /usr/local/src/pgsql/current/bin/postgres
    -N 32
    -o '-F'

Prev | Home | Next
pgadmin | Up | pg_dump