↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译，由 Pigsty 团队维护。

百科 / 命令行工具 / 服务端程序

pg_ctl

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

当前查看 PostgreSQL 18.6。

说明

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

手册中的可执行程序
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默认数据目录位置。

手册定义

pg_ctl

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

大纲

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]

说明

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

环境

PGCTLTIMEOUT

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

PGDATA

默认数据目录位置。

大多数 pg_ctl 模式都需要知道数据目录的位置，因此除非已设置 PGDATA，否则必须提供 -D 选项。

其他会影响服务器的变量，见postgres。

文件

postmaster.pid

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

postmaster.opts

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

示例

启动服务器

要启动服务器并等待其开始接受连接：

$ pg_ctl start

要使用端口 5433 启动服务器，并在未启用fsync的情况下运行，可使用：

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

停止服务器

要停止服务器，可使用：

$ pg_ctl stop

-m选项允许控制服务器如何关闭：

$ pg_ctl stop -m smart

重启服务器

重启服务器几乎等同于先停止服务器再重新启动，只不过默认情况下，pg_ctl会保存并重用传给前一个运行实例的命令行选项。要使用与之前相同的选项重启服务器，可使用：

$ pg_ctl restart

但是，如果指定了-o，就会替换先前的所有选项。要使用端口 5433 重启服务器，并在重启时禁用fsync，可使用：

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

显示服务器状态

下面是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"

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

另见

initdb, postgres

文档与源码

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

版本比较

PostgreSQL 13 → 14: 属性变化。

以下差异保留原始字段名与英文源描述。

--- PostgreSQL 13
+++ PostgreSQL 14
@@ -27,7 +27,7 @@
       "signature": "-D datadir --pgdata= datadir"
     },
     {
-      "description": "Append the server log output to filename . If the file does not exist, it is created. The umask is set to 077, so access to the log file is disallowed to other users by default.",
+      "description": "Append the server log output to filename . If the file does not exist, it is created. By default, only the cluster owner can access the log file. If group access is enabled in the cluster, users in the same group as the cluster owner can also read it.",
       "names": [
         "-l filename",
         "--log= filename"

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

相关条目

导出 JSON · 返回命令行工具 · 收录范围为 PostgreSQL 10 至 20；最早采样版本不一定是实际引入版本。