PostgreSQL/Managing the Instance

Architecture PostgreSQL
Managing the Instance

The PostgreSQL instance consists of several processes running on a server platform. They work together in a coordinated manner using common configuration files and a common start/stop procedure. Thus all are running or none of them.

The program pg_ctl controls and observes them as a whole. When you are logged in as user postgres you can start it from a shell. The simplified syntax is:

pg_ctl [ status | start | stop | restart | reload | init ] [-U username] [-P password] [--help]


When pg_ctl runs in the status mode, it lists the actual status of the instance.

$ pg_ctl status
pg_ctl: server is running (PID: 864)
/usr/lib/postgresql/9.4/bin/postgres "-D" "/var/lib/postgresql/9.4/main" "-c" "config_file=/etc/postgresql/9.4/main/postgresql.conf"

You can observe, whether the instance is running or not, the process id (PID) of the postmaster, the directory of the cluster and the name of the configuration file.


When pg_ctl runs in the start mode, it tries to start the instance.

$ pg_ctl start
database system is ready to accept connections

When you see the above message everythink works fine.


When pg_ctl runs in the stop mode, it tries to stop the instance.

$ pg_ctl stop
database system is shut down

When you see the above message the instance is shut down, all connections to client applications are closed and no new applications can reach the database. The stop mode knows three different modes for shutting down the instance:

  • Smart mode waits for all active clients to disconnect.
  • Fast mode (the default) does not wait for clients to disconnect. All active transactions are rolled back and clients are forcibly disconnected.
  • Immediate mode aborts all server processes immediately, without a clean shutdown.

Syntax: pg_ctl stop [-m s[mart] | f[ast] | i[mmediate] ]


When pg_ctl runs in the restart mode, it performs the same actions as in a sequence of stop and start.


In the reload mode the instance reads and reloads its configuration file.


In the init mode the instance creates a complete new cluster with the 3 databases template0, template1, and postgres. This command needs the additional parameter -D datadir to know at which place in the file system it shall create the new cluster.

Automated start at boot timeEdit

In most cases it is necessary that PostgreSQL starts immediately after the server boots. Whether this happens - or not - may be configured in the file start.conf, which is located in the special directory $PGDATA (Debian/Ubuntu) or in the main directory of the cluster (RedHat). There is only one entry and its allowed values are:

  • auto: automatically start/stop
  • manual: do not start/stop automatically, but allow manually managing as described above
  • disabled: do not allow manual startup with pg_ctlcluster (this can be easily circumvented and is only meant to be a small protection for accidents)

  Architecture PostgreSQL
Managing the Instance