Postgresql 中文操作指南

pg_ctl

pg_ctl — 初始化、启动、停止或控制 PostgreSQL 服务器

Synopsis

pg_ctl init[db] [ -D datadir ] [ -s ] [ -o initdb-options ]

pg_ctl start [ -D datadir ] [ -l filename ] [ -W ] [ -t seconds ] [ -s ] [ -o options ] [ -p path ] [ -c ]

pg_ctl stop [ -D datadir ] [ -m s[mart] | f[ast] | i[mmediate] ] [ -W ] [ -t seconds ] [ -s ]

pg_ctl restart [ -D datadir ] [ -m s[mart] | f[ast] | i[mmediate] ] [ -W ] [ -t seconds ] [ -s ] [ -o options ] [ -c ]

pg_ctl reload [ -D datadir ] [ -s ]

pg_ctl status [ -D datadir ]

pg_ctl promote [ -D datadir ] [ -W ] [ -t seconds ] [ -s ]

pg_ctl logrotate [ -D datadir ] [ -s ]

pg_ctl kill signal_name process_id

在 Microsoft Windows 上，还有：

pg_ctl register [ -D datadir ] [ -N servicename ] [ -U username ] [ -P password ] [ -S a[uto] | d[emand] ] [ -e source ] [ -W ] [ -t seconds ] [ -s ] [ -o options ]

pg_ctl unregister [ -N servicename ]

Description

pg_ctl 是用于初始化 PostgreSQL 数据库群集、启动、停止或重新启动 PostgreSQL 数据库服务器 ( postgres )，或显示正在运行服务器状态的实用工具。虽然可以手动启动服务器，但 pg_ctl 封装了诸如重定向日志输出以及从终端和进程组正确分离的任务。它还为受控关机提供了便利选项。

init 或 initdb 模式创建新的 PostgreSQL 数据库群集，即单个服务器实例将管理的数据库集合。此模式调用 initdb 命令。有关详细信息，请参见 initdb 。

start 模式启动新服务器。服务器在后台启动，其标准输入附加到 /dev/null （或在 Windows 上附加到 nul ）。在类 Unix 系统上的常规情况下，服务器的标准输出和标准错误发送到 pg_ctl 的标准输出（不是标准错误）。然后应将 pg_ctl 的标准输出重定向到文件，或通过管道传输到其他进程（如 rotatelogs 等日志循环程序）；否则 postgres 会在其输出中写入对控制终端（从后台进行）并且不会离开 shell 的进程组。在 Windows 上，服务器的标准输出和标准错误按默认设置发送到终端。可以通过使用 -l 将服务器输出附加到日志文件，来更改这些默认行为。建议使用 -l 或输出重定向。

stop 模式关闭在指定数据目录中运行的服务器。可以使用 -m 选项，选择三种不同的关闭方法。“智能”模式禁止新连接，然后等待所有现有客户端断开连接。如果服务器处于热备用状态，一旦所有客户端断开连接，将终止恢复和流式复制。“快速”模式（默认设置）不等待客户端断开连接。所有活动事务将回滚，客户端将被强制断开连接，然后关闭服务器。“立即”模式将立即中止所有服务器进程，而不会进行清理关闭。在下次服务器启动期间，此选择会产生一个故障恢复周期。

restart 模式有效地执行一个停止，然后执行一个启动。这允许更改 postgres 命令行选项，或更改在不重新启动服务器的情况下无法更改的配置文件选项。如果在服务器启动期间在命令行上使用了相对路径，除非以在服务器启动期间相同的当前目录中执行 pg_ctl，否则 restart 可能会失败。

reload 模式只是向 postgres 服务器进程发送 SIGHUP 信号，使其重新读取其配置文件（ postgresql.conf 、 pg_hba.conf 等）。这允许更改不需要完全重启服务器才能生效的配置文件选项。

status 模式检查指定的 data 目录中是否运行着服务器。如果是，则显示服务器的 PID 和用于对其进行调用的命令行选项。如果服务器未运行，pg_ctl 会返回以 3 为退出状态。如果没有指定可访问的 data 目录，pg_ctl 会返回以 4 为退出状态。

promote 模式命令运行在指定 data 目录中的备用服务器结束备用模式并开始读写操作。

logrotate 模式轮换服务器日志文件。有关如何将此模式与外部日志轮换工具一起使用的详细信息，请参阅 Section 25.3 。

kill 模式向指定进程发送一个信号。这主要在没有内置 kill 命令的 Microsoft Windows 上很有价值。使用 —​help 查看支持的信号名称列表。

register 模式在 Microsoft Windows 上将 PostgreSQL 服务器注册为系统服务。 -S 选项允许选择服务的启动类型，包括"自动"（系统启动时自动启动服务）或"按需"（按需启动服务）。

unregister 模式取消在 Microsoft Windows 上注册的系统服务。这会撤消 register 命令的影响。

Options

  • -c_—​core-files_

    • 尝试在可能的情况下允许服务器崩溃以生成核心文件，方法是解除对核心文件设置的任何软资源限制。这是通过允许从失败的服务器进程获取堆栈跟踪，从而帮助调试或诊断问题。

  • -D _datadir—​pgdata=_datadir

    • 指定数据库配置文件的文件系统位置。如果未包含此选项，则会使用环境变量 PGDATA 。

  • -l _filename—​log=_filename

    • 将服务器日志输出追加到 filename 。如果该文件不存在，则会创建。umask 被设为 077，因此默认情况下其他用户无权访问日志文件。

  • -m _mode—​mode=_mode

    • 指定关闭模式。 mode 可以是 smart ， fast 或 immediate ，也可以是这三个中的一个的第一个字母。如果未包含此选项，则以 fast 为默认值。

  • -o _options—​options=_options

    • 指定要直接传递给 postgres 命令的选项。 -o 可以指定多次，所有给定的选项都会被传递。

    • 通常应该用单引号或双引号将 options 括起来，以确保它们作为一组被传递。

  • -o _initdb-options—​options=_initdb-options

    • 指定要直接传递给 initdb 命令的选项。 -o 可以指定多次，所有给定的选项都会被传递。

    • 通常应该用单引号或双引号将 initdb-options 括起来，以确保它们作为一组被传递。

  • -p _path_

    • 指定 postgres 可执行文件的位置。默认情况下， postgres 可执行文件取自与 pg_ctl 相同的目录，或者，如果该目录不存在，则取自固定安装目录。只有在您进行非正常操作并收到找不到 postgres 可执行文件的错误时，才需要使用此选项。

    • 在 init 模式中，此选项同样指定 initdb 可执行文件的位置。

  • -s_—​silent_

    • 仅打印错误，不打印信息消息。

  • -t _seconds—​timeout=_seconds

    • 指定等待操作完成时要等待的最大秒数（请参阅选项 -w ）。默认为 PGCTLTIMEOUT 环境变量的值，如果没有设置，则默认为 60 秒。

  • -V_—​version_

    • 打印 pg_ctl 版本并退出。

  • -w_—​wait_

    • 等待操作完成。这适用于模式 start 、 stop 、 restart 、 promote 和 register ，并且是这些模式的默认设置。

    • 在等待时， pg_ctl 会反复检查服务器的 PID 文件，在检查期间有一小段时间的休眠。当 PID 文件表明服务器已准备好接受连接时，则认为启动已完成。当服务器移除 PID 文件时，则认为关机已完成。 pg_ctl 根据启动或关机是否成功返回一个退出代码。

    • 如果操作未在超时内完成（请参阅选项 -t ），则 pg_ctl 以非零退出状态退出。但请注意，操作可能在后台继续进行并最终成功。

  • -W_—​no-wait_

    • 不等待操作完成。这与选项 -w 相反。

    • 如果禁用等待，则会触发请求的操作，但不会收到有关其成功与否的任何反馈。在那种情况下，服务器日志文件或外部监视系统必须用于检查操作的进度和成功性。

    • 在 PostgreSQL 的早期版本中，这是默认值， stop 模式除外。

  • -?_—​help_

    • 显示有关 pg_ctl 命令行参数的帮助并退出。

如果指定了有效但不适用于所选操作模式的选项，pg_ctl 将忽略该选项。

Options for Windows

  • -e _source_

    • 作为 Windows 服务运行时，pg_ctl 用来记录到事件日志中的事件源名称。默认值为 PostgreSQL 。请注意，这仅控制从 pg_ctl 本身发送的消息；启动后，服务器会使用其 event_source 参数指定的事件源。如果服务器在启动的非常早期阶段失败，在该参数设置之前，它还可能会使用默认事件源名称 PostgreSQL 记录。

  • -N _servicename_

    • 要注册的系统服务名称。此名称将用作服务名称和显示名称。默认值为 PostgreSQL 。

  • -P _password_

    • 以其身份运行服务的用户的密码。

  • -S _start-type_

    • 系统服务的启动类型。 start-type 可以是 auto 或 demand ，也可以是这两个中的一个的首个字母。如果省略此选项， auto 为默认值。

  • -U _username_

    • 以其身份运行服务的用户的用户名。对于域用户，请使用格式 DOMAIN\username 。

Environment

  • PGCTLTIMEOUT

    • 等待启动或关机完成时的默认秒数限制。如果未设置，默认值为 60 秒。

  • PGDATA

    • Default data directory location.

大多数 pg_ctl 模式需要知道数据目录位置；因此，除非设置了 PGDATA ，否则 -D 选项是必填的。

pg_ctl 与大多数其他 PostgreSQL 实用程序一样，也使用 libpq 支持的环境变量（请参阅 Section 34.15 ）。

有关影响服务器的其他变量，请参阅 postgres 。

Files

  • postmaster.pid

    • pg_ctl 会检查数据目录中的此文件，以确定服务器当前是否正在运行。

  • postmaster.opts

    • 如果此文件存在于数据目录中，pg_ctl（在 restart 模式下）会将文件的内容作为选项传给 postgres，除非被 -o 选项覆盖。此文件的内容也会在 status 模式下显示。

Examples

Starting the Server

若要启动服务器，请等到服务器可接受连接：

$ pg_ctl start

若要使用端口 5433 启动服务器，且不使用 fsync ，请使用：

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

Stopping the Server

若要停止服务器，请使用：

$ pg_ctl stop

-m 选项允许对 how 服务器停止进行控制：

$ pg_ctl stop -m smart

Restarting the Server

重启服务器几乎等同于停止服务器并重新启动它，只是默认情况下， pg_ctl 会保存之前正在运行实例传递的命令行选项并重复使用它们。若要使用与之前相同的选项重启服务器，请使用：

$ pg_ctl restart

但是，如果指定了 -o ，则会替换任何先前的选项。若要使用端口 5433 重启，并在重启后禁用 fsync ：

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

Showing the Server Status

这是 pg_ctl 中一个示例状态输出：

$ pg_ctl status

pg_ctl: server is running (PID: 13718)
/usr/local/pgsql/bin/postgres "-D" "/usr/local/pgsql/data" "-p" "5433" "-B" "128"

第二行是要在重启模式下调用的命令。

See Also

initdb ， postgres