选择 打开 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。

受支持版本: 当前版本 (18) / 17 / 16 / 15 / 14
测试与开发版本: 19 / devel
不受支持的版本: 13 / 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0
历史版本PostgreSQL 9.0 已于 2015 年 10 月结束社区维护,本页译文保留供仍在使用旧版本的读者参考。新系统请看当前版本

9.24. 系统管理函数 #

表 9.55展示了那些可以用于查询以及修改运行时配置参数的函数。

表 9.55. 配置设定函数

Name Return Type 描述
current_setting(setting_name) text 获取设置的当前值
set_config(setting_name, new_value, is_local) text 设置参数并返回新值

函数current_setting返回设置setting_name的当前值。它对应于SQL命令SHOW。例如:

SELECT current_setting('datestyle');

 current_setting
-----------------
 ISO, MDY
(1 row)

set_config将参数setting_name设置为new_value。如果is_localtrue,新值仅适用于当前事务。如果要让新值适用于当前会话,请改用false。该函数对应于 SQL 命令SET。例如:

SELECT set_config('log_statement_stats', 'off', false);

 set_config
------------
 off
(1 row)

表 9.56中展示的函数向其他服务器进程发送控制信号。这些函数仅限超级用户使用。

表 9.56. 服务器信号函数

Name Return Type 描述
pg_cancel_backend(pid int) boolean 取消后端的当前查询。如果调用角色是被取消后端所属角色的成员,也允许执行此操作;但只有超级用户才能取消超级用户的后端。
pg_terminate_backend(pid int) boolean 终止后端。如果调用角色是被终止后端所属角色的成员,也允许执行此操作;但只有超级用户才能终止超级用户的后端。
pg_reload_conf() boolean 使服务器进程重新加载配置文件
pg_rotate_logfile() boolean 轮转服务器日志文件

这些函数在成功时都返回 true,否则返回 false

pg_cancel_backendpg_terminate_backend向由进程 ID 标识的后端进程发送信号(分别是SIGINTSIGTERM)。活动后端的进程 ID 可以从pg_stat_activity视图的procpid列中找到,或者通过在服务器上列出postgres进程(在 Unix 上使用ps,在Windows上使用任务管理器)得到。

pg_reload_conf 向服务器发送 SIGHUP 信号,使所有服务器进程重新加载配置文件。

pg_rotate_logfile 向日志文件管理器发送信号,使其立即切换到新的输出文件。只有内置日志收集器正在运行时才有效,否则不存在日志文件管理器子进程。

表 9.57中列出的函数有助于进行在线备份。这些函数不能在恢复期间执行。前三个函数仅限超级用户使用。

表 9.57. 备份控制函数

Name Return Type 描述
pg_start_backup(label text [, fast boolean ]) text 准备执行在线备份(默认仅限超级用户,但可以向其他用户授予EXECUTE权限以运行此函数)
pg_stop_backup() text 结束排他在线备份(默认仅限超级用户,但可以向其他用户授予EXECUTE权限以运行此函数)
pg_switch_xlog() text 强制切换到新的预写式日志文件(默认仅限超级用户,但可以向其他用户授予EXECUTE权限以运行此函数)
pg_current_xlog_location() text 获取当前预写式日志写入位置
pg_current_xlog_insert_location() text 获取当前预写式日志插入位置
pg_xlogfile_name_offset(location text) text, integer 将事务日志位置字符串转换为文件名和文件内的十进制字节偏移量
pg_xlogfile_name(location text) text 将事务日志位置字符串转换为文件名

pg_start_backup接受任意用户定义的备份标签。(通常是备份转储文件将要保存的名称。)该函数将备份标签文件(backup_label)写入数据库集簇的数据目录,执行检查点,然后以文本形式返回备份的起始事务日志位置。用户可以忽略该返回值,提供它只是因为它可能有用。

postgres=# select pg_start_backup('label_goes_here');
 pg_start_backup
-----------------
 0/D4445B8
(1 row)

还可以提供第二个可选参数,其类型为boolean。如果该参数为true,则尽快执行pg_start_backup。这会强制立即执行检查点,使 I/O 操作量陡增,并降低并发执行的查询的速度。

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仅提取预写式日志文件名。当指定的预写式日志位置恰好位于预写式日志文件边界时,这两个函数都返回前一个预写式日志文件的名称。这通常正是管理预写式日志归档时所需的行为,因为前一个文件是当前需要归档的最后一个文件。

有关正确使用这些函数的详细信息,参见第 24.3 节

表 9.58中展示的函数提供有关备库当前状态的信息。这些函数既可以在恢复期间执行,也可以在正常运行中执行。

表 9.58. 恢复信息函数

Name Return Type 描述
pg_is_in_recovery() bool 如果恢复仍在进行,则为真。
pg_last_xlog_receive_location() text 获取流复制最近接收并同步到磁盘的预写式日志位置。在流复制进行期间,该值单调增加。如果恢复已完成,该值将保持为恢复期间最后接收并同步到磁盘的 WAL 记录的位置。如果禁用了流复制,或者流复制尚未开始,此函数返回 NULL。
pg_last_xlog_replay_location() text 获取恢复期间最近重放的预写式日志位置。如果恢复仍在进行,该值单调增加。如果恢复已完成,该值将保持为该次恢复期间最后应用的 WAL 记录的位置。如果服务器未经恢复而正常启动,此函数返回 NULL。

表 9.59中的函数计算数据库对象的磁盘空间用量。

表 9.59. 数据库对象尺寸函数

Name Return Type 描述
pg_column_size(any) int 存储某个值所使用的字节数(可能已压缩)
pg_total_relation_size(regclass) bigint 指定表占用的磁盘空间总量,包括所有索引和 TOAST 数据
pg_table_size(regclass) bigint 指定表占用的磁盘空间,不包括索引(但包括 TOAST、空闲空间映射和可见性映射)
pg_indexes_size(regclass) bigint 指定表的索引占用的磁盘空间总量
pg_database_size(oid) bigint 指定 OID 的数据库占用的磁盘空间
pg_database_size(name) bigint 指定 OID 的数据库占用的磁盘空间
pg_tablespace_size(oid) bigint 指定 OID 的表空间占用的磁盘空间
pg_tablespace_size(name) bigint 指定 OID 的表空间占用的磁盘空间
pg_relation_size(relation regclass, fork text) bigint 指定 OID 或名称的表或索引的指定分支('main''fsm''vm')所使用的磁盘空间
pg_relation_size(relation regclass) bigint Shorthand for pg_relation_size(..., 'main')
pg_size_pretty(bigint) text 将以 64 位整数表示的字节大小转换为带有大小单位的人类可读格式

pg_column_size 显示存储任意单个数据值所用的空间。

pg_total_relation_size 接受表或 TOAST 表的 OID 或名称,返回该表占用的磁盘总空间,包括所有关联索引。此函数等同于 pg_table_size + pg_indexes_size

pg_table_size 接受表的 OID 或名称,返回该表所需的磁盘空间,不包括索引。(包括 TOAST 空间、空闲空间映射和可见性映射。)

pg_indexes_size 接受表的 OID 或名称,返回该表所有附属索引占用的磁盘总空间。

pg_database_sizepg_tablespace_size 接受数据库或表空间的 OID 或名称,返回其中占用的磁盘总空间。使用 pg_database_size 必须对指定数据库拥有 CONNECT 权限(默认授予)。使用 pg_tablespace_size 必须对指定表空间拥有 CREATE 权限;但如果该表空间是当前数据库的默认表空间,则不受此限制。

pg_relation_size接受表、索引或 TOAST 表的 OID 或名称,并以字节为单位返回该关系某个分支的磁盘大小。(注意,大多数情况下使用更高层的函数会更方便,例如pg_total_relation_sizepg_table_size,它们会把所有分支的大小相加。)只带一个参数时,返回关系的主数据分支大小。可以提供第二个参数来指定要检查的分支:

  • 'main'返回关系的主数据分支大小。

  • 'fsm'返回与该关系关联的空闲空间映射的大小(见第 54.3 节)。

  • 'vm'返回与该关系关联的可见性映射的大小(见第 54.4 节)。

pg_size_pretty 可以将其他函数的结果格式化为便于阅读的形式,适当地使用 kB、MB、GB 或 TB 单位。

表 9.60中展示的函数帮助标识数据库对象相关的磁盘文件。

表 9.60. 数据库对象位置函数

Name Return Type 描述
pg_relation_filenode(relation regclass) oid 指定关系的文件结点编号
pg_relation_filepath(relation regclass) text 指定关系的文件路径名

pg_relation_filenode 接受表、索引、序列或 TOAST 表的 OID 或名称,返回当前分配给它的文件结点编号。文件结点是关系文件名的基本组成部分(更多信息见第 54.1 节)。对于大多数表,结果与 pg_class.relfilenode 相同;但某些系统目录的 relfilenode 为零,必须使用此函数获取正确值。如果传入的关系没有存储空间(例如视图),函数返回 NULL。

pg_relation_filepathpg_relation_filenode 类似,但返回关系的完整文件路径名(相对于数据库集簇的数据目录 PGDATA)。

表 9.61中展示的函数提供对数据库服务器所在机器上文件的本地访问。只能访问数据库集簇目录和log_directory中的文件。集簇目录中的文件使用相对路径,日志文件使用与log_directory配置设置相匹配的路径。这些函数仅限超级用户使用。

表 9.61. 通用文件访问函数

Name Return Type 描述
pg_ls_dir(dirname text) setof text 列出目录内容。
pg_read_file(filename text, offset bigint, length bigint) text 返回文本文件的内容。
pg_stat_file(filename 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.62中展示的函数用于管理咨询锁。关于如何正确使用这些函数的细节,见第 13.3.4 节

表 9.62. 咨询锁函数

Name Return Type 描述
pg_advisory_lock(key bigint) void 获取排他会话级咨询锁
pg_advisory_lock(key1 int, key2 int) void 获取排他会话级咨询锁
pg_advisory_lock_shared(key bigint) void 获取共享会话级咨询锁
pg_advisory_lock_shared(key1 int, key2 int) void 获取共享会话级咨询锁
pg_try_advisory_lock(key bigint) boolean 如果可用,则获取排他会话级咨询锁
pg_try_advisory_lock(key1 int, key2 int) boolean 如果可用,则获取排他会话级咨询锁
pg_try_advisory_lock_shared(key bigint) boolean 如果可用,则获取共享会话级咨询锁
pg_try_advisory_lock_shared(key1 int, key2 int) boolean 如果可用,则获取共享会话级咨询锁
pg_advisory_unlock(key bigint) boolean 释放排他会话级咨询锁
pg_advisory_unlock(key1 int, key2 int) boolean 释放排他会话级咨询锁
pg_advisory_unlock_shared(key bigint) boolean 释放共享会话级咨询锁
pg_advisory_unlock_shared(key1 int, key2 int) boolean 释放共享会话级咨询锁
pg_advisory_unlock_all() void 释放当前会话持有的所有会话级咨询锁

pg_advisory_lock锁定由应用定义的资源,资源可以用一个 64 位键值或两个 32 位键值标识(注意,这两个键空间并不重叠)。键类型记录在pg_locks.objid中。如果另一个会话已经持有同一资源上的锁,该函数将等待,直到资源可用。该锁是排他的。多个锁请求会叠加,因此如果同一资源被锁定了三次,就必须解锁三次,才能释放给其他会话使用。

pg_advisory_lock_shared 的行为与 pg_advisory_lock 相同,但该锁可以与其他请求共享锁的会话共享。只有试图获取排他锁的会话会被阻挡。

pg_try_advisory_lockpg_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 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。