Home Explore Blog CI



postgresql

3rd chunk of `doc/src/sgml/ref/pg_ctl-ref.sgml`
2266ea401a96ee94d32fdc3abf6f1f97a47968f8dd0847350000000100000faa
 encapsulates tasks such
   as redirecting log output and properly detaching from the terminal
   and process group. It also provides convenient options for
   controlled shutdown.
  </para>

  <para>
   The <option>init</option> or <option>initdb</option> mode creates a new
   <productname>PostgreSQL</productname> database cluster, that is,
   a collection of databases that will be managed by a single
   server instance.  This mode invokes the <command>initdb</command>
   command.  See <xref linkend="app-initdb"/> for details.
  </para>

  <para>
   <option>start</option> mode launches a new server.  The
   server is started in the background, and its standard input is attached
   to <filename>/dev/null</filename> (or <literal>nul</literal> on Windows).
   On Unix-like systems, by default, the server's standard output and
   standard error are sent to <application>pg_ctl</application>'s
   standard output (not standard error).  The standard output of
   <application>pg_ctl</application> should then be redirected to a
   file or piped to another process such as a log rotating program
   like <application>rotatelogs</application>; otherwise <command>postgres</command>
   will write its output to the controlling terminal (from the
   background) and will not leave the shell's process group.  On
   Windows, by default the server's standard output and standard error
   are sent to the terminal.  These default behaviors can be changed
   by using <option>-l</option> to append the server's output to a log file.
   Use of either <option>-l</option> or output redirection is recommended.
  </para>

  <para>
   <option>stop</option> mode shuts down the server that is running in
   the specified data directory.  Three different
   shutdown methods can be selected with the <option>-m</option>
   option.  <quote>Smart</quote> mode disallows new connections, then waits
   for all existing clients to disconnect.
   If the server is in hot standby, recovery and streaming replication
   will be terminated once all clients have disconnected.
   <quote>Fast</quote> mode (the default) does not wait for clients to disconnect.
   All active transactions are
   rolled back and clients are forcibly disconnected, then the
   server is shut down.  <quote>Immediate</quote> mode will abort
   all server processes immediately, without a clean shutdown.  This choice
   will lead to a crash-recovery cycle during the next server start.
  </para>

  <para>
   <option>restart</option> mode effectively executes a stop followed
   by a start.  This allows changing the <command>postgres</command>
   command-line options, or changing configuration-file options that
   cannot be changed without restarting the server.
   If relative paths were used on the command line during server
   start, <option>restart</option> might fail unless
   <application>pg_ctl</application> is executed in the same current
   directory as it was during server start.
  </para>

  <para>
   <option>reload</option> mode simply sends the
   <command>postgres</command> server process a <systemitem>SIGHUP</systemitem>
   signal, causing it to reread its configuration files
   (<filename>postgresql.conf</filename>,
   <filename>pg_hba.conf</filename>, etc.).  This allows changing
   configuration-file options that do not require a full server restart
   to take effect.
  </para>

  <para>
   <option>status</option> mode checks whether a server is running in
   the specified data directory. If it is, the server's <acronym>PID</acronym>
   and the command line options that were used to invoke it are displayed.
   If the server is not running, <application>pg_ctl</application> returns
   an exit status of 3.  If an accessible data directory is not
   specified, <application>pg_ctl</application> returns an exit status of 4.
  </para>

  <para>
   <option>promote</option> mode commands the standby server that is
   running in the specified data directory to end standby mode
   and begin read-write operations.

Title: pg_ctl Modes of Operation: Init, Start, Stop, Restart, Reload, Status, and Promote
Summary
This section describes the different modes of operation for `pg_ctl`. The `init` mode creates a new database cluster, invoking `initdb`. The `start` mode launches a server in the background, handling standard input and output. The `stop` mode shuts down the server, offering smart, fast, and immediate shutdown methods. The `restart` mode combines stop and start, allowing changes to command-line or configuration options. The `reload` mode sends a SIGHUP signal to reread configuration files. The `status` mode checks if a server is running, displaying its PID and command-line options. The `promote` mode converts a standby server to read-write mode.