PostgreSQL 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
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
]
描述
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
命令的效果。
选项
-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
-
只打印错误,不打印信息性的消息。
-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
模式中。
例子
启动服务器
要启动服务器并且等到服务器接受连接:
$
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"
第二行是在重启模式可能被调用的命令行。