pg_ctl

Name

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

Synopsis

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包装了重定向日志输出以及正确地从终端和进程组脱离等任务。它也提供了方便的选项用来控制关闭。

initinitdb模式会创建一个新的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.confpg_hba.conf等)。这允许改变配置文件选项而无需一次完整的重启来让改变生效。

status模式检查一个服务器是否运行在指定的数据目录中。如果有一个服务器正在运行,PID和用来调用它的命令行选项将被显示。如果服务器没有在运行,进程将返回退出状态 3。

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可以是smartfastimmediate,或者这三者之一的第一个字母。如果这被忽略,将使用smart

-o options

指定被直接传递给postgres命令的选项。

这些选项应该通常被单引号或双引号包围来确保它们被作为一个组传递。

-o initdb-options

指定要直接传递给initdb命令的选项。

这些选项应该通常被单引号或双引号包围来确保它们被作为一个组传递。

-p path

指定postgres可执行程序的位置。默认情况下,postgres可执行程序可以从pg_ctl相同的目录得到,或者如果没有在那里找到,则在硬写的安装目录中获得。除非你正在做一些不同寻常的事并且得到错误说没有找到postgres可执行程序,这个选项不是必需的。

init模式中,这个选项类似于指定了initdb可执行程序的位置。

-s
--silent

只打印错误,不打印信息性的消息。

-t
--timeout

等待启动或关闭完成的最大秒数。默认为 60 秒。

-V
--version

打印pg_ctl版本并退出。

-w

等待启动或关闭完成。等待是关闭的默认选项,但不是启动的默认选项。在等待启动时,pg_ctl会重复尝试连接到服务器。在等待关闭时,pg_ctl会等待服务器移除它的PID文件。这个选项允许在启动时一个SSL口令的进入。pg_ctl基于启动或关闭的成功返回一个退出码。

-W

不等待启动或关闭完成。这是启动和重启模式的默认值。

-?
--help

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

用于 Windows 的选项

-N servicename

要注册的系统服务的名称。这个名称将被用于服务名和显示名。

-P password

启动该服务的用户的口令。

-S start-type

要注册的系统服务的启动类型。启动类型可以是autodemand或者两者之一的第一个字母。如果这被忽略,会使用auto

-U username

启动该服务的用户的用户名。对于域用户,使用格式DOMAIN\username

环境

PGDATA

默认的数据目录位置。

和大部分其他PostgreSQL工具相似,pg_ctl也使用libpq(见Section 31.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

停止服务器

要停止服务器,使用:

$ pg_ctl stop

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

$ pg_ctl stop -m fast

重启服务器

重启服务器几乎等价于停止服务器并且再次启动它,不过pg_ctl会保存并重用被传递给之前的运行实例的命令行选项。要以最简单的形式重启服务器,使用:

$ pg_ctl restart

要重启服务器并等待它关闭和重启:

$ pg_ctl -w restart

要使用端口 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