pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。
表 9.45展示了那些可以用于查询以及修改运行时配置参数的函数。
表 9.45. 配置设定函数
| Name | Return Type | 描述 |
|---|---|---|
|
text |
获取设置的当前值 |
|
text |
设置参数并返回新值 |
函数current_setting返回设置setting_name的当前值。它对应于SQL命令SHOW。例如:
SELECT current_setting('datestyle');
current_setting
-----------------
ISO, MDY
(1 row)
set_config将参数setting_name设置为new_value。如果is_local为true,新值仅适用于当前事务。如果要让新值适用于当前会话,请改用false。该函数对应于 SQL 命令SET。例如:
SELECT set_config('log_statement_stats', 'off', false);
set_config
------------
off
(1 row)
表 9.46中展示的函数向其他服务器进程发送控制信号。这些函数仅限超级用户使用。
表 9.46. Server Signalling Functions
| Name | Return Type | 描述 |
|---|---|---|
|
boolean |
取消后端的当前查询 |
|
boolean |
使服务器进程重新加载配置文件 |
|
boolean |
轮转服务器日志文件 |
这些函数在成功时都返回 true,否则返回 false。
pg_cancel_backend向由进程 ID 标识的后端进程发送一个查询取消(SIGINT)信号。活动后端的进程 ID 可以从pg_stat_activity视图的procpid列中找到,或者通过用ps列出服务器上的postgres进程得到。
pg_reload_conf 向服务器发送 SIGHUP 信号,使所有服务器进程重新加载配置文件。
pg_rotate_logfile 向日志文件管理器发送信号,使其立即切换到新的输出文件。只有使用redirect_stderr进行日志记录时才有效,否则不存在日志文件管理器子进程。
表 9.47中列出的函数有助于进行在线备份。这些函数不能在恢复期间执行。前三个函数仅限超级用户使用。
表 9.47. 备份控制函数
| Name | Return Type | 描述 |
|---|---|---|
|
text |
准备执行在线备份 |
|
text |
结束在线备份 |
|
text |
强制切换到新的事务日志文件 |
|
text |
获取当前预写式日志写入位置 |
|
text |
获取当前预写式日志插入位置 |
|
text, integer |
将事务日志位置字符串转换为文件名和文件内的十进制字节偏移量 |
|
text |
将事务日志位置字符串转换为文件名 |
pg_start_backup接受单个参数,它是一个任意的用户自定义备份标签。(通常是备份转储文件将要保存的名称。)该函数把一个备份标签文件写入数据库集簇的数据目录,然后以文本形式返回备份的起始事务日志位置。用户不必关注这个结果值,但提供它只是以防它有用。
postgres=# select pg_start_backup('label_goes_here');
pg_start_backup
-----------------
0/D4445B8
(1 row)
pg_stop_backup 删除 pg_start_backup 创建的标签文件,并在事务日志归档区域创建一个备份历史文件。历史文件包括传给 pg_start_backup 的标签、备份的起止事务日志位置以及备份的起止时间。返回值是备份的结束事务日志位置(同样可以忽略)。记录结束位置后,当前事务日志插入点会自动推进到下一个事务日志文件的起始处,使包含结束位置的事务日志文件可以立即归档,从而完成备份。
pg_switch_xlog 切换到下一个预写式日志文件,使当前文件可以归档(假设正在使用连续归档)。返回值是刚完成的预写式日志文件中的结束预写式日志位置加 1。如果自上次切换预写式日志以来没有发生任何预写式日志活动,pg_switch_xlog 不执行任何操作,并返回当前使用的预写式日志文件的起始位置。
pg_current_xlog_location 显示当前预写式日志写入位置,格式与上述函数相同。类似地,pg_current_xlog_insert_location 显示当前预写式日志插入点。插入位置是预写式日志在任意时刻的“逻辑”末尾,而写入位置是实际从服务器内部缓冲区写出的内容的末尾。写入位置是能从服务器外部检查到的内容的末尾,如果要归档尚未写满的预写式日志文件,通常需要的是这个位置。提供插入位置主要是为了服务器调试。这些都是只读操作,不需要超级用户权限。
可以使用pg_xlogfile_name_offset从上述任一函数的结果中提取相应的预写式日志文件名和字节偏移。例如:
postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
file_name | file_offset
--------------------------+-------------
00000001000000000000000D | 4039624
(1 row)
类似地,pg_xlogfile_name仅提取预写式日志文件名。当指定的预写式日志位置恰好位于预写式日志文件边界时,这两个函数都返回前一个预写式日志文件的名称。这通常正是管理预写式日志归档时所需的行为,因为前一个文件是当前需要归档的最后一个文件。
有关正确使用这些函数的详细信息,参见第 23.3 节。
表 9.48中的函数计算数据库对象的磁盘空间用量。
表 9.48. 数据库对象尺寸函数
| Name | Return Type | 描述 |
|---|---|---|
pg_column_size(any) |
int |
存储某个值所使用的字节数(可能已压缩) |
|
bigint |
指定 OID 的数据库占用的磁盘空间 |
|
bigint |
指定名称的数据库占用的磁盘空间 |
|
bigint |
指定 OID 的表或索引占用的磁盘空间 |
|
bigint |
指定名称的表或索引占用的磁盘空间。表名可以用模式名限定 |
|
text |
将以 64 位整数表示的字节大小转换为带有大小单位的人类可读格式 |
|
bigint |
指定 OID 的表空间占用的磁盘空间 |
|
bigint |
指定名称的表空间占用的磁盘空间 |
|
bigint |
指定 OID 的表占用的磁盘空间总量,包括索引和 TOAST 数据 |
|
bigint |
指定名称的表占用的磁盘空间总量,包括索引和 TOAST 数据。表名可以用模式名限定 |
pg_column_size 显示存储任意单个数据值所用的空间。
pg_database_size和pg_tablespace_size接受数据库或表空间的 OID 或名称,返回其中占用的磁盘总空间。
pg_relation_size接受表、索引或 TOAST 表的 OID 或名称,并以字节为单位返回大小。
pg_size_pretty 可以将其他函数的结果格式化为便于阅读的形式,适当地使用 kB、MB、GB 或 TB 单位。
pg_total_relation_size接受表或 TOAST 表的 OID 或名称,返回数据及所有关联索引和 TOAST 表的字节大小。
表 9.49中展示的函数提供对数据库服务器所在机器上文件的本地访问。只能访问数据库集簇目录和log_directory中的文件。集簇目录中的文件使用相对路径,日志文件使用与log_directory配置设置相匹配的路径。这些函数仅限超级用户使用。
表 9.49. 通用文件访问函数
| Name | Return Type | 描述 |
|---|---|---|
|
setof text |
列出目录内容。 |
|
text |
返回文本文件的内容。 |
|
record |
返回文件信息。 |
pg_ls_dir 返回指定目录中的所有名称,但不包括特殊项“.”和“..”。
pg_read_file从给定的offset开始返回文本文件的一部分,最多返回length字节(如果先到达文件末尾,则返回更少的字节)。如果offset为负,则它相对于文件末尾。
pg_stat_file返回一条记录,包含文件大小、最后访问时间戳、最后修改时间戳、最后文件状态更改时间戳(仅限 Unix 平台)、文件创建时间戳(仅限 Windows),以及一个boolean值,表示它是否是目录。典型用法包括:
SELECT * FROM pg_stat_file('filename');
SELECT (pg_stat_file('filename')).modification;
表 9.50中展示的函数用于管理咨询锁。关于如何正确使用这些函数的细节,见第 12.3.4 节。
表 9.50. 咨询锁函数
| Name | Return Type | 描述 |
|---|---|---|
|
void |
获取排他会话级咨询锁 |
|
void |
获取排他会话级咨询锁 |
|
void |
获取共享会话级咨询锁 |
|
void |
获取共享会话级咨询锁 |
|
boolean |
如果可用,则获取排他会话级咨询锁 |
|
boolean |
如果可用,则获取排他会话级咨询锁 |
|
boolean |
如果可用,则获取共享会话级咨询锁 |
|
boolean |
如果可用,则获取共享会话级咨询锁 |
|
boolean |
释放排他会话级咨询锁 |
|
boolean |
释放排他会话级咨询锁 |
|
boolean |
释放共享会话级咨询锁 |
|
boolean |
释放共享会话级咨询锁 |
|
void |
释放当前会话持有的所有会话级咨询锁 |
pg_advisory_lock锁定由应用定义的资源,资源可以用一个 64 位键值或两个 32 位键值标识(注意,这两个键空间并不重叠)。如果另一个会话已经持有同一资源上的锁,该函数将等待,直到资源可用。该锁是排他的。多个锁请求会叠加,因此如果同一资源被锁定了三次,就必须解锁三次,才能释放给其他会话使用。
pg_advisory_lock_shared 的行为与 pg_advisory_lock 相同,但该锁可以与其他请求共享锁的会话共享。只有试图获取排他锁的会话会被阻挡。
pg_try_advisory_lock 与 pg_advisory_lock 类似,但不会等待锁变得可用。它要么立即获得锁并返回 true,要么在无法立即获得锁时返回 false。
pg_try_advisory_lock_shared 的行为与 pg_try_advisory_lock 相同,但尝试获取的是共享锁,而不是排他锁。
pg_advisory_unlock将释放先前获得的排他咨询锁。如果成功释放锁,则返回true。如果未持有该锁,则返回false,并且服务器还会发出一条 SQL 警告。
pg_advisory_unlock_shared的行为与pg_advisory_unlock相同,只是它释放的是共享咨询锁。
pg_advisory_unlock_all将释放当前会话持有的所有咨询锁。(会话结束时会隐式调用此函数,即使客户端非正常断开连接也是如此。)
译文有误、术语不当或页面显示问题,请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。