PG中的pg_ctl命令

官网：http://postgres.cn/docs/13/app-pg-ctl.html

pg_ctl — 初始化、启动、停止或控制一个PostgreSQL服务器。pg_ctl是PG中初始化数据目录，启动、停止、重启、重加载数据库服务，或者查看数据库服务状态的工具，相比SERVICE或SYSTECTL的管理方式，PG_CTL提供了丰富的控制项，执行PG_CTL命令需要操作系统用户使用SU命令切换到POSTGRES用户。

描述

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可能会失败，除非pg_ctl被运行在与上次启动服务器相同的目录中。

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

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

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

logrotate模式轮换服务器日志文件。有关如何将此模式与外部日志轮换工具一起使用的详细信息，参见第 24.3 节。

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

register模式把PostgreSQL服务器注册为Microsoft Windows上的一个系统服务。-S选项允许选择服务启动类型，可以是“auto”（随系统自动启动）或“demand”（按需启动）。

unregister模式在Microsoft Windows上移除一个系统服务的注册。这会撤销register命令的效果。

命令

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 logrotate [-D datadir] [-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]

选项

• -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可以被指定多次，所有给定的选项都会被传过去。这些选项应该通常被单引号或双引号包围来确保它们被作为一个组传递。

• -o *initdb-options* --options=*initdb-options*

  指定要直接传递给initdb命令的选项。-o可以被指定多次，所有给定的选项都会被传过去。这些选项应该通常被单引号或双引号包围来确保它们被作为一个组传递。

• -p *path*

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

• -s --silent

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

  本人提供Oracle(OCP、OCM)、MySQL(OCP)、PostgreSQL(PGCA、PGCE、PGCM)等数据库的培训和考证业务，私聊QQ646634621或微信db_bao，谢谢！

• -t *seconds* --timeout=*seconds*

  指定等待一个操作完成时要等待的最大秒数（见选项-w）。默认为PGCTLTIMEOUT环境变量的值，如果该环境变量没有设置则默认为60秒。

• -V --version

  打印pg_ctl版本并退出。

• -w --wait

  等待操作完成。模式start、stop、restart、promote以及register支持这个选项，并且对那些模式是默认的。在等待时，pg_ctl会一遍又一遍地检查服务器的PID文件，在两次检查之间会休眠一小段时间。当PID文件指示该服务器已经做好准备接受连接时，启动操作被认为完成。当服务器移除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*

  要注册的系统服务的启动类型。启动类型可以是auto、demand或者两者之一的第一个字母。如果这个选项被忽略，则auto是默认值。

• -U *username*

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

环境

• PGCTLTIMEOUT

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

• PGDATA

  默认的数据目录位置。

大部分的pg_ctl模式都要求知道数据目录的位置，因此-D选项是必需的，除非PGDATA被设置。

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

更多影响服务器的变量请见postgres。

文件

• postmaster.pid

  pg_ctl在数据目录中检查这个文件来判断服务器当前是否正在运行。

• postmaster.opts

  如果这个文件存在于数据目录中，pg_ctl（处于restart模式中）将把该文件的内容作为选项传递给postgres，除非通过-o选项进行了覆盖。这个文件的内容也会被显示在status模式中。

例子

启动服务器

要启动服务器并且等到服务器接受连接：

要使用端口 5433 启动服务器并且运行时不使用fsync：

停止服务器

要停止服务器，使用：

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

重启服务器

重启服务器几乎等价于停止服务器并且再次启动它，不过pg_ctl默认会保存并重用被传递给之前的运行实例的命令行选项。要以和之前相同的选项重启服务器，使用：

但是如果指定了-o，则会替换任何之前的选项。要使用端口 5433 重启并在重启时禁用fsync：

显示服务器状态

这里是pg_ctl状态输出的例子：

第二行是在重启模式可能被调用的命令行。

其它

pg_ctl 语法格式：

• 初始化数据库
  pg_ctl init[db] [-D DATADIR] [-s] [-o OPTIONS]

• 启动数据库
  pg_ctl start [-D DATADIR] [-l FILENAME] [-W] [-t SECS] [-s] [-o OPTIONS] [-p PATH] [-c]

• 关闭数据库
  pg_ctl stop [-D DATADIR] [-m SHUTDOWN-MODE] [-W] [-t SECS] [-s]

• 重启数据库
  pg_ctl restart [-D DATADIR] [-m SHUTDOWN-MODE] [-W] [-t SECS] [-s] [-o OPTIONS] [-c]

• 重新加载 postgresql.conf 或 pg_hba.conf 文件 ,重新读取配置文件(postgresql.conf,pg_hba.conf等，而不重启)

  pg_ctl reload [-D DATADIR] [-s]

• 查看服务器是否在指定的数据目录运行
  pg_ctl status [-D DATADIR]

• pg_ctl promote [-D DATADIR] [-W] [-t SECS] [-s]

• pg_ctl logrotate [-D DATADIR] [-s]

• pg_ctl kill SIGNALNAME PID

命令选项

• -D, --pgdata=DATADIR：指定数据库相关文件的数据目录，如果省略，默认读取 PGDATA 环境变量
• -s, --silent：静默输出，仅仅输出错误消息
• -t, --timeout=SECS：指定等待操作完成的最大延时秒数。默认为 PGCTLTIMEOUT 环境变量的值，如果省略，默认60秒
• -V, --version output version information, then exit
• -w, --wait：等待操作完成，如果操作在延迟时间内未完成，pg_ctl 退出状态为非零
• -W, --no-wait：不等待操作完成，不会提示数据库停止是否完成

启动 & 重启选项

• -c, --core-files allow postgres to produce core files
• -l, --log=FILENAME：将服务器日志输出追加到 filename中，也叫做服务器日志文件。如果该文件的 umask 设置为077，访问日志文件默认情况下其它用户不可读。
• -o, --options=OPTIONS command line options to pass to postgres (PostgreSQL server executable) or initdb
• -p PATH-TO-POSTGRES normally not necessary

启动 & 停止选项

• -m, --mode=MODE：指定关闭数据库的模式，有三个选项，smart,fast,immediate，省略默认为fast

关库选项：

• smart：smart模式会等待活动的事务提交结束， 并等待客户端主动断开连接之后关闭数据库
• fast：fast模式则会回滚所有活动的事务， 并强制断开客户端的连接之后关闭数据库（默认），相当于Oracle 中的 immediate模式关闭
• immediate：模式立即终止所有服务器进程，当下一次数据库启动时它会首先进入恢复状态（不推荐使用）( 相当于使用 kill 工具杀死进程[此方式不会干净的关闭数据库且可能会造成数据丢失] )