PostgreSQL/Managing the Instance


The PostgreSQL instance consists of several processes that run continuously on the server. They work together in a coordinated manner using common configuration files and RAM. Thus all are running or none of them.

The process postmaster is one of them. It starts, stops, and controls the other processes. postmaster himself can be started directly or with the help of the wrapper program pg_ctl. Its simplified syntax is:

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

The instance must be run by the operating system user postgres and not by root.

status

edit

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: 16244)
/usr/lib/postgresql/14/bin/postgres
$

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

start

edit

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

$ pg_ctl start
...
...
 done
server started
$

When you see the above message, everything works fine.

stop

edit

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

$ pg_ctl stop
...
...
 done
server stopped
$

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 sub-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] ]

restart

edit

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

reload

edit

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

init

edit

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 time

edit

In most cases, it is desired that PostgreSQL starts immediately after the server boots. Whether this happens - or not - may be configured in the file start.conf. Depending on the operation system, the file is located in different directories.

There is only one entry and its allowed values are:

  • auto: automatically start/stop at server boot/shutdown time
  • 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)