系统管理函数

9.26. 系统管理函数

9.26.1. 配置设定函数 9.26.2. 服务器信号函数 9.26.3. 备份控制函数 9.26.4. 恢复控制函数 9.26.5. 快照同步函数 9.26.6. 复制函数 9.26.7. 数据库对象管理函数 9.26.8. 索引维护函数 9.26.9. 通用文件访问函数 9.26.10. 咨询锁函数

这一节描述的函数被用来控制和监视一个PostgreSQL安装。

9.26.1. 配置设定函数

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

表 9.82. 配置设定函数

名称	返回类型	描述
curr ent_setting(setting_name [, ``missing_ok`` ])	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)

如果没有名为``setting_name``的设置，除非提供``missing_ok``并且其值为true，current_setting会抛出错误。

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.26.2. 服务器信号函数

在表 9.83中展示的函数向其它服务器进程发送控制信号。默认情况下这些函数只能被超级用户使用，但是如果需要，可以利用GRANT把访问特权授予给其他用户。

表 9.83. 服务器信号函数

名称	返回类型	描述
` pg_cancel_backend(pid` int)	boolean	取 消一个后端的当前查询。如 果调用角色是被取消后端的 拥有者角色的成员或者调用 角色已经被授予pg_si gnal_backend，这也是 允许的，不过只有超级用户 才能取消超级用户的后端。
pg_reload_conf()	boolean	导致服务 器进程重载它们的配置文件
pg_rotate_logfile()	boolean	切换服务器的日志文件
pg _terminate_backend(pid int)	boolean	中止一个后端。如 果调用角色是被取消后端的 拥有者角色的成员或者调用 角色已经被授予pg_si gnal_backend，这也是 允许的，不过只有超级用户 才能取消超级用户的后端。

这些函数中的每一个都在成功时返回true，并且在失败时返回false。

pg_cancel_backend和pg_terminate_backend向由进程 ID 标识的后端进程发送信号（分别是SIGINT或SIGTERM）。一个活动后端的进程 ID可以从pg_stat_activity视图的pid列中找到，或者通过在服务器上列出postgres进程（在 Unix 上使用ps或者在Windows上使用任务管理器）得到。一个活动后端的角色可以在pg_stat_activity视图的usename列中找到。

pg_reload_conf给服务器发送一个SIGHUP信号， 导致所有服务器进程重载配置文件。

pg_rotate_logfile给日志文件管理器发送信号，告诉它立即切换到一个新的输出文件。这个函数只有在内建日志收集器运行时才能工作，因为否则就不存在日志文件管理器子进程。 subprocess.

9.26.3. 备份控制函数

表 9.84中展示的函数可以辅助制作在线备份。这些函数不能在恢复期间执行（非排他性的pg_start_backup，非排他性的pg_stop_backup，pg_is_in_backup、pg_backup_start_time和pg_wal_lsn_diff除外）。

表 9.84. 备份控制函数

名称	返回类型	描述
pg_create_ restore_point(name text)	pg_lsn	为执行 恢复创建一个命名点（ 默认只限于超级用户， 但是可以授予其他用户 EXECUTE 特权来执行该函数）
pg_curre nt_wal_flush_lsn()	pg_lsn	得到当前 的预写式日志刷写位置
pg_curren t_wal_insert_lsn()	pg_lsn	获得当 前预写式日志插入位置
pg _current_wal_lsn()	pg_lsn	获得当 前预写式日志写入位置
pg_ start_backup(label text [, ``fast`` boolean [, ``exclusive`` boolean]])	pg_lsn	准备执行在 线备份（默认只限于超 级用户或者复制角色， 但是可以授予其他用户 EXECUTE 特权来执行该函数）
pg_stop_backup()	pg_lsn	完成执行排他的在 线备份（默认只限于超 级用户或者复制角色， 但是可以授予其他用户 EXECUTE 特权来执行该函数）
pg_sto p_backup(exclusive boolean)	setof record	结束执行排他 或者非排他的在线备份 （ 默认只限于超级用户， 但是可以授予其他用户 EXECUTE 特权来执行该函数）
` pg_is_in_backup()`	bool	如果一个在线排他备 份仍在进行中则为真。
pg_b ackup_start_time()	timest amp with time zone	获得一个进行中的在线 排他备份的开始时间。
pg_switch_wal()	pg_lsn	强制切换到一个 新的预写式日志文件（ 默认只限于超级用户， 但是可以授予其他用户 EXECUTE 特权来执行该函数）
p g_walfile_name(lsn text)	pg_lsn	转换预写式日 志位置字符串为文件名
pg_walfi le_name_offset(lsn text)	pg_lsn, integer	转换预写式日志位置 字符串为文件名以及文 件内的十进制字节偏移
p g_wal_lsn_diff(lsn pg_lsn, ``lsn`` pg_lsn)	numeric	计算两个预 写式日志位置间的差别

pg_start_backup接受一个参数，这个参数可以是备份的任意用户定义的标签（通常这是备份转储文件将被存储的名字）。当被用在排他模式中时，该函数向数据库集簇的数据目录写入一个备份标签文件（backup_label）和一个表空间映射文件（tablespace_map，如果在pg_tblspc/目录中有任何链接），执行一个检查点，然后以文本方式返回备份的起始预写式日志位置。用户可以忽略这个结果值，但是为了可能需要的场合我们还是提供该值。 当在非排他模式中使用时，这些文件的内容会转而由pg_stop_backup函数返回，并且应该由调用者写入到备份中去。

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创建的tablespace_map文件（如果存在）。在一次非排他备份中，backup_label和tablespace_map的内容会包含在该函数返回的结果中，并且应该被写入到该备份的文件中（这些内容不在数据目录中）。有一个可选的boolean类型的第二参数。如果为假，pg_stop_backup将在备份完成后立即返回而不等待WAL被归档。这种行为仅对独立监控WAL归档的备份软件有用。否则，让备份一致所要求的WAL可能会丢失，进而让备份变得毫无用处。当这个参数被设置为真时，在启用归档的前提下pg_stop_backup将等待WAL被归档，在后备服务器上，这意味只有archive_mode = always时才会等待。如果主服务器上的写活动很低，在主服务器上运行pg_switch_wal以触发一次即刻的段切换会很有用。

当在主服务器上执行时，该函数还在预写式日志归档区里创建一个备份历史文件。这个历史文件包含给予pg_start_backup的标签、备份的起始与终止预写式日志位置以及备份的起始和终止时间。返回值是备份的终止预写式日志位置（同样也可以被忽略）。在记录结束位置之后，当前预写式日志插入点被自动地推进到下一个预写式日志文件，这样结束的预写式日志文件可以立即被归档来结束备份。

pg_switch_wal移动到下一个预写式日志文件，允许当前文件被归档（假定你正在使用连续归档）。返回值是在甘冈完成的预写式日志文件中结束预写式日志位置 + 1。如果从上一次预写式日志切换依赖没有预写式日志活动，pg_switch_wal不会做任何事情并且返回当前正在使用的预写式日志文件的开始位置。

pg_create_restore_point创建一个命名预写式日志记录，它可以被用作恢复目标，并且返回相应的预写式日志位置。这个给定的名字可以用于recovery_target_name来指定恢复要进行到的点。避免使用同一个名称创建多个恢复点，因为恢复会停止在第一个匹配名称的恢复目标。

pg_current_wal_lsn以上述函数所使用的相同格式显示当前预写式日志的写位置。类似地，pg_current_wal_insert_lsn显示当前预写式日志插入点，而pg_current_wal_flush_lsn显示当前预写式日志的刷写点。在任何情况下，插入点是预写式日志的“逻辑”终止点，而写入位置是已经实际从服务器内部缓冲区写出的日志的终止点，刷写位置则是被确保写入到持久存储中的日志的终止点。写入位置是可以从服务器外部检查的终止点，对那些关注归档部分完成预写式日志文件的人来说，这就是他们需要的位置。插入和刷写点主要是为了服务器调试目的而存在的。这些都是只读操作并且不需要超级用户权限。

你可以使用pg_walfile_name_offset从任何上述函数的结果中抽取相应的预写式日志文件名称以及字节偏移。例如：

postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
        file_name         | file_offset
--------------------------+-------------
 00000001000000000000000D |     4039624
(1 row)

相似地，pg_walfile_name只抽取预写式日志文件名。当给定的预写式日志位置正好在一个预写式日志文件的边界，这些函数都返回之前的预写式日志文件的名称。这对管理预写式日志归档行为通常是所希望的行为，因为前一个文件是当前需要被归档的最后一个文件。

pg_wal_lsn_diff以字节数计算两个预写式日志位置之间的差别。它可以和pg_stat_replication或表 9.84中其他的函数一起使用来获得复制延迟。

9.26.4. 恢复控制函数

表 9.85中展示的函数提供有关后备机当前状态的信息。这些函数可以在恢复或普通运行过程中被执行。

表 9.85. 恢复信息函数

名称	返回类型	描述
p g_is_in_recovery()	bool	如果恢 复仍在进行中，为真。
pg_last _wal_receive_lsn()	pg_lsn	获得最后一个收到 并由流复制同步到磁盘 的预写式日志位置。当 流复制在进行中时，这 将单调增加。如果恢复 已经完成，这将保持静 止在恢复过程中收到并 同步到磁盘的最后一个 WAL 记录。如果流 复制被禁用，或者还没 有被启动，该函数返回 NULL。
pg_las t_wal_replay_lsn()	pg_lsn	获得恢复过程中被重 放的最后一个预写式日 志位置。当流复制在进 行中时，这将单调增加 。如果恢复已经完成， 这将保持静止在恢复过 程中被应用的最后一个 WAL 记录。如 果服务器被正常启动而 没有恢复，该函数返回 NULL。
pg_last_xact_ replay_timestamp()	timest amp with time zone	获得恢复过程中被重 放的最后一个事务的时 间戳。这是在主机上产 生的事务的提交或中止 WAL 记录的时间。如果 在恢复过程中没有事务 被重放，这个函数返回 NULL。否则，如 果恢复仍在进行这将单 调增加。如果恢复已经 完成，则这个值会保持 静止在恢复过程中最后 一个被应用的事务。如 果服务器被正常启动而 没有恢复，该函数返回 NULL。

表 9.86中展示的函数空值恢复的进程。这些函数只能在恢复过程中被执行。

表 9.86. 恢复控制函数

名称	返回类型	描述
pg_ is_wal_replay_paused()	bool	如果恢复被暂停，为真。
pg_promote(wait boolean DEFAULT true, ``wait_seconds`` integer DEFAULT 60)	boolean	促进物理备用服务器。 当 ``wait`` 设置为true（默 认值）时，该函数将等待晋 升完成或``wait_second s``秒，如果晋升成功， 则返回true，否则 返回false。如果 ``wait``被设置为 false，则会返回 true。函数在发送后 立即返回true。 SIGUSR1给postmast er触发推广。此功能默认只 限于超级用户，但其他用户 可以被 授予EXECUTE来运行函数。
` pg_wal_replay_pause()`	void	立即暂停恢 复（默认仅限于超级用户, 但是可以授予其他用户 EXECUTE 特权来执行该函数）。
`` pg_wal_replay_resume()``	void	如果恢复被暂停， 重启之（默认仅限于超级用 户，但是可以授予其他用户 EXECUTE 特权来执行该函数）。

在恢复被暂停时，不会有进一步的数据库改变被应用。如果在热备模式，所有新的查询将看到数据库的同一个一致快照，并且在恢复被继续之前不会有更多查询冲突会产生。

如果流复制被禁用，暂停状态可以无限制地继续而不出问题。在流复制进行时，WAL 记录将继续被接收，最后将会填满可用的磁盘空间，取决于暂停的持续时间、WAL 的产生率和可用的磁盘空间。

9.26.5. 快照同步函数

PostgreSQL允许数据库会话同步它们的快照。一个快照决定对于正在使用该快照的事务哪些数据是可见的。当两个或者更多个会话需要看到数据库中的相同内容时，就需要同步快照。如果两个会话独立开始其事务，就总是有可能有某个第三事务在两个START TRANSACTION命令的执行之间提交，这样其中一个会话就可以看到该事务的效果而另一个则看不到。

为了解决这个问题，PostgreSQL允许一个事务导出它正在使用的快照。只要导出的事务仍然保持打开，其他事务可以导入它的快照，并且因此可以保证它们可以看到和第一个事务看到的完全一样的数据库视图。但是注意这些事务中的任何一个对数据库所作的更改对其他事务仍然保持不可见，和未提交事务所作的修改一样。因此这些事务是针对以前存在的数据同步，而对由它们自己所作的更改则采取正常的动作。

如表 9.87中所示，快照通过pg_export_snapshot函数导出，并且通过SET TRANSACTION命令导入。

表 9.87. 快照同步函数

名称	返回类型	描述
pg_export_snapshot()	text	保存当前快照并返回它的标识符

函数pg_export_snapshot保存当前的快照并且返回一个text串标识该快照。该字符串必须被传递（到数据库外）给希望导入快照的客户端。直到导出快照的事务的末尾，快照都可以被导入。如果需要，一个事务可以导出多于一个快照。注意这样做只在 READ COMMITTED事务中有用，因为在REPEATABLE READ和更高隔离级别中，事务在它们的生命期中都使用同一个快照。一旦一个事务已经导出了任何快照，它不能使用PREPARE TRANSACTION。

关于如何使用一个已导出快照的细节请见SET TRANSACTION.

9.26.6. 复制函数

表 9.88中展示的函数 用于控制以及与复制特性交互。 复制原点函数的使用仅限于超级用户。 复制槽的函数只限于超级用户和拥有REPLICATION权限的用户。

很多这些函数在复制协议中都有等价的命令。

表 复制 SQL 函数

函数	返回类型	描述
pg_crea te_physical_replicat ion_slot(slot_name name [, ``im mediately_reserve`` boolean])	(``slot_name`` name, ``xlog_position`` pg_lsn)	创建一个新的名 为``slot_name`` 的物理复制槽。第二 个参数是可选的，当它 为true时，立 即为这个物理槽指定要 被保留的LSN。否则该 LSN会被保留在来自一 个流复制客户端的第一 个连接上。来自一个物 理槽的流改变只可能出 现在使用流复制协议时 — 见第 52 .4 节。 当可选的第三参数* temporary``*\ 被设 置为真时，指定那个槽 不会被持久地存储在磁 盘上并且仅对当前会话 的使用有意义。临时槽 也会在发生任何错误时 被释放。这个函数对应 于复制协议命令\ ``CR EATE_REPLICATION_SLO T ... PHYSICAL。
pg_drop_replicat ion_slot(slot_name name)	void	丢弃名为 ``slot_name``的物理或逻辑复制槽。 和复制协议命令``D ROP_REPLICATION_SLOT ``相同。对于逻辑槽 ，在连接到在其中创建 该槽的同一个数据库时 ，必须调用这个函数。
pg_cre ate_logical_replicat ion_slot(slot_name name, ``plugin`` name)	(``slot_name`` name, ``lsn`` pg_lsn)	使用输出插件``plu gin``创建一个名为 ``slot_name``的 新逻辑（解码）复制槽 。当可选的第三参数 ``temporary``被 设置为真时，指定那个 槽不会被持久地存储在 磁盘上并且仅对当前会 话的使用有意义。临时 槽也会在发生任何错误 时被释放。对这个函数 的调用与复制协议命令 ``CREATE_REPLICAT ION_SLOT … LOGICAL ``具有相同的效果。
pg_copy_p hysical_replication_ slot(src_slot_name name, ``dst_slot_name`` name [, ``temporary`` boolean])	(``slot_name`` name, ``lsn`` pg_lsn)	将一个名为* ``src_slot_name``*的现有物理复制槽复制 到一个名为``dst_ slot_name``的物理 复制槽。被复制的物理 槽开始从与源槽相同的 LSN开始保留WAL。* ``temporary``*是可 选的。如果省略了* ``temporary``*，则 使用与源槽相同的值。
pg_copy_ logical_replication_ slot(src_slot_name name, ``dst_slot_name`` name [, ``temporary`` boolean [, ``plugin`` name]])	(``slot_name`` name, ``lsn`` pg_lsn)	复制一 个名为``src_slot _name``的现有逻辑 复制槽。到一个名为 ``dst_slot_name`` 的逻辑复制槽。同时 改变输出插件和持久性 。被复制的逻辑槽开始 来自与源逻辑 槽相同的LSN。这两个 ``temporary``和 ``plugin``是可 选的。如果省略了* ``temporary``*或``plugin``。使用 与源逻辑槽相同的值。
` pg_logical_slot_get _changes(slot_name` name, ``upto_lsn`` pg_lsn, ``upto_nchanges`` int, VARIADIC ``options`` text[])	(``lsn`` pg_lsn, ``xid`` xid, ``data`` text)	返回槽 ``slot_name``中 的改变，从上一次已经 被消费的点开始返回。 如果`` upto_lsn``和`` upto_nchanges``为 NULL，逻辑解码将一 直继续到 WAL 的末尾。如果``upto_lsn``为非 NULL， 解码将只包括那些在指 定 LSN 之前提交 的事务。如果``up to_nchanges``为非 NULL， 解码将在其 产生的行数超过指定值 后停止。不过要注意， 被 返回的实际行数可能更 大，因为对这个限制的 检查只会在增加了解码 每个新的提交事务产生 的行之后进行。
`` pg_logical_slot_peek _changes(slot_name`` name, ``upto_lsn`` pg_lsn, ``upto_nchanges`` int, VARIADIC ``options`` text[])	(``lsn`` text, ``xid`` xid, ``data`` text)	行为就像` pg_logical_slot_get _changes()`函数， 不过改变不会被消费， 即在未来的调用 中还会返回这些改变。
pg_log ical_slot_get_binary _changes(slot_name name, ``upto_lsn`` pg_lsn, ``upto_nchanges`` int, VARIADIC ``options`` text[])	(``lsn`` pg_lsn, ``xid`` xid, ``data`` bytea)	行为就像` pg_logical_slot_get _changes()`函数， 不过改变会以 bytea返回。
pg_logi cal_slot_peek_binary _changes(slot_name name, ``upto_lsn`` pg_lsn, ``upto_nchanges`` int, VARIADIC ``options`` text[])	(``lsn`` pg_lsn, ``xid`` xid, ``data`` bytea)	行为就像` pg_logical_slot_get _changes()`函数， 不过改变会以 bytea返回并且 这些改变不会被消费， 即在未来的调用 中还会返回这些改变。
` pg_replication_slot _advance(slot_name` name, ``upto_lsn`` pg_lsn)	(``slot_name`` name, ``end_lsn`` pg_lsn) bool	将复 制槽的当前确认的位置 提前到名为``slot _name``的复制槽的 当前确认位置。该槽不 会向后移动，也不会移 动到当前插入位置之外 。返回该槽的名称和它 被推进到的真实位置。 如果有任何推进，则在 后续的检查点中写出更 新后的槽的信息。如果 发生崩溃，该槽位可能 会返回到之前的位置。
`` pg_replication_origi n_create(node_name`` text)	oid	用给定的外部名 称创建一个复制源，并 且返回分配给它的内部 id。
pg_replication_ori gin_drop(node_name text)	void	删除一个之 前创建的复制源，包括 任何相关的重放进度。
pg_replication_or igin_oid(node_name text)	oid	用名称查 找复制源并且返回内部 id。如果 没有找到则抛出错误。
pg_repl ication_origin_sessi on_setup(node_name text)	void	把当 前会话标记为正在从给 定的源进行重放，允许 重放进度被跟踪。使用 pg_repl ication_origin_sessi on_reset可以取消 标记。只有之前没有 源被配置时才能使用。
` pg_replication_orig in_session_reset()`	void	取消pg_replic ation_origin_session _setup()的效果。
pg _replication_origin_ session_is_setup()	bool	当前会话中是否已 经配置了一个复制源？
pg_rep lication_origin_sess ion_progress(flush bool)	pg_lsn	返 回当前会话中配置的复 制源的重放位置。参数 * ``flush``*决定对应 的本地事务是否被确保 已经刷入磁盘。
pg_re plication_origin_xac t_setup(origin_lsn pg_lsn, ` `origin_timestamp`` timestamptz)	void	标 记当前事务为正在重放 一个已经在给定的LSN 和时间戳提交的事 务。只有当之前已经用 pg_repl ication_origin_sessi on_setup()配置过 一个 复制源时才能被调用。
pg_replication_o rigin_xact_reset()	void	取消pg_rep lication_origin_xact _setup()的效果。
p g_replication_origin _advance(node_name text, ``pos`` pg_lsn)	void	把给 定节点的复制进度设置 为给定的位置。这主要 用于配置更改或者类似 操作 之后设置初始位置或者 新位置。注意这个函数 的不当使用可能会导致 不一致的复制数据。
pg _replication_origin_ progress(node_name text, ``flush`` bool)	pg_lsn	返回给定复 制元的重放位置。参数 * ``flush``*决定对应 的本地事务是否被确保 已经刷入磁盘。
` pg_logical_emit_mes sage(transactional` bool, ``prefix`` text, ``content`` text)	pg_lsn	发出 文本形式的逻辑解码消 息。这可以被用来通过 WAL 向逻辑解码 插件传递一般消息。参 数``transactiona l``指定该消息是否 应该是当前事务的一部 分或者当逻辑解码读到 该记录时该消息是否应 该被立刻写入并且解码 。``prefix``是 逻辑解码插件用来识别 它们感兴趣的消息的文 本前缀。``conten t``是消息的文本。
` pg_logical_emit_mes sage(transactional` bool, ``prefix`` text, ``content`` bytea)	pg_lsn	发出二进制 逻辑解码消息。这可以 被用来通过WAL向逻辑 解码插件传递一般性消 息。参数``transa ctional``指定该消 息是否应该成为当前事 务的一部分或者是否应 该在逻辑解码过程读到 该记录时立刻进行写入 和解码。参数``pre fix``是一个逻辑解 码插件使用的文本前缀 ，逻辑解码插件用它来 识别感兴趣的消息。参 数``content``是消息的二进制内容。

9.26.7. 数据库对象管理函数

表 9.89中展示的函数计算数据库对象使用的磁盘空间。

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

名称	返回类型	描述
pg_column_size(any)	int	存储一个特定值（ 可能压缩过）所需的字节数
pg_database_size(oid)	bigint	指定 OID 的数据库使用的磁盘空间
` pg_database_size(name`)	bigint	指定名 称的数据库使用的磁盘空间
pg _indexes_size(regclass)	bigint	附加到指定 表的索引所占的总磁盘空间
pg _relation_size(relation regclass, ``fork`` text)	bigint	指定表或索引的指定分叉（ 'main'、'fsm' ``\ 、\ ``'vm'或' init'）使用的磁盘空间
pg _relation_size(relation regclass)	bigint	pg_relation_ size(..., 'main')的简写
pg_size_bytes(text)	bigint	把人类可读格式的带 有单位的尺寸转换成字节数
` pg_size_pretty(bigint`)	text	将表示成一个 64位整数的字节尺寸转换为 带尺寸单位的人类可读格式
`` pg_size_pretty(numeric``)	text	将表示成一 个数字值的字节尺寸转换为 带尺寸单位的人类可读格式
`` pg_table_size(regclass``)	bigint	被指定表使用的磁 盘空间，排除索引（但包括 TOAST、空 闲空间映射和可见性映射）
`` pg_tablespace_size(oid``)	bigint	指定 OID 的表空间使用的磁盘空间
p g_tablespace_size(name)	bigint	指定名 称的表空间使用的磁盘空间
pg_total_ relation_size(regclass)	bigint	指定表所用的总磁盘空间， 包括所有的索引和TOAST数据

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_size以及pg_tablespace_size接受数据库或者表空间的OID或者名称，并且返回它们使用的磁盘空间。要使用pg_database_size，用户必须具有指定数据库上的CONNECT权限（默认情况下已经被授予）或者是pg_read_all_stats角色的一个成员。要使用pg_tablespace_size，用户必须具有指定表空间上的CREATE权限或者是pg_read_all_stats角色的一个成员，除非该表空间是当前数据库的默认表空间。

pg_relation_size接受一个表、索引或 TOAST 表的 OID 或者名称，并且返回那个关系的一个分叉所占的磁盘空间的字节尺寸（注意 对于大部分目的，使用更高层的函数pg_total_relation_size 或者pg_table_size会更方便，它们会合计所有分叉的尺寸）。 如果只得到一个参数，它会返回该关系的主数据分叉的尺寸。提供第二个参数 可以指定要检查哪个分叉：

• 'main'返回该关系主数据分叉的尺寸。

• 'fsm'返回与该关系相关的空闲空间映射的尺寸。

• 'vm'返回与该关系相关的可见性映射的尺寸。

• 'init'返回与该关系相关的初始化分叉的尺寸。

pg_size_pretty可以用于把其它函数之一的结果格式化成一种人类易读的格式，可以根据情况使用字节、kB、MB、GB 或者 TB。

pg_size_bytes可以被用来从人类可读格式的字符串得到其中所表示的字节数。其输入可能带有的单位包括字节、kB、MB、GB 或者 TB，并且对输入进行解析时是区分大小写的。如果没有指定单位，会假定单位为字节。

备注

注意

函数pg_size_pretty和pg_size_bytes所使用的单位 kB、MB、GB 和 TB 是用 2 的幂而不是 10 的幂来定义，因此 1kB 是 1024 字节，1MB 是 1024² = 1048576 字节，以此类推。

上述操作表和索引的函数接受一个regclass参数，它是该表或索引在pg_class系统目录中的 OID。你不必手工去查找该 OID，因为regclass数据类型的输入转换器会为你代劳。只写包围在单引号内的表名，这样它看起来像一个文字常量。为了与普通SQL名称的处理相兼容，该字符串将被转换为小写形式，除非其中在表名周围包含双引号。

如果一个 OID 不表示一个已有的对象并且被作为参数传递给了上述函数，将会返回 NULL。

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

表 9.90. 数据库对象定位函数

名称	返回类型	描述
pg_rela tion_filenode(relation regclass)	oid	指定关系的文件结点号
pg_rela tion_filepath(relation regclass)	text	指定关系的文件路径名
pg_fileno de_relation(tablespace oid, ``filenode`` oid)	regclass	查找与给定的表 空间和文件节点相关的关系

pg_relation_filenode接受一个表、索引、序列或 TOAST 表的 OID 或名称，返回当前分配给它的“filenode”号。文件结点是关系的文件名的基本组件。对于大多数表结果和pg_class.relfilenode相同，但是对于某些系统目录relfilenode为零，并且必须使用此函数获取正确的值。 如果传递一个没有存储的关系（如视图），此函数将返回 NULL。

pg_relation_filepath与pg_relation_filenode类似，但是它返回关系的整个文件路径名（相对于数据库集簇的数据目录PGDATA）。

pg_filenode_relation是pg_relation_filenode的反向函数。给定一个“tablespace” OID 以及一个 “filenode”，它会返回相关关系的 OID。对于一个在数据库的默认表空间中的表，该表空间可以指定为 0。

表 9.91列出了用来管理排序规则的函数。

表 9.91. 排序规则管理函数

名称	返回类型	描述
pg_collati on_actual_version(oid)	text	返回来自操作 系统的排序规则的实际版本
pg_import_sy stem_collations(schema regnamespace)	integer	导入操作系统排序规则

pg_collation_actual_version返回当前安装在操作系统中的该排序规则对象的实际版本。如果这个版本与pg_collation.collversion中的值不同，则依赖于该排序规则的对象可能需要被重建。还可以参考`ALTER COLLATION `__。

pg_import_system_collations基于在操作系统中找到的所有locale在系统目录pg_collation中加入排序规则。这是initdb会使用的函数。如果后来在操作系统上安装了额外的locale，可以再次运行这个函数加入新locale的排序规则。匹配pg_collation中现有项的locale将被跳过（但是这个函数不会移除以在操作系统中不再存在的locale为基础的排序规则对象）。``schema``参数通常是pg_catalog，但这不是一种要求，排序规则也可以被安装到其他的方案中。该函数返回其创建的新排序规则对象的数量。

表 9.92. 分区信息函数

名称	返回类型	描述
pg_parti tion_tree(regclass)	setof record	列出一个分区树 中的表或索引的相关信 息。给定的分区表或分 区索引，每张表有一行 分区。 提供的信息 包括分区的名称，它的 直系父级的名称，一个 布尔值，表示该分区是 否是一个叶子，以及一 个整数，表示它在层次 结构中的级别。level的 值从0开始，表 示输入表或索引作为分 区树的根，1表 示其分区，2表 示其分区，以此类推。
pg_partition_ ancestors(regclass)	setof regclass	列出给定分区的祖先 关系，包括分区本身。
pg_parti tion_root(regclass)	regclass	R返回给定关系所属的分 区树的最上层父节点。

要检查第 5.11.2.1 节中描述的measurement表中的数据的总大小，可以使用下面的查询:

=# SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size
     FROM pg_partition_tree('measurement');
 total_size
------------
 24 kB
(1 row)

9.26.8. 索引维护函数

表 9.93展示了可用于 索引维护任务的函数。这些函数不能在恢复期间执行。只有超级用户以及给定索引的拥有者才能是用这些函数。

表 9.93. 索引维护函数

名称	返回类型	描述
brin_summ arize_new_values(index regclass)	integer	对还没有建 立概要的页面范围建立概要
brin _summarize_range(index regclass, ``blockNumber`` bigint)	integer	如果还没 有对覆盖给定块的页面范围 建立概要，则对其建立概要
brin_d esummarize_range(index regclass, ``blockNumber`` bigint)	integer	如 果覆盖给定块的页面范围已 经建立有概要，则去掉概要
gin_cl ean_pending_list(index regclass)	bigint	把 GIN 待处理 列表项移动到主索引结构中

brin_summarize_new_values接收一个 BRIN 索引的 OID 或者名称作为参数并且检查该索引以找到基表中当前还没有被该索引汇总的页面范围。对任意一个这样的范围，它将通过扫描那些表页面创建一个新的摘要索引元组。它会返回被插入到该索引的新页面范围摘要的数量。brin_summarize_range做同样的事情，不过它只对覆盖给定块号的范围建立概要。

gin_clean_pending_list接受一个 GIN 索引的 OID 或者名字，并且通过把指定索引的待处理列表中的项批量移动到主 GIN 数据结构来清理该索引的待处理列表。它会返回从待处理列表中移除的页数。注意如果其参数是一个禁用fastupdate选项构建的 GIN 索引，那么不会做清理并且返回值为 0，因为该索引根本没有待处理列表。

9.26.9. 通用文件访问函数

表 9.94中展示的函数提供了对数据库服务器所在机器上的文件的本地访问。只能访问数据库集簇目录以及log_directory中的文件，除非用户被授予了角色pg_read_server_files。 使用相对路径访问集簇目录里面的文件，以及匹配 log_directory配置设置的路径访问日志文件。

注意向用户授予pg_read_file()或者相关函数上的EXECUTE特权，函数会允许他们读取服务器上该数据库能读取的任何文件并且这些读取动作会绕过所有的数据库内特权检查。这意味着，除了别的之外，具有这种访问的用户能够读取pg_authid表中包含着认证信息的内容，也能读取数据库中的任意文件。因此，授予对这些函数的访问应该要很仔细地考虑。

表 9.94. 通用文件访问函数

名称	返回类型	描述
pg_ls_dir(dirname text [, ``missing_ok`` boolean, ``include_dot_dirs`` boolean])	setof text	列出 目录中的内容。默认仅限 于超级用户使用，但是可 以给其他用户授予EXECU TE让他们运行这个函数。
pg_ls_logdir()	setof record	列出日志目录中文 件的名称、尺寸以及最后 修改时间。访问被授予给 pg_monitor角色 的成员，并且可以被授予 给其他非超级用户角色。
pg_ls_waldir()	setof record	列出WAL目录中文 件的名称、尺寸以及最后 修改时间。访问被授予给 pg_monitor角色 的成员，并且可以被授予 给其他非超级用户角色。
pg_ls _archive_statusdir()	setof record	列出WAL存档状态目录中 文件的名称、大小和最后 一次修改时间。访问权限 只授予pg_monitor 角色的成员，也可以授 予其他非超级用户角色。
pg_l s_tmpdir([tablespace oid])	setof record	为` `tablespace``列出临 时目录中文件的名称、大 小和最后一次修改时间。 如果没 有提供``tablespace` `，则在临时目录中的 pg_def ault表空间被使用。 pg_monitor角色的 成员可以访问，其他非超 级用户角色也可以访问。
p g_read_file(filename text [, ``offset`` bigint, ``length`` bigint [, ``missing_ok`` boolean] ])	text	返回一个文 本文件的内容。默认仅限 于超级用户使用，但是可 以给其他用户授予EXECU TE让他们运行这个函数。
pg_read_ binary_file(filename text [, ``offset`` bigint, ``length`` bigint [, ``missing_ok`` boolean] ])	bytea	返回一 个文件的内容。默认仅限 于超级用户使用，但是可 以给其他用户授予EXECU TE让他们运行这个函数。
p g_stat_file(filename text[, ``missing_ok`` boolean])	record	返回关于一 个文件的信息。默认仅限 于超级用户使用，但是可 以给其他用户授予EXECU TE让他们运行这个函数。

这些函数中的某些有一个可选的``missing_ok``参数， 它指定文件或者目录不存在时的行为。如果为true， 函数会返回 NULL （pg_ls_dir除外，它返回一个空 结果集）。如果为false，则发生一个错误。默认是 false。

pg_ls_dir返回指定目录中所有文件（以及目录和其他特殊文件） 的名称。``include_dot_dirs``指示结果集中是否包括 “.”和“..”。默认是排除它们（false），但是 当``missing_ok``为true时把它们包括在内是 有用的，因为可以把一个空目录与一个不存在的目录区分开。

pg_ls_logdir返回日志目录中每个文件的名称、尺寸以及最后的修改时间（mtime）。默认情况下，只有超级用户以及pg_monitor角色的成员能够使用这个函数。可以使用GRANT把访问授予给其他人。

pg_ls_waldir返回预写式日志（WAL）目录中每个文件的名称、尺寸以及最后的修改时间（mtime）。默认情况下，只有超级用户以及pg_monitor角色的成员能够使用这个函数。可以使用GRANT把访问授予给其他人。

pg_ls_archive_statusdir返回WAL归档状态目录pg_wal/archive_status中每个文件的名称、大小和最后一次修改时间（mtime）。默认情况下，只有超级用户和pg_monitor角色的成员才能使用此函数。可使用GRANT授权其他用户访问。

pg_ls_tmpdir返回指定的``tablespace``临时文件目录中每个文件的名称、大小和最后一次修改时间（mtime）。 如果没有提供``tablespace``，则使用pg_default表空间。 默认情况下，只有超级用户和pg_monitor角色的成员才能使用这个函数。 可使用GRANT授权其他用户访问。

pg_read_file返回一个文本文件的一部分，从给定的``offset``开始，返回最多``length``字节（如果先到达文件末尾则会稍短）。如果``offset``为负，它相对于文件的末尾。如果``offset``和``length``被忽略，整个文件都被返回。从文件中读的字节被使用服务器编码解释成一个字符串；如果它们在编码中不合法则抛出一个错误。

pg_read_binary_file与pg_read_file相似，除了前者的结果是一个bytea值；相应地，不会执行编码检查。通过与convert_from函数结合，这个函数可以用来读取一个指定编码的文件：

SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8');

pg_stat_file返回一个记录，其中包含文件尺寸、最后访问时间戳、最后修改时间戳、最后文件状态改变时间戳（只支持 Unix 平台）、文件创建时间戳（只支持 Windows）和一个boolean指示它是否为目录。通常的用法包括：

SELECT * FROM pg_stat_file('filename');
SELECT (pg_stat_file('filename')).modification;

9.26.10. 咨询锁函数

表 9.95. 咨询锁函数

名称	返回类型	描述
pg_advisory_lock(key bigint)	void	获得排他会话级别咨询锁
` pg_advisory_lock(key1` int, ``key2`` int)	void	获得排他会话级别咨询锁
pg_ad visory_lock_shared(key bigint)	void	获得共享会话级别咨询锁
pg_adv isory_lock_shared(key1 int, ``key2`` int)	void	获得共享会话级别咨询锁
`` pg_advisory_unlock(key`` bigint)	boolean	释 放一个排他会话级别咨询锁
p g_advisory_unlock(key1 int, ``key2`` int)	boolean	释 放一个排他会话级别咨询锁
pg _advisory_unlock_all()	void	释放当前会话 持有的所有会话级别咨询锁
pg_advi sory_unlock_shared(key bigint)	boolean	释 放一个共享会话级别咨询锁
pg_advis ory_unlock_shared(key1 int, ``key2`` int)	boolean	释 放一个共享会话级别咨询锁
pg_ advisory_xact_lock(key bigint)	void	获得排他事务级别咨询锁
pg_a dvisory_xact_lock(key1 int, ``key2`` int)	void	获得排他事务级别咨询锁
pg_advisor y_xact_lock_shared(key bigint)	void	获得共享事务级别咨询锁
pg_advisory _xact_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_ad visory_lock_shared(key bigint)	boolean	如果可能 ，获得共享会话级别咨询锁
pg_try_adv isory_lock_shared(key1 int, ``key2`` int)	boolean	如果可能 ，获得共享会话级别咨询锁
pg_try_ advisory_xact_lock(key bigint)	boolean	如果可能 ，获得排他事务级别咨询锁
pg_try_a dvisory_xact_lock(key1 int, ``key2`` int)	boolean	如果可能 ，获得排他事务级别咨询锁
pg_try_advisor y_xact_lock_shared(key bigint)	boolean	如果可能 ，获得共享事务级别咨询锁
pg_try_advisory _xact_lock_shared(key1 int, ``key2`` int)	boolean	如果可能 ，获得共享事务级别咨询锁

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将释放当前会话所持有的所有会话级别咨询锁（这个函数隐式地在会话末尾被调用，即使客户端已经不雅地断开）。

pg_advisory_xact_lock的工作和pg_advisory_lock相同，不过锁是在当前事务的末尾被自动释放的并且不能被显式释放。

pg_advisory_xact_lock_shared的工作和pg_advisory_lock_shared相同，除了锁是在当前事务的末尾自动被释放的并且不能被显式释放。

pg_try_advisory_xact_lock的工作和pg_try_advisory_lock相同，不过锁（若果获得）是在当前事务的末尾被自动释放的并且不能被显式释放。

pg_try_advisory_xact_lock_shared的工作和pg_try_advisory_lock_shared相同，不过锁（若果获得）是在当前事务的末尾被自动释放的并且不能被显式释放。