pg_ctl — 启动、停止、重启 PostgreSQL

pg_ctl

名称

pg_ctl -- 启动、停止、重启 PostgreSQL

语法

pg_ctl start [-w] [-s] [-D datadir] [-l filename] [-o options] [-p path]
pg_ctl stop [-W] [-s] [-D datadir] [-m s[mart] | f[ast] | i[mmediate] ]
pg_ctl restart [-w] [-s] [-D datadir] [-m s[mart] | f[ast] | i[mmediate] ] [-o options]
pg_ctl reload [-s] [-D datadir]
pg_ctl status [-D datadir]
pg_ctl kill [signal_name] [process_id]
pg_ctl register [-N servicename] [-U username] [-P password] [-D datadir] [-w] [-o options]
pg_ctl unregister [-N servicename]

描述

pg_ctl 用于启动、停止、重启 PostgreSQL 后端服务器(postgres)，或者显示一个运行着的服务器的状态。尽管可以手动启动服务器，但是 pg_ctl 封装了重新定向日志输出，与终端和进程组合理分离，以及另外提供了一个选项用于有控制的关闭。

在 start 模式里会启动一个新的服务器。服务器是在后台启动的，标准输入被附着到了 /dev/null 上。如果使用了 -l ，那么标准输出和标准错误将被定向到一个日志文件，要么就是重定向到 pg_ctl 的标准输出(而不是标准错误)。如果没有选定日志文件，pg_ctl 的标准输出应该重定向到一个文件或者用管道输出到类似 rotatelogs这样的日志滚动程序，否则，postgres 将把它的输出写到控制终端(在后台)并且将不会脱离
shell 的进程组。

在 stop 模式下，那个正在特定数据目录运行的服务器将被关闭。你可以用 -m 选项选择三种不同的关闭模式："Smart"模式等待所有客户端中断连接，这是缺省。"Fast"模式并不等待客户端中断连接，所有活跃事务都被回滚并且客户端都被强制断开。"Immediate"模式将在没有干净关闭的情况下强行退出。这么做将导致在重新启动的时候的恢复。

restart 实际上是先执行一个停止，然后紧跟一个启动。它允许变换 postgres 的命令行选项。

reload 模式简单地给 postgres 发送一个 SIGHUP 信号，导致它重新读取配置文件(postgresql.conf,pg_hba.conf 等)，这样就允许修改配置文件选项而不用重启系统即可生效。

status 模式监查一个服务器是否在指定的数据目录运行，如果是，那么显示其 PID 和调用它的命令行选项。

kill 模式允许你给一个指定的进程发送信号。这个功能对 Microsoft Windows 特别有用，因为它没有 kill 命令。使用 --help 查看支持的信号名字列表。

register 模式允许你在 Microsoft Windows 上注册一个系统服务。

unregister 模式允许你在 Microsoft Windows 上删除先前用 register 命令注册的系统服务。

选项

-D datadir

声明该数据库的文件系统位置。如果忽略则使用 PGDATA 环境变量。

-l filename

把服务器日志输出附加在 filename 文件上。如果该文件不存在则创建它。umask 设置为 077 ，因此缺省时是不允许从其它用户向日志文件访问的。

-m mode

声明关闭模式。mode 可以是 smart, fast, immediate 之一，或者是这三个的首字母之一。

-o options

声明要直接传递给 postgres 的选项。

参数通常都用单或者双引号包围以保证它们作为一个整体传递。

-p path

声明 postgres 可执行文件的位置。缺省位于 pg_ctl 自身所在目录，如果没找到则使用硬编码的安装目录。除非你想干点什么特别的事情，并且想得到类似没有找到 postgres 这样的错误，否则必须使用这个选项。

-s

只打印错误，而不打印提示性信息。

-w

等待启动或者关闭的完成(60 秒超时)，这个参数是关闭时的缺省值。成功的关闭是以删除 PID 文件为标志的。对于启动而言，一次成功的 psql -l 就标志着成功。pg_ctl 将企图使用对 psql 合适的端口，如果存在 PGPORT环境变量，那么将用它。否则，它将查找在 postgresql.conf 文件里是否设置了一个端口。如果都没有，它将使用
PostgreSQL 编译时的缺省端口(缺省 5432)。在等待的时候，pg_ctl 将根据启动或者关闭的成功状况返回一个准确的退出代码。

-W

不等待启动或者停止的完成。这是启动和重启的缺省。

Windows 选项

-N servicename

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

-P password

用户启动服务的口令

-U username

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

环境变量

PGDATA

缺省数据目录位置

PGPORT

psql 的缺省端口(由 -w 选项使用)。

其它的环境变量请参阅 postgres

文件

postmaster.pid

这个文件存在于数据目录中是为了帮助 pg_ctl 判断服务器当前是否在运行。

postmaster.opts.default

如果这个文件存在于数据目录，pg_ctl (在 start 模式下)将把文件地内容当作传递给 postgres 命令的选项传递过去，除非被 -o 选项覆盖。

postmaster.opts

如果这个文件存在于数据目录，pg_ctl (在 start 模式下)将把文件地内容当作传递给 postgres 命令的选项传递过去，除非被 -o 选项覆盖。这个文件的内容也会在 status 模式里显示出来。

postgresql.conf

这个文件在数据目录中，会分析它以查找和 psql 一起用的合适的端口(在 start 模式里给出 -w 的时候)。

注意

等待完全启动还不是一个定义得很完整的操作，如果访问控制设置为本地客户端在没有手工交互的情况下不能访问的话还可能会失效(比如口令认证)。

例子

启动服务器

启动服务器：

启动服务器的一个例子，等到服务器启动了才退出：

服务器使用 5433 端口，而且不带 fsync 运行，使用：

停止服务器

使用 -m 选项停止服务器允许用户控制如何关闭后端。

重启服务器

这个命令几乎等于先停止服务器然后再启动它，只不过 pg_ctl 保存并重新使用上一次运行服务器的命令行参数。重启服务器的最简单的方法是：

重启服务器，等待其停止和重启：

使用 5433 端口重启并且重启后关闭 fsync ：

显示服务器状态

下面是来自 pg_ctl 的状态输出的例子：

这就是在 restart 模式中被调用的命令行。

又见

postgres

pg_resetxlog

名称

pg_resetxlog -- 重置一个数据库集群的预写日志以及其它控制内容

语法

pg_resetxlog [-f] [-n] [-ooid ] [-x xid ] [-e xid_epoch ] [-m mxid ] [-O mxoff ]
[-l timelineid, fileid,seg ] datadir

描述

pg_resetxlog 清理预写日志(WAL)并且可以有选择地重置其它一些存储在 pg_control 文件中的控制信息。有时候，如果这些文件崩溃了，就需要这个功能。一定只把它用作最后的方法，就是说只有因为这样的崩溃导致服务器无法启动的时候才使用。

运行这个命令之后，可能就可以启动服务器了，但是，一定要记住数据库可能因为部分提交的事务而含有不完整的数据。你应该马上转储数据，运行 initdb ，然后重新加载。在重新加载之后，检查不完整的部分然后根据需要进行修复。

这个命令只能由安装服务器的用户运行，因为它需要对数据目录的读写权限。出于安全考虑，pg_resetxlog 不使用环境变量 PGDATA ，你必须在命令行上声明数据目录。

如果 pg_resetxlog 抱怨说它无法判断用于 pg_control 的有效数据，那么你可以强制它继续处理，方法是声明-f(强制)开关。在这种情况下，那些丢失了的数据将用模糊的近似数值代替。大多数字段都可以匹配上，但是下一个 OID 、下一个事务 ID 、下一个事务 ID 的 epoch(时间点)、下一个多事务 ID(两阶段提交的东西)、下一个多事务偏移量、WAL
开始地址、数据库区域字段可能需要手工帮助，前面六个可以用下面讨论的开关设置。pg_resetxlog 自己的环境是猜测区域字段的来源；看看 LANG 等东西，它们应该和 initdb 运行的环境相匹配。如果你不能判断所有这些字段的正确数值，那么 -f 仍然可以使用，但是这样恢复过来的数据库正确性更值得怀疑：立即转储和重新加载是必须的。在转储之前不要执行任何修改数据的操作，因为任何这样的动作都可能把事情搞得更糟糕。

-o, -x, -e, -m, -O, -l 开关允许手工设置下一个 OID 、下一个事务 ID 、下一个事务 ID epoch 、下一个多事务 ID 、下一个多事务偏移量、WAL 起始位置的数值。只有在 pg_resetxlog 无法通过读取 pg_control 判断合适的数值的时候才需要它。安全的数值可以用下面的方法判断：

• 对于下一个事务 ID(-x)而言，一个安全的数值是看看数据目录里的 pg_clog 里数值最大的文件名，然后加一，然后再乘上 1048576 。请注意那些文件名是十六进制的。通常也以十六进制的形式声明开关值是最简单的。比如，如果 0011 是 pg_clog 里最大的记录，-x
  0x1200000 就可以了(后面的五个零提供了合适的乘积)。

• 下一个多事务 ID(-m)的安全值可以通过查看数据目录里 pg_multixact/offsets 子目录里面的数字最大的文件名，加一，然后乘以 65536 得到。和上面一样，文件名是十六进制的，因此最简单的方法是给开关声明一个十六进制的开关值，然后在结尾加四个零。

• 下一个多事务偏移量(-O)的安全值可以通过检查数据目录里 pg_multixact/members 子目录下的数字最大的文件名，加一，然后乘以 65536 得到。和上面一样，文件名是十六进制的，因此最简单的方法是给开关声明一个十六进制的开关值，然后在结尾加四个零。

• WAL 的起始位置(-l)应该比目前存在于数据目录 pg_xlog 里面的任何文件号都大。它的文件名也是十六进制的，并且有三部分。第一部分是"时间线 ID"，通常应该保持相同。第三部分不要选择大于 255(0xFF)；应该是在达到 255 的时候给第二部分增一然后重置第三部分为 0 。比如，如果 00000001000000320000004A 是pg_xlog 里最大的条目，那么 -l
  0x1,0x32,0x4B 就可以了；但如果最大的条目是000000010000003A000000FF ，那么选择 -l 0x1,0x3B,0x0 或更多。

• 没有很容易的办法来判断比数据库中最大的 OID 大一号的下一个 OID ，不过很走运的是获取正确的下一个 OID 并非非常关键的事情。

• 除了由 pg_resetxlog 设定的字段外，事务 ID epoch 实际上并未存储在数据库里的任何地方。所以只要是涉及到数据库自身的任何数值都有效。你可能需要调整这个值以确保诸如 Slony-I 之类的备份系统能够正常工作。如果是这样的话，应当从下游已复制的数据库中获取恰当的值。

-n(无操作)开关指示 pg_resetxlog 打印从 pg_control 重新构造的数值然后不修改任何值就退出。这主要是一个调试工具，但是在 pg_resetxlog 真正处理前进行的整洁性检查的时候可能会有用。

注意

在服务器运行的时候一定不要运行这个命令。如果发现在数据文件目录里有锁文件，那么 pg_resetxlog 将拒绝启动。如果服务器崩溃，那么可能会剩下一个锁文件；如果这样，你可以删除该锁文件以便允许 pg_resetxlog运行。但是在你这么做之前，一定要确保没有任何后端服务器进程仍在运行。

postgres

名称

postgres -- PostgreSQL 数据库服务器

语法

postgres [option...]

描述

postgres 是 PostgreSQL 数据库服务器。客户端应用程序为了访问数据库，将通过 TCP Socket 或 Unix domain socket 连接到一个运行中的 postgres 进程。然后该 postgres 实例将启动(fork)一个新的、独立的服务器进程来处理这个连接。

一个 postgres 总是管理来自同一个数据库集群的数据。一个数据库集群是一组在同一个文件系统位置("数据区")存放数据的数据库。一个系统上可以同时运行多个 postgres 进程，只要他们使用不同的数据区和不同的端口号(见下文)。postgres 启动时需要知道数据区的位置，该位置必须通过 -D 选项或 PGDATA 环境变量指定。通常，-D 或 PGDATA 都直接指向由
initdb 创建的集群目录。其他可能的文件布局在节17.2里面有讨论。

缺省时 postgres 在前台启动并将日志信息输出到标准错误。但在实际应用中，postgres 应当作为后台进程启动，而且多数是在系统启动时自动启动。

postgres 还能以单用户模式运行。这种用法的主要用于 initdb 的初始化过程中。有时候它也被用于调试灾难性恢复。不过，单用户模式运行的服务器并不适合于调试，因为没有实际的进程间通讯和锁动作发生。当从 shell 上以单用户模式调用时，用户可以输入查询，然后结果会在屏幕上以一种更适合开发者阅读(不适合普通用户)的格式显示出来。在单用户模式下，将把会话用户 ID 设为 1 并赋予超级用户权限。该用户不必实际存在，因此单用户模式运行的服务器可以用于对某些意外损坏的系统表进行手工恢复。

选项

postgres 接受下列命令行参数。关于这些选项的更详细讨论请参考章17。你也可以通过设置一个配置文件来减少敲击这些选项。有些(安全的)选项还可以从连接过来的客户端设置，以一种应用无关的方法仅对该会话生效。比如，如果设置了 PGOPTIONS 环境变量，那么基于 libpq 的客户端就都把那个字符串传递给服务器，并被服务器解释成 postgres 命令行选项。

通用用途

-A 0|1

打开运行时断言检查，是检测编程错误的调试帮助。只有在编译 PostgreSQL 时打开了它，你才能使用它。如果编译时打开了，缺省是打开。

-B nbuffers

为服务器进程分配和管理的共享内存缓冲区数量。这个参数的缺省值是 initdb 自动选择的；参考节17.4.1获取更多信息。

-c name=value

设置一个命名的运行时参数。PostgreSQL 支持的配置参数在章17里描述。大多数其它命令行选项实际上都是这样的参数赋值的短形式。-c 可以出现多次从而设置多个参数。

-d debug-level

设置调试级别。数值越高，写到服务器日志的调试输出越多。取值范围是 1 到 5 。还可以针对某次单独的会话使用 -d 0 来防止从父 postgres 进程继承日志级别。

-D datadir

声明数据目录或者配置文件的文件系统路径。细节详见节17.2。

-e

把缺省日期风格设置为"European"，也就是说用 DMY 规则解释日期输入，并且在一些日期输出格式里日子在月份前面打印。参阅节8.5获取更多细节。

-F

关闭 fsync 调用以提高性能，但是要冒系统崩溃时数据毁坏的风险。声明这个选项等效关闭了 fsync 参数。在使用之前阅读详细文档！

-h hostname

指定 postgres 侦听来自前端应用 TCP/IP 连接的 IP 主机名或地址。数值也可以是一个用空格分隔的地址列表，或者 * 表示监听所有可用的地址。空值表示不监听任何 IP 地址，而只使用 Unix 域套接字与客户端通信。缺省只监听 localhost 。声明这个选项等效于设置 listen_addresses 配置参数。

-i

这个选项允许远程客户通过 TCP/IP(网际域套接字)与服务器通讯。没有这个选项，服务器将只接受本地连接。这个选项等效于在 postgresql.conf 中或者通过 -h 选项将 listen_addresses 设为 *

这个选项已经废弃了，因为它不能实现 listen_addresses 的所有功能。所以最好直接设置 listen_addresses

-k directory

指定 postgres 侦听来自前端应用连接的 Unix 域套接字的目录。缺省通常是 /tmp ，但是可以在编译的时候修改。

-l

这个选项使用 SSL 进行的安全通讯。要使用这个选项，编译 PostgreSQL 时你必须打开了 SSL 支持。有关使用 SSL 的信息，请参考节16.7。

-N max-connections

设置最多允许同时连接多少个客户端(也就是最多同时运行多少个服务器进程)。缺省值为 32 ，不过该值最大可以设置为系统所能承受的极限。请注意 -B 的值要求至少两倍于 -N 的值。参阅节16.4获取有关大量客户的系统资源需求。声明这个选项等效于声明 max_connections 配置参数。

-o extra-options

在 extra-options 里面指定的命令行选项将被传递给所有由这个 postgres 派生的服务进程。如果选项字符串包含任何空白，那么整个字符串必须用引号界定。

反对使用该选项，所有服务器进程的命令行选项都可以直接在 postgres 命令行上指定，不必这么麻烦。

-p port

指定 postgres 侦听客户端连接的 TCP/IP 端口或本地 Unix domain socket 文件的扩展。缺省的端口号是环境变量 PGPORT 的值。如果 PGPORT 没有设置，那么缺省是 PostgreSQL 编译时指定的值(通常是 5432)。如果你声明了一个非缺省端口，那么所有前端应用都必须用命令行选项或者 PGPORT 声明同一个端口。

-s

在每条命令结束时打印时间信息和其它统计信息。这个开关对测试性能和调节缓冲区数量有好处。

-S work-mem

声明内部排序和散列在求助于临时磁盘文件之前可以使用的内存数量。参阅节17.4.1里描述的配置变量work_mem

--name=value

设置一个命名的运行时参数；其缩写形式是 -c

--describe-config

以制表符分隔的 COPY 格式，导出服务器内部配置变量、描述、缺省值。设计它主要是给管理工具使用。

半内部选项

还有几个其它的选项可以声明，主要用于调试用途。这些东西在这里列出只是给 PostgreSQL 系统开发人员使用的。强烈反对使用这些选项。另外这些选项的任何一项都可能在未来版本中消失而不加说明。

-f { s | i | m | n | h }

禁止某种扫描和连接方法的使用：s 和 i 分别关闭顺序和索引扫描，而 n, m, h 分别关闭嵌套循环，融合(merge)和 Hash 连接。

顺序扫描和嵌套循环都不可能完全被关闭。 -fs 和 -fn 选项仅仅是在存在其它方法时阻碍优化器使用这些方法罢了。

-n

该选项主要用于调试导致服务器进程异常崩溃的问题。对付这种情况的一般策略是通知所有其它服务器进程终止并重新初始化共享内存和信号灯。这是因为一个出错的服务器进程可能在终止之前就已经对共享的东西造成了破坏。该选项指定 postgres 不重新初始化共享数据结构。一个有经验的系统程序员这时就可以使用调试器检查共享内存和信号灯状态。

-O

允许修改系统表的结构。这个参数用于 initdb

-P

读取系统表时忽略系统索引(但在更改数据时仍然更新索引)。这对于从索引已经损坏的系统表中回复是很有帮助的。

-t pa[rser] | pl[anner] | e[xecutor]

打印与每个主要系统模块相关的查询记时统计。它不能和 -s 选项一起使用。

-T

该选项主要用于调试导致服务器进程异常崩溃的问题。对付这种情况的一般策略是通知所有其它服务器进程终止并重新初始化共享内存和信号灯。这是因为一个出错的服务器进程可能在终止之前就已经对共享的东西造成了破坏。该选项指定 postgres 通过发送 SIGSTOP 信号停止其他所有服务器进程，但是并不让它们退出。这样就允许系统程序员手动从所有服务器进程搜集内核转储。

-v protocol

声明这次会话使用的前/后服务器协议的版本数。该选项仅在内部使用。

-W seconds

一旦看见这个选项，进程就睡眠标出的秒数。这样就给开发者一些时间把调试器附着在该服务器进程上。

-y database

表明这是一个由父 postgres 进程启动的子进程，并使用指定的数据库。该选项仅供内部使用。

单用户模式的选项

下面的选项仅在单用户模式下可用。

--single

选中单用户模式。这个必须是命令行中的第一个选项。

database

要访问的数据库名字。如果忽略掉则缺省为用户名。

-E

回显所有命令

-j

禁止使用新行作为语句分隔符

-r filename

将所有服务器输出日志保存到 filename 中。在多用户模式下该选项将被忽略，所有进程都将使用 stderr

环境变量

PGCLIENTENCODING

客户端使用的缺省字符编码。客户端可以独立地覆盖它。这个值也可以在配置文件里设置。

PGDATA

缺省数据目录位置

PGDATESTYLE

运行时参数 DateStyle 的缺省值。现在反对使用该环境变量。

PGPORT

缺省端口(最好在配置文件中设置)

TZ

服务器的时区

诊断

一个提到了 semget 或 shmget 的错误信息可能意味着你需要重新配置你的内核，提供足够的共享内存和信号灯。更多讨论，参阅节16.4。你也可以通过降低 shared_buffers 值以减少 PostgreSQL 的共享内存的消耗，或者降低 max_connections 值减少 PostgreSQL 的信号灯的消耗。

如果碰到一个说另外一个服务器正在运行的错误信息，可以根据不同的系统使用命令

或

如果确信没有冲突的服务器正在运行，那么你可以删除消息里提到的锁文件然后再次运行。

抱怨无法绑定端口的错误信息可能表明该端口已经被其它非 PostgreSQL 进程使用。如果终止 postgres 后又马上用同一个端口运行它，也可能得到这个错误信息；这时，你必须多等几秒，等操作系统关闭了该端口后再试。最后，如果你使用了一个操作系统认为是保留的端口，也可能导致这个错误信息。例如，我的 Unix 版本认为低于 1024 的端口号是"可信任的"，因而只有 Unix 超级用户可以使用它们。

注意

如果有可能，不要使用 SIGKILL 杀死主 postgres 服务器进程。这样会阻止 postgres 在退出前释放它持有的系统资源(例如共享内存和信号灯)。这样可能会影响到将来启动新的 postgres 进程。

可以使用 SIGTERM, SIGINT, SIGQUIT 信号正常结束 postgres 服务器进程。第一个信号将等待所有的客户端退出后才退出。第二个将强制断开所有客户端，而第三个将不停止立刻退出，导致在重启时的恢复运行。SIGHUP会重新加载服务器配置文件。也可以向一个单独的服务器进程发送 SIGHUP 信号，但是这样做没什么意义。

pg_ctl 工具可以用于安全而有效地启停 postgres ，推荐使用。

要推出一个正在运行的查询，可以向正在执行该查询的进程发送 SIGINT 信号。

主 postgres 服务器进程向子进程发送 SIGTERM 信号让它们正常退出；发送 SIGQUIT 信号立即退出且不做清理工作，用户应当尽量避免使用该信号。同时，发送 SIGKILL 信号也是不明智的：主 postgres 进程将把这个信号当作崩溃信号，然后会强制其他兄弟进程作为标准的崩溃回复过程退出。

臭虫

-- 选项在 FreeBSD 或 OpenBSD 上无法运行，应该使用 -c 。这在受影响的系统里是个臭虫；如果这个毛病没有修补好，将来的 PostgreSQL 版本将提供一个绕开的办法。

用法

启动一个单用户模式的服务器：

用 -D 给服务器提供正确的数据库目录的路径，或者确保环境变量 PGDATA 已经正确设置。同时还要声名你想用的特定数据库名字。

通常，独立运行的服务器把换行符当做命令输入完成字符；它还不懂分号的作用，因为那些东西是在 psql 里的。要想把一行分成多行写，你必需在除最后一个换行符以外的每个换行符前面敲一个反斜杠。

但是如果使用了 -j 命令行选项，新行将不被当作命令结束符。此时服务器将从标准输入一直读取到 EOF 标志为止，然后把把所有读到的内容当作一个完整的命令字符串看待，并且反斜杠与换行符也被当作普通字符来看待。

输入 EOF(Control+D)即可退出会话。如果你已经使用了 -j 则必须连续使用两个 EOF 才行。

请注意单用户模式运行的服务器不会提供复杂的行编辑功能(比如，没有命令行历史)。

例子

用缺省值在后台启动 postgres ：

在指定的端口启动 postgres ：

这条命令将在端口 1234 启动 postgres 。你应该这样使用 psql 与之连接：

或者设置环境变量 PGPORT ：

命名的运行时参数可以用下列的风格之一设置：

两种形式都覆盖那些现有的在 postgresql.conf 里面的 work_mem 设置。请注意在参数名里的下划线在命令行上可以写成下划线，也可以写成连字符。除了用于短期的实验以外，更好的习惯是编辑