pg_ctl

当前查看 PostgreSQL 18。

中文定义与说明

命令行工具 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 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 ]。

同版本中文手册节选

描述

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 选项选择三种不同的关闭方法。“Smart”模式不允许新连接，然后等待所有现有客户端断开。如果服务器处于热备状态，那么在所有客户端断开后，恢复和流复制都会终止。“Fast”模式（默认值）不等待客户端断开。所有活动事务都会回滚，客户端会被强制断开，然后服务器关闭。“Immediate”模式会立即中止所有服务器进程，而不执行干净关闭。这样会导致服务器在下次启动时进入一次崩溃恢复周期。

restart 模式实际上就是先执行停止再执行启动。这使得可以修改 postgres 的命令行选项，或者修改那些不重启服务器就无法更改的配置文件选项。如果服务器启动时在命令行中使用了相对路径，那么除非在与服务器上次启动时相同的当前目录中执行 pg_ctl，否则 restart 可能失败。

reload 模式只是向 postgres 服务器进程发送一个 SIGHUP 信号，使其重新读取配置文件（postgresql.conf、pg_hba.conf 等）。这样就可以修改那些无需完全重启服务器即可生效的配置文件选项。

status 模式会检查指定数据目录中是否有服务器正在运行。若有，则显示服务器的 PID 以及调用它时使用的命令行选项。若服务器未运行，pg_ctl 返回退出状态 3。若未指定一个可访问的数据目录，pg_ctl 返回退出状态 4。

promote 模式会指示在指定数据目录中运行的备库结束备库模式，并开始进行读写操作。

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

kill 模式向指定进程发送信号。这在没有内置 kill 命令的 Microsoft Windows 上尤其有用。使用 --help 可查看受支持的信号名称列表。

register 模式会将 PostgreSQL 服务器注册为 Microsoft Windows 上的系统服务。-S 选项允许选择服务启动类型，可以是“auto”（系统启动时自动启动服务）或“demand”（按需启动服务）。

unregister 模式会在 Microsoft Windows 上注销一个系统服务。这会撤销 register 命令的效果。

选项

-c --core-files

在支持的平台上，通过解除对核心转储文件施加的任何软资源限制，尝试允许服务器在崩溃时生成核心转储文件。这样就可以从失败的服务器进程中获得栈跟踪，从而有助于调试或诊断问题。

-D datadir --pgdata=datadir

指定数据库配置文件所在的文件系统位置。若省略此选项，则使用环境变量 PGDATA。

-l filename --log=filename

将服务器日志输出追加到 filename。如果该文件不存在，就会创建它。默认情况下，只有集簇拥有者可以访问该日志文件。如果在集簇中启用了组访问权限，与集簇拥有者同组的用户也可以读取它。

-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 会忽略它。

用于 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 格式。

查看完整中文手册与上下文。

说明

描述 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 选项选择三种不同的关闭方法。 “ Smart ” 模式不允许新连接，然后等待所有现有客户端断开。如果服务器处于热备状态，那么在所有客户端断开后，恢复和流复制都会终止。 “ Fast ” 模式（默认值）不等待客户端断开。所有活动事务都会回滚，客户端会被强制断开，然后服务器关闭。 “ Immediate ” 模式会立即中止所有服务器进程，而不执行干净关闭。这样会导致服务器在下次启动时进入一次崩溃恢复周期。 restart 模式实际上就是先执行停止再执行启动。这使得可以修改 postgres 的命令行选项，或者修改那些不重启服务器就无法更改的配置文件选项。如果服务器启动时在命令行中

手册中的可执行程序: pg_ctl
程序版本: 18.6
参考清单: 服务端程序
选项定义组: 18

用法

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

手册中的选项

选项与参数	说明
-c --core-files	在支持的平台上，通过解除对核心转储文件施加的任何软资源限制，尝试允许服务器在崩溃时生成核心转储文件。这样就可以从失败的服务器进程中获得栈跟踪，从而有助于调试或诊断问题。
-D datadir --pgdata= datadir	指定数据库配置文件所在的文件系统位置。若省略此选项，则使用环境变量 PGDATA 。
-l filename --log= filename	将服务器日志输出追加到 filename 。如果该文件不存在，就会创建它。默认情况下，只有集簇拥有者可以访问该日志文件。如果在集簇中启用了组访问权限，与集簇拥有者同组的用户也可以读取它。
-m mode --mode= mode	指定关闭模式。 mode 可以是 smart 、 fast 或 immediate ，也可以是这三者之一的首字母。若省略此选项，则默认值为 fast 。
-o options --options= options	指定要直接传递给 postgres 命令的选项。 -o 可以指定多次，给出的所有选项都会被传递过去。
-o initdb-options --options= initdb-options	指定要直接传递给 initdb 命令的选项。 -o 可以指定多次，给出的所有选项都会被传递过去。
-p path	指定 postgres 可执行程序的位置。默认情况下， postgres 可执行程序取自与 pg_ctl 相同的目录；如果那里没有，则取自硬编码的安装目录。除非采用了某些非常规方式，并收到找不到 postgres 可执行程序的错误，否则通常不需要使用此选项。
-s --silent	只打印错误，不打印信息性消息。
-t seconds --timeout= seconds	指定等待某个操作完成时最多等待多少秒（见选项 -w ）。默认值为环境变量 PGCTLTIMEOUT 的值；如果未设置该环境变量，则默认为 60 秒。
-V --version	打印 pg_ctl 的版本并退出。
-w --wait	等待操作完成。 start 、 stop 、 restart 、 promote 和 register 模式支持此选项，而且对这些模式来说它是默认行为。
-W --no-wait	不等待操作完成。这与选项 -w 相反。
-? --help	显示有关 pg_ctl 命令行参数的帮助并退出。
-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 格式。

环境变量

变量	含义
PGCTLTIMEOUT	等待启动或关闭完成时，默认的等待秒数上限。如果未设置，默认值为 60 秒。
PGDATA	默认数据目录位置。

文档与源码

来源构建

版本: 18.6
构建: https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2
来源指纹: ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8

版本比较

PostgreSQL 17 → 18: 无变化。

比较已记录的接口与属性，排除来源指纹和构建元数据。某个样本中没有记录，不能据此判断实际引入或移除的版本。

快速链接