pg_ctl

Initialize a new PostgreSQL database cluster

$ pg_ctl [[-D|--pgdata]] [data_directory] init

$ pg_ctl [[-D|--pgdata]] [data_directory] start

$ pg_ctl [[-D|--pgdata]] [data_directory] stop

$ pg_ctl [[-D|--pgdata]] [data_directory] restart

$ pg_ctl [[-D|--pgdata]] [data_directory] reload

pg_ctl [option...] [-D ]

-D
    Specifies the absolute path to the database cluster's data directory. This option is mandatory for most commands.

-l
    Appends the server log output to the specified logfile. If not specified, the output goes to standard output or standard error.

-o
    Specifies options that are passed directly to the postmaster (or postgres) command. These options must be enclosed in single or double quotes if they contain spaces or special characters.

-p
    Specifies the absolute path to the postmaster (or postgres) executable. This is usually unnecessary as pg_ctl finds it in the same directory as itself.

-s
    Run in silent mode. No informational messages are printed to standard output or standard error, only error messages.

-t
    Specifies the maximum time (in seconds) to wait for startup or shutdown to complete. The default is 60 seconds.

-w
    Wait for the operation (start or stop) to complete. pg_ctl will return only after the server has successfully started or stopped. Useful for scripting.

-c
    Used with the stop command to attempt to clear the postmaster.pid file if it's found to be invalid. Use with caution.

-m
    Specifies the shutdown mode for the stop command. Modes are smart (default), fast, or immediate.

-P
    Allows pg_ctl to start a PostgreSQL server even if the postmaster.pid file already exists. This is generally not recommended as it could indicate a server is already running or a previous crash. Use with extreme caution.

-V, --version
    Prints the pg_ctl version and exits.

-?, --help
    Shows help about pg_ctl command line arguments and exits.

pg_ctl is a utility for managing a PostgreSQL database server instance. It simplifies common administrative tasks such as starting, stopping, restarting, reloading configuration, checking status, and promoting standby servers. It acts as a wrapper around the main PostgreSQL server process (postmaster or postgres), handling its signals and process management. It requires the data directory to be specified, typically via the -D option, to correctly identify and manage the target database cluster. While it can also initialize a new database cluster using the initdb command, its primary role is the operational control of an already initialized server.

pg_ctl must be run by the user who owns the PostgreSQL data directory. Running as root or another user can lead to permission issues or security vulnerabilities. Always ensure the correct data directory is specified with -D.
Using the -P option to force a server start is dangerous and can lead to data corruption if another server process is indeed running or if the postmaster.pid file is truly valid.

pg_ctl takes one of several commands as its first argument to specify the desired action:

start: Starts a new PostgreSQL server.
stop: Shuts down the running PostgreSQL server.
restart: Stops and then starts the PostgreSQL server. This is equivalent to running 'stop' then 'start'.
reload: Sends a SIGHUP signal to the PostgreSQL server, causing it to reload its configuration files (e.g., postgresql.conf, pg_hba.conf) without requiring a full restart.
status: Reports whether a PostgreSQL server is running in the specified data directory. If running, it shows its PID and start command.
promote: Promotes a standby server to become a primary server. This command is crucial in replication setups.
kill <signal_name>: Sends a specified signal (e.g., HUP, INT, QUIT, TERM) to the server process. Generally used for advanced troubleshooting.
logrotate: Closes the server's current log file, allowing a new one to be opened. Useful for log rotation scripts.
initdb: Initializes a new PostgreSQL database cluster in the specified data directory. This command should only be run once for a new cluster.
register / unregister: (Windows-specific) Registers or unregisters the PostgreSQL server as a Windows service.

When stopping the server with pg_ctl stop -m <mode>, you can choose from three shutdown modes:

smart (default): Waits for all clients to disconnect. New connections are prevented. Once all clients are disconnected, the server shuts down. This is the safest mode.
fast: Disconnects all clients immediately and rolls back all in-progress transactions. The server then shuts down. This mode is faster but can interrupt ongoing operations.
immediate: Kills the postmaster process without any graceful shutdown. This is the fastest but also the most aggressive mode, equivalent to kill -9. It can lead to a crash recovery on the next startup and should only be used in emergencies.

pg_ctl has been a fundamental utility in the PostgreSQL ecosystem since its early days (e.g., PostgreSQL 6.0 and earlier). Its introduction significantly simplified the administration of PostgreSQL servers by providing a consistent interface for common lifecycle operations, abstracting away the direct manipulation of postmaster signals. Over time, new commands like 'promote' were added to support advanced features such as streaming replication, but its core function as the primary server control utility has remained constant and central to PostgreSQL administration.

postgres(1), initdb(1), psql(1), pg_isready(1)