pg_ctl
From PostgreSQL
pg_ctl
大纲
pg_ctl init[db] [-s] [-D datadir] [-o initdb-options]
pg_ctl start [-w] [-t seconds] [-s] [-D datadir] [-l filename] [-o options] [-p path] [-c]
pg_ctl stop [-W] [-t seconds] [-s] [-D datadir] [-m s[mart] | f[ast] | i[mmediate] ]
pg_ctl restart [-w] [-t seconds] [-s] [-D datadir] [-c] [-m s[mart] | f[ast] | i[mmediate] ] [-o options]
pg_ctl reload [-s] [-D datadir]
pg_ctl status [-D datadir]
pg_ctl promote [-s] [-D datadir]
pg_ctl kill signal_name process_id
pg_ctl register [-N servicename] [-U username] [-P password] [-D datadir] [-S a[uto] | d[emand] ] [-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的命令行选项。如果指定的相对路径是在服务器启动期间在命令行指定的，restart可能会失败。
reload模式简单地向postgres进程发送一个SIGHUP信号，导致它重新读取它的配置文件（postgresql.conf、pg_hba.conf等）。这允许改变配置文件选项而无需一次完整的重启来让改变生效。
status模式检查一个服务器是否运行在指定的数据目录中。如果有一个服务器正在运行，PID和用来调用它的命令行选项将被显示。如果服务器没有在运行，进程将返回退出状态 3。如果没有指定一个可以访问的数据目录，该进程将返回退出状态 4。
在promote模式中，运行在指定数据目录中的后备服务器被命令退出恢复并且开始读写操作。
kill模式允许你向一个指定进程发送一个消息。这对没有kill命令的Microsoft Windows特别有价值。使用--help来查看受支持的信号名称列表。
register模式允许你在Microsoft Windows上注册一个系统服务。-S选项允许选择服务启动类型，可以是"auto"（随系统自动启动）或"demand"（按需启动）。
unregister模式允许你在Microsoft Windows上移除一个系统服务的注册。这会撤销register命令的效果。
选项
- -c --core-file
-
在可行的平台上尝试允许服务器崩溃产生核心文件，方法是提升在核心文件上的任何软性资源限制。这通过允许从一个失败的服务器进程中获得一个栈跟踪而有助于调试或诊断问题。
-
-D
datadir
--pgdata datadir -
指定数据库配置文件的文件系统位置。如果这被忽略，将使用环境变量PGDATA。
-
-l
filename
--log filename -
追加服务器日志输出到filename。如果该文件不存在，它会被创建。umask被设置成 077，这样默认情况下不允许其他用户访问该日志文件。
-
-m
mode
--mode mode -
指定关闭模式。mode可以是smart、fast或immediate，或者这三者之一的第一个字母。如果这被忽略，将使用fast。
- -o options
-
指定被直接传递给postgres命令的选项。 多个选项调用会被追加在一起。
这些选项应该通常被单引号或双引号包围来确保它们被作为一个组传递。
- -o initdb-options
-
指定要直接传递给initdb命令的选项。
这些选项应该通常被单引号或双引号包围来确保它们被作为一个组传递。
- -p path
-
指定postgres可执行程序的位置。默认情况下，postgres可执行程序可以从pg_ctl相同的目录得到，或者如果没有在那里找到，则在硬写的安装目录中获得。除非你正在做一些不同寻常的事并且得到错误说没有找到postgres可执行程序，这个选项不是必需的。
在init模式中，这个选项类似于指定了initdb可执行程序的位置。
-
-s
--silent -
只打印错误，不打印信息性的消息。
-
-t
--timeout -
等待启动或关闭完成的最大秒数。默认值是环境变量 PGCTLTIMEOUT的值，如果该环境变量未设置，则默认值为 60。
-
-V
--version -
打印pg_ctl版本并退出。
- -w
-
等待启动或关闭完成。等待是关闭的默认选项，但不是启动的默认选项。在等待启动时，pg_ctl会重复尝试连接到服务器。在等待关闭时，pg_ctl会等待服务器移除它的PID文件。这个选项允许在启动时一个SSL口令的进入。pg_ctl基于启动或关闭的成功返回一个退出码。
- -W
-
不等待启动或关闭完成。这是启动和重启模式的默认值。
-
-?
--help -
显示有关pg_ctl命令行参数的帮助并退出。
用于 Windows 的选项
- -e source
-
作为一个 Windows 服务运行时，pg_ctl用来 在事件日志中记录日志的事件源的名称。默认是PostgreSQL。 注意这只控制来自pg_ctl本身的日志，一旦开始， 服务器将使用event_source中指定的事件源。如果在 早期的启动阶段服务器失败，它可能也会使用默认的事件源 PostgreSQL来记录。
- -N servicename
-
要注册的系统服务的名称。这个名称将被用于服务名和显示名。
- -P password
-
启动该服务的用户的口令。
- -S start-type
-
要注册的系统服务的启动类型。启动类型可以是auto、demand或者两者之一的第一个字母。如果这被忽略，会使用auto。
- -U username
-
启动该服务的用户的用户名。对于域用户，使用格式DOMAIN\username。
环境
- PGCTLTIMEOUT
-
等待启动或者关闭完成时要等待的默认秒数限制。如果没有设置， 默认值是 60 秒。
- PGDATA
-
默认的数据目录位置。
和大部分其他PostgreSQL工具相似，pg_ctl也使用libpq（见第 32.14 节）支持的环境变量。更多服务器变量请见postgres。
文件
- postmaster.pid
-
这个文件在数据目录中的存在被用来帮助pg_ctl决定服务器是否正在运行着。
- postmaster.opts
-
如果这个文件存在于数据目录中，pg_ctl（处于restart模式中）将把该文件的内容作为选项传递给postgres，除非通过-o选项进行了覆盖。这个文件的内容也会被显示在status模式中。
例子
启动服务器
要启动服务器：
$ pg_ctl start
要启动服务器并且等到服务器接受连接：
$ pg_ctl -w start
要使用端口 5433 启动服务器并且运行时不使用fsync：
$ pg_ctl -o "-F -p 5433" start