PostgreSQL 教程

Appearance

pg_ctl ​

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

概要 ​

pg_ctl``init[db][-Ddatadir] [-s] [-oinitdb-options]

pg_ctl``start[-Ddatadir] [-lfilename] [-W] [-tseconds] [-s] [-ooptions] [-ppath] [-c]

pg_ctl``stop[-Ddatadir] [-m``s[mart]|f[ast]|i[mmediate]] [-W] [-tseconds] [-s]

pg_ctl``restart[-Ddatadir] [-m``s[mart]|f[ast]|i[mmediate]] [-W] [-tseconds] [-s] [-ooptions] [-c]

pg_ctl``reload[-Ddatadir] [-s]

pg_ctl``status[-Ddatadir]

pg_ctl``promote[-Ddatadir] [-W] [-tseconds] [-s]

pg_ctl``logrotate[-Ddatadir] [-s]

pg_ctl``killsignal_name**process_id

在 Microsoft Windows 上，还有

pg_ctl``register[-Ddatadir] [-Nservicename] [-Uusername] [-Ppassword] [-S``a[uto]|d[emand]] [-esource] [-W] [-tseconds] [-s] [-ooptions]

pg_ctl``unregister[-Nservicename]

说明 ​

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命令行选项，或更改无法在不重新启动服务器的情况下更改的配置文件选项。如果在服务器启动期间在命令行上使用了相对路径，则restart可能失败，除非pg_ctl在与服务器启动期间相同的当前目录中执行。

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

status模式检查服务器是否在指定的数据目录中运行。如果正在运行，则会显示服务器的PID和用于调用它的命令行选项。如果服务器未运行，pg_ctl将返回退出状态 3。如果未指定可访问的数据目录，pg_ctl将返回退出状态 4。

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

logrotate模式轮换服务器日志文件。有关如何将此模式与外部日志轮换工具配合使用的详细信息，请参阅第 25.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。如果文件不存在，则创建该文件。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 秒数
--timeout=秒数

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

-V
--version

打印 pg_ctl 版本并退出。

-w
--wait

等待操作完成。这受模式 start、stop、restart、promote 和 register 支持，并且是这些模式的默认设置。

在等待时，pg_ctl 会重复检查服务器的 文件，在检查之间短暂休眠。当 文件指示服务器已准备好接受连接时，启动被视为已完成。当服务器删除 文件时，关闭被视为已完成。pg_ctl 会根据启动或关闭的成功返回退出代码。

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

-W
--no-wait

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

如果禁用了等待，则会触发请求的操作，但不会反馈其成功信息。在这种情况下，必须使用服务器日志文件或外部监控系统来检查操作的进度和成功情况。

在 PostgreSQL 的早期版本中，这是默认设置，但 stop 模式除外。

-?
--help

显示有关 pg_ctl 命令行参数的帮助，然后退出。

如果指定了有效但与所选操作模式无关的选项，pg_ctl会忽略它。

Windows 选项 ​

-e 源

当以 Windows 服务运行时，pg_ctl 用于记录到事件日志的事件源名称。默认值为 PostgreSQL。请注意，这仅控制从 pg_ctl 本身发送的消息；一旦启动，服务器将使用其 event_source 参数指定的事件源。如果服务器在启动的早期阶段（在设置该参数之前）发生故障，则它也可能会使用默认事件源名称 PostgreSQL 进行日志记录。

-N 服务名称

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

-P 密码

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

-S 启动类型

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

-U 用户名

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

环境 ​

PGCTLTIMEOUT

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

PGDATA

默认数据目录位置。

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

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

有关影响服务器的其他变量，请参见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