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

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可能会失败, 除非在与服务器启动时相同的当前目录中执行pg_ctl

reload模式简单地向postgres服务器进程发送一个 SIGHUP信号,导致它重新读取它的配置文件 (postgresql.confpg_hba.conf等)。 这允许改变配置文件选项而无需完全重新启动服务器来让改变生效。

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

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

kill模式向一个指定进程发送一个消息。这主要在没有内建 kill命令的Microsoft Windows上有价值。使用--help来查看受支持的信号名称列表。

register模式在Microsoft Windows上注册 PostgreSQL服务为系统服务。-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可以是smartfastimmediate,或者这三者之一的第一个字母。 如果忽略该选项,默认是fast

-o options
--options=options

指定被直接传递给postgres命令的选项。 -o可以多次指定,所有给定的选项都被传递。

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

-o initdb-options
--options=initdb-options

指定要直接传递给initdb命令的选项。 -o可以多次指定,所有给定的选项都被传递。

这些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

等待操作完成。 支持模式startstoprestartpromoteregister,并且是这些模式的默认。

在等待启动时,pg_ctl会重复尝试连接到服务器。 在等待关闭时,pg_ctl会等待服务器移除它的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可以是autodemand或者两者之一的第一个字母。如果忽略该选项, 默认是auto

-U username

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

环境

PGCTLTIMEOUT

等待启动或者关闭完成时要等待的默认秒数限制。如果没有设置, 默认值是 60 秒。

PGDATA

默认的数据目录位置。

大多数pg_ctl模式需要知道数据目录的位置;因此, 除非设置了PGDATA,否则-D选项是必需的。

和大部分其他PostgreSQL工具相似,pg_ctl也使用libpq(见第 33.14 节)支持的环境变量。

对于影响服务器的其他变量,请参见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