9.26. 系统 Management 功能

本节中描述的功能用于控制和监视 PostgreSQL 安装。

9 .26.1. 配置设置功能

Table 9.77显示了可用于查询和更改运行时配置参数的功能。

表 9.77. 配置设置功能

Name	Return Type	Description
`current_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，则新值仅适用于当前 Transaction。如果希望新值适用于当前会话，请使用false。该函数对应于 SQL 命令SET。一个例子：

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

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

9 0.26.2. 服务器信令功能

Table 9.78中显示的功能将控制 signal 发送到其他服务器进程。默认情况下，仅限超级用户使用这些功能，但可以使用GRANT授予其他人访问权限，但有 exception。

表 9.78. 服务器信令功能

Name	Return Type	Description
`pg_cancel_backend(pid int)`	`boolean`	取消后端的当前查询。如果调用角色是其后端被取消的角色的成员或已授予调用角色`pg_signal_backend`的角色，则也允许这样做，但是只有超级用户才能取消超级用户后端。
`pg_reload_conf()`	`boolean`	使服务器进程重新加载其配置文件
`pg_rotate_logfile()`	`boolean`	旋转服务器的日志文件
`pg_terminate_backend(pid int)`	`boolean`	终止后端。如果调用者角色是其后端要终止的角色的成员或已授予调用者角色`pg_signal_backend`，则也允许这样做，但是只有超级用户才能终止超级用户后端。

如果成功，每个函数都将返回true，否则返回false。

pg_cancel_backend和pg_terminate_backend发送 signal(分别为 SIGINT 或 SIGTERM)到由进程 ID 标识的后端进程。可以从pg_stat_activity视图的pid列中找到活动后端的进程 ID，也可以在服务器上列出postgres进程(在 Unix 上使用 ps 或在 Windows 上使用任务 Management 器)找到。活动后端的角色可以在pg_stat_activity视图的usename列中找到。

pg_reload_conf向服务器发送 SIGHUPsignal，导致所有服务器进程重新加载配置文件。

pg_rotate_logfile指示日志文件 Management 器立即切换到新的输出文件。仅当内置日志收集器正在运行时，此方法才起作用，因为否则，将没有日志文件 Management 器子进程。

9 0.26.3. 备份控制功能

Table 9.79中显示的功能有助于进行在线备份。这些功能无法在恢复期间执行(非专有pg_start_backup，非专有pg_stop_backup，pg_is_in_backup，pg_backup_start_time和pg_wal_lsn_diff除外)。

表 9.79. 备份控制功能

Name	Return Type	Description
`pg_create_restore_point(name text)`	`pg_lsn`	创建用于执行还原的命名点(默认情况下仅限于超级用户，但可以授予其他用户执行该功能的权限)
`pg_current_wal_flush_lsn()`	`pg_lsn`	获取当前的预写日志刷新位置
`pg_current_wal_insert_lsn()`	`pg_lsn`	获取当前的预写日志插入位置
`pg_current_wal_lsn()`	`pg_lsn`	获取当前的预写日志写入位置
`pg_start_backup(label text [, fast boolean [, exclusive boolean ]])`	`pg_lsn`	准备执行在线备份(默认情况下仅限于超级用户，但可以授予其他用户执行该功能的权限)
`pg_stop_backup()`	`pg_lsn`	完成独家在线备份的执行(默认情况下仅限超级用户，但可以授予其他用户执行该功能的权限)
`pg_stop_backup(exclusive boolean [, wait_for_archive boolean ])`	`setof record`	完成执行独占或非独占的在线备份(默认情况下仅限于超级用户，但可以授予其他用户执行该功能的权限)
`pg_is_in_backup()`	`bool`	如果在线独占备份仍在进行中，则为 true。
`pg_backup_start_time()`	`timestamp with time zone`	获取正在进行的在线独占备份的开始时间。
`pg_switch_wal()`	`pg_lsn`	强制切换到新的预写日志文件(默认情况下限制为超级用户，但可以授予其他用户执行该功能的权限)
`pg_walfile_name(lsn pg_lsn)`	`text`	将预写日志位置转换为文件名
`pg_walfile_name_offset(lsn pg_lsn)`	`text` , `integer`	将预写日志位置转换为文件名和文件中的十进制字节偏移量
`pg_wal_lsn_diff(lsn pg_lsn, lsn pg_lsn)`	`numeric`	计算两个预写日志位置之间的差异

pg_start_backup接受用于备份的任意用户定义标签。 (通常这将是备份转储文件的存储名称.)在独占模式下使用时，该函数将写入备份标签文件(backup_label)，并且如果pg_tblspc/目录中有任何链接，则将写入表空间 Map 文件。 (tablespace_map)进入数据库集群的数据目录，执行检查点，然后以文本形式返回备份的起始预写日志位置。用户可以忽略此结果值，但在有用时会提供它。在非独占模式下使用时，这些文件的内容由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类型的第二个参数。如果为 false，则pg_stop_backup将在备份完成后立即返回，而无需 awaitWAL 被存档。此行为仅对独立监视 WAL 归档的备份软件有用。否则，可能缺少使备份保持一致所需的 WAL，并使备份无用。当此参数设置为 true 时，pg_stop_backup将在启用归档后 awaitWAL 归档；在备用数据库上，这意味着它将仅在archive_mode = always时 await。如果主节点上的写入活动较少，则在主节点上运行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仅提取预写日志文件名。当给定的预写日志位置恰好在预写日志文件边界时，这两个函数都将返回先前的预写日志文件的名称。这通常是 Management 预写日志归档行为的理想行为，因为前一个文件是当前需要归档的最后一个文件。

pg_wal_lsn_diff计算两个预写日志位置之间的字节差。它可以与pg_stat_replication或Table 9.79中显示的某些功能一起使用，以获取复制滞后。

有关正确使用这些功能的详细信息，请参见Section 25.3。

9 .26.4. 恢复控制功能

Table 9.80中显示的功能提供有关备用设备当前状态的信息。这些功能可以在恢复期间和正常运行中执行。

表 9.80. 恢复信息功能

Name	Return Type	Description
`pg_is_in_recovery()`	`bool`	如果恢复仍在进行，则为 true。
`pg_last_wal_receive_lsn()`	`pg_lsn`	获取接收的最后一个预写日志位置并通过流复制同步到磁盘。在进行流复制时，这将单调增加。如果恢复完成，则恢复时将保持在接收到并同步到磁盘的最后一个 WAL 记录的值不变。如果禁用流复制，或者尚未开始，则该函数返回 NULL。
`pg_last_wal_replay_lsn()`	`pg_lsn`	获取恢复期间重播的最后一个预写日志位置。如果恢复仍在进行中，它将单调增加。如果恢复完成，则该值将保持该恢复期间应用的最后一个 WAL 记录的值不变。当服务器正常启动但没有恢复时，该函数返回 NULL。
`pg_last_xact_replay_timestamp()`	`timestamp with time zone`	获取恢复期间上次重播的事务的时间戳。这是在主数据库上生成该事务的提交或中止 WAL 记录的时间。如果恢复期间没有重播任何事务，则此函数返回 NULL。否则，如果恢复仍在进行中，它将单调增加。如果恢复已完成，则该值将保持为该恢复期间应用的最后一个事务的值不变。当服务器正常启动但没有恢复时，该函数返回 NULL。

Table 9.81中显示的功能控制恢复进度。这些功能只能在恢复期间执行。

表 9.81. 恢复控制功能

Name	Return Type	Description
`pg_is_wal_replay_paused()`	`bool`	如果恢复暂停，则为 True。
`pg_wal_replay_pause()`	`void`	立即暂停恢复(默认情况下仅限超级用户，但可以授予其他用户 EXECUTE 运行该功能)。
`pg_wal_replay_resume()`	`void`	如果暂停，则重新开始恢复(默认情况下限制为超级用户，但可以授予其他用户 EXECUTE 运行该功能)。

恢复暂停时，不再应用任何数据库更改。如果处于热备用状态，则所有新查询将看到数据库的相同一致快照，并且在恢复恢复之前不会产生其他查询冲突。

如果禁用了流复制，则暂停状态可能会无限期 continue 而不会出现问题。在进行流复制时，将 continue 接收 WAL 记录，这将最终填充可用的磁盘空间，具体取决于暂停的持续时间，WAL 生成的速率和可用的磁盘空间。

9 .26.5. 快照同步功能

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

为了解决此问题，PostgreSQL 允许事务“导出”它正在使用的快照。只要导出的事务保持打开状态，其他事务就可以“导入”其快照，从而保证它们看到的数据库视图与第一个事务所看到的完全相同。但是请注意，由这些事务中的任何一个进行的任何数据库更改对于其他事务都是不可见的，这与未提交的事务进行的更改一样。因此，事务相对于预先存在的数据是同步的，但对于它们自己进行的更改通常会采取行动。

快照使用pg_export_snapshot功能导出，如Table 9.82所示，并使用SET TRANSACTION命令导入。

表 9.82. 快照同步功能

Name	Return Type	Description
`pg_export_snapshot()`	`text`	保存当前快照并返回其标识符

函数pg_export_snapshot保存当前快照，并返回标识快照的text字符串。此字符串必须(在数据库外部)传递给要导入快照的 Client 端。快照仅可用于导入，直到导出快照的事务结束为止。如果需要，一个事务可以导出多个快照。请注意，这样做仅在READ COMMITTED事务中有用，因为在REPEATABLE READ和更高的隔离级别中，事务在整个生命周期中都使用相同的快照。事务导出任何快照后，就无法使用PREPARE TRANSACTION进行准备。

有关如何使用导出的快照的详细信息，请参见SET TRANSACTION。

9 .26.6. 复制功能

Table 9.83中显示的功能用于控制复制功能并与之交互。有关基础功能的信息，请参见Section 26.2.5，Section 26.2.6和Chapter 50。复制源的功能使用仅限于超级用户。复制插槽功能的使用仅限于超级用户和具有REPLICATION特权的用户。

这些功能中的许多功能在复制协议中具有等效的命令。参见Section 53.4。

Section 9.26.3，Section 9.26.4和Section 9.26.5中描述的功能也与复制有关。

表 9.83. 复制 SQL 函数

Function	Return Type	Description
`pg_create_physical_replication_slot(slot_name name [, immediately_reserve boolean, temporary boolean])`	( `slot_name` `name` , `lsn` `pg_lsn` )	创建一个名为* `slot_name` 的新物理复制插槽。可选的第二个参数`true`时，指定立即为此复制插槽的 LSN 保留；否则，将在流复制 Client 端的第一次连接上保留 LSN。只有使用流复制协议才能从物理插槽进行流更改(请参阅Section 53.4)。可选的第三个参数 `temporary` *设置为 true 时，指定该插槽不应永久存储到磁盘，而只能供当前会话使用。发生任何错误时也会释放临时插槽。此功能对应于复制协议命令`CREATE_REPLICATION_SLOT ... PHYSICAL`。
`pg_drop_replication_slot(slot_name name)`	`void`	删除名为* `slot_name` *的物理或逻辑复制插槽。与复制协议命令`DROP_REPLICATION_SLOT`相同。对于逻辑插槽，当连接到创建插槽的同一数据库时，必须调用该逻辑插槽。
`pg_create_logical_replication_slot(slot_name name, plugin name [, temporary boolean])`	( `slot_name` `name` , `lsn` `pg_lsn` )	使用输出插件* `plugin` 创建一个名为 `slot_name` 的新逻辑(解码)复制插槽。可选的第三个参数 `temporary` *设置为 true 时，指定该插槽不应永久存储到磁盘，而只能用于当前会话。发生任何错误时也会释放临时插槽。对该函数的调用与复制协议命令`CREATE_REPLICATION_SLOT ... LOGICAL`具有相同的效果。
`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，则逻辑解码将 continue 直到 WAL 结束。如果 `upto_lsn` 为非 NULL，则解码将仅包括那些在指定 LSN 之前提交的事务。如果 `upto_nchanges` *为非 NULL，则当解码产生的行数超过指定值时，解码将停止。但是请注意，返回的实际行数可能会更大，因为仅在添加对每个新事务提交进行解码时生成的行之后才检查此限制。
`pg_logical_slot_peek_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[])`	( `lsn` `pg_lsn` , `xid` `xid` , `data` `text` )	行为与`pg_logical_slot_get_changes()`函数类似，但不消耗更改；也就是说，它们将在以后的通话中再次返回。
`pg_logical_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_logical_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_origin_create(node_name text)`	`oid`	使用给定的外部名称创建复制源，然后返回分配给它的内部 ID。
`pg_replication_origin_drop(node_name text)`	`void`	删除以前创建的复制源，包括任何关联的重播进度。
`pg_replication_origin_oid(node_name text)`	`oid`	按名称查找复制源，然后返回内部 ID。如果未找到相应的复制源，则会引发错误。
`pg_replication_origin_session_setup(node_name text)`	`void`	将当前会话标记为从给定的源进行重播，从而可以跟踪重播进度。使用`pg_replication_origin_session_reset`还原。仅当未配置先前的来源时才可以使用。
`pg_replication_origin_session_reset()`	`void`	取消`pg_replication_origin_session_setup()`的效果。
`pg_replication_origin_session_is_setup()`	`bool`	在当前会话中是否已配置复制源？
`pg_replication_origin_session_progress(flush bool)`	`pg_lsn`	返回当前会话中配置的复制源的重播位置。参数* `flush` *确定是否将保证相应的本地事务已被刷新到磁盘。
`pg_replication_origin_xact_setup(origin_lsn pg_lsn, origin_timestamp timestamptz)`	`void`	将当前事务标记为重播已在给定 LSN 和时间戳下提交的事务。仅当先前使用`pg_replication_origin_session_setup()`配置复制源时才可以调用。
`pg_replication_origin_xact_reset()`	`void`	取消`pg_replication_origin_xact_setup()`的效果。
`pg_replication_origin_advance(node_name text, lsn pg_lsn)`	`void`	将给定节点的复制进度设置到给定位置。这主要用于在配置更改等之后设置初始位置或新位置。请注意，不小心使用此功能会导致不一致的复制数据。
`pg_replication_origin_progress(node_name text, flush bool)`	`pg_lsn`	返回给定复制源的重播位置。参数* `flush` *确定是否将保证相应的本地事务已被刷新到磁盘。
`pg_logical_emit_message(transactional bool, prefix text, content text)`	`pg_lsn`	发出文本逻辑解码消息。这可以用于通过 WAL 将通用消息传递到逻辑解码插件。参数* `transactional` 指定消息是当前事务的一部分，还是应立即写入并在逻辑解码读取记录后立即对其进行解码。 `prefix` 是逻辑解码插件用来轻松识别有趣消息的文本前缀。 `content` *是消息的文本。
`pg_logical_emit_message(transactional bool, prefix text, content bytea)`	`pg_lsn`	发出二进制逻辑解码消息。这可以用于通过 WAL 将通用消息传递到逻辑解码插件。参数* `transactional` 指定消息是当前事务的一部分，还是应立即写入并在逻辑解码读取记录后立即对其进行解码。 `prefix` 是逻辑解码插件用来轻松识别有趣消息的文本前缀。 `content` *是消息的二进制内容。

9 .26.7. 数据库对象 Management 功能

Table 9.84中显示的函数计算数据库对象的磁盘空间使用率。

表 9.84. 数据库对象大小函数

Name	Return Type	Description
`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 的表空间使用的磁盘空间
`pg_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 空间，自由空间 Map 和可见性 Map.)

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接受表，索引或烤面包表的 OID 或名称，并返回该关系的一个分支的磁盘大小(以字节为单位)。 (请注意，在大多数情况下，使用更高级别的函数pg_total_relation_size或pg_table_size会更方便，这些函数求和所有派生的大小.)使用一个参数，它返回关系的主数据派生的大小。可以提供第二个参数来指定要检查的派生：

'main'返回关系的主数据分支的大小。
'fsm'返回与该关系关联的可用空间图的大小(请参见Section 68.3)。
'vm'返回与该关系关联的“可见性 Map”(请参见Section 68.4)的大小。
'init'返回与该关系关联的初始化分支的大小(如果有)。

pg_size_pretty可用于以易于理解的方式格式化其他功能之一的结果，并适当地使用字节，kB，MB，GB 或 TB。

pg_size_bytes可用于以易于理解的格式从字符串中获取字节大小。Importing 可能具有字节单位 kB，MB，GB 或 TB，并且不区分大小写地进行解析。如果未指定单位，则假定为字节。

Note

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

以上对表或索引进行操作的函数接受regclass参数，该参数只是pg_class系统目录中表或索引的 OID。但是，您不必手工查找 OID，因为regclass数据类型的 Importing 转换器将为您完成工作。只需将表名写在单引号中，使它看起来像 Literals 常量。为了与普通 SQL 名称的处理兼容，该字符串将转换为小写，除非该字符串在表名周围包含双引号。

如果将不代表现有对象的 OID 作为参数传递给上述函数之一，则返回 NULL。

Table 9.85中显示的功能有助于识别与数据库对象关联的特定磁盘文件。

表 9.85. 数据库对象定位功能

Name	Return Type	Description
`pg_relation_filenode(relation regclass)`	`oid`	指定关系的文件节点号
`pg_relation_filepath(relation regclass)`	`text`	指定关系的文件路径名
`pg_filenode_relation(tablespace oid, filenode oid)`	`regclass`	查找与给定表空间和文件节点关联的关系

pg_relation_filenode接受表，索引，序列或 Toast 表的 OID 或名称，并返回当前为其分配的“文件节点”号。 filenode 是用于该关系的文件名的基本组成部分(有关更多信息，请参见Section 68.1)。对于大多数表，结果与pg_class相同。 relfilenode，但对于某些系统目录，relfilenode为零，必须使用此函数来获取正确的值。如果传递了没有存储的关系(例如视图)，则该函数将返回 NULL。

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

pg_filenode_relation与pg_relation_filenode相反。给定一个“表空间” OID 和一个“文件节点”，它将返回关联关系的 OID。对于数据库默认表空间中的表，可以将表空间指定为 0.

Table 9.86列出了用于 Management 归类的功能。

表 9.86. 整理 Management 功能

Name	Return Type	Description
`pg_collation_actual_version(oid)`	`text`	从 os 返回排序规则的实际版本
`pg_import_system_collations(schema regnamespace)`	`integer`	导入 os 归类

pg_collation_actual_version返回归类对象的实际版本，因为该对象当前已安装在 os 中。如果这与pg_collation.collversion中的值不同，则可能需要重建取决于排序规则的对象。另请参见ALTER COLLATION。

pg_import_system_collations根据在 os 中找到的所有语言环境，将归类添加到系统目录pg_collation中。这就是initdb的用途；有关更多详细信息，请参见Section 23.2.2。如果稍后在 os 中安装了其他语言环境，则可以再次运行此功能以为新的语言环境添加排序规则。与pg_collation中的现有条目匹配的语言环境将被跳过。 (但是该函数不会删除基于 os 中不再存在的语言环境的整理对象.)* schema *参数通常为pg_catalog，但这不是必需的；排序规则也可以安装到其他模式中。该函数返回其创建的新排序规则对象的数量。

9 .26.8. 索引维护功能

Table 9.87显示了可用于索引维护任务的功能。恢复期间无法执行这些功能。这些功能的使用仅限于超级用户和给定索引的所有者。

表 9.87. 索引维护功能

Name	Return Type	Description
`brin_summarize_new_values(index regclass)`	`integer`	汇总尚未汇总的页面范围
`brin_summarize_range(index regclass, blockNumber bigint)`	`integer`	总结覆盖给定块的页面范围(如果尚未总结)
`brin_desummarize_range(index regclass, blockNumber bigint)`	`integer`	如果汇总，则取消汇总覆盖给定块的页面范围
`gin_clean_pending_list(index regclass)`	`bigint`	将 GIN 待处理列表条目移入主索引结构

brin_summarize_new_values接受 OID 或 BRIN 索引的名称，并检查索引以查找基表中当前未被索引汇总的页面范围；对于任何这样的范围，它将通过扫描表页面来创建新的摘要索引 Tuples。它返回插入到索引中的新页面范围摘要的数量。 brin_summarize_range的作用相同，只是它只汇总了覆盖给定块号的范围。

gin_clean_pending_list接受 OID 或 GIN 索引的名称，并通过将指定索引的条目批量移动到主要 GIN 数据结构中来清除指定索引的待处理列表。它返回从挂起列表中删除的页面数。请注意，如果该参数是在禁用fastupdate选项的情况下构建的 GIN 索引，则不会进行清理，并且返回值为 0，因为该索引没有待处理列表。有关待处理列表和fastupdate选项的详细信息，请参见Section 66.4.1和Section 66.5。

9 .26.9. 通用文件访问功能

Table 9.88中显示的功能提供对托管服务器的计算机上文件的本地访问。除非授予用户角色pg_read_server_files，否则只能访问数据库集群目录和log_directory中的文件。为群集目录中的文件使用相对路径，为日志文件使用与log_directory配置设置匹配的路径。

请注意，授予用户pg_read_file()的 EXECUTE 特权或相关功能，使他们能够读取服务器上数据库可以读取的任何文件，并且这些读取会绕过所有数据库内特权检查。这意味着，除其他事项外，具有此访问权限的用户能够读取包含认证信息的pg_authid表的内容，以及读取数据库中的任何文件。因此，应仔细考虑授予访问这些功能的权限。

表 9.88. 通用文件访问功能

Name	Return Type	Description
`pg_ls_dir(dirname text [, missing_ok boolean, include_dot_dirs boolean])`	`setof text`	列出目录的内容。默认情况下限制为超级用户，但是可以授予其他用户 EXECUTE 运行该功能。
`pg_ls_logdir()`	`setof record`	在日志目录中列出文件的名称，大小和最后修改时间。授予`pg_monitor`角色的成员访问权限，也可以授予其他非超级用户角色的访问权限。
`pg_ls_waldir()`	`setof record`	列出 WAL 目录中文件的名称，大小和最后修改时间。授予`pg_monitor`角色的成员访问权限，也可以授予其他非超级用户角色的访问权限。
`pg_read_file(filename text [, offset bigint, length bigint [, missing_ok boolean] ])`	`text`	返回文本文件的内容。默认情况下限制为超级用户，但是可以授予其他用户 EXECUTE 运行该功能。
`pg_read_binary_file(filename text [, offset bigint, length bigint [, missing_ok boolean] ])`	`bytea`	返回文件的内容。默认情况下限制为超级用户，但是可以授予其他用户 EXECUTE 运行该功能。
`pg_stat_file(filename text[, missing_ok boolean])`	`record`	返回有关文件的信息。默认情况下限制为超级用户，但是可以授予其他用户 EXECUTE 运行该功能。

其中一些函数带有可选的* 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_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. 咨询锁功能

Table 9.89中显示的功能 Management 咨询锁。有关正确使用这些功能的详细信息，请参见Section 13.3.5。

表 9.89. 咨询锁功能

Name	Return Type	Description
`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_advisory_unlock(key bigint)`	`boolean`	释放专用的会话级咨询锁
`pg_advisory_unlock(key1 int, key2 int)`	`boolean`	释放专用的会话级咨询锁
`pg_advisory_unlock_all()`	`void`	释放当前会话持有的所有会话级别的咨询锁
`pg_advisory_unlock_shared(key bigint)`	`boolean`	释放共享的会话级别咨询锁
`pg_advisory_unlock_shared(key1 int, key2 int)`	`boolean`	释放共享的会话级别咨询锁
`pg_advisory_xact_lock(key bigint)`	`void`	获得排他 Transaction 级别的咨询锁
`pg_advisory_xact_lock(key1 int, key2 int)`	`void`	获得排他 Transaction 级别的咨询锁
`pg_advisory_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_advisory_lock_shared(key bigint)`	`boolean`	获取共享的会话级别咨询锁(如果有)
`pg_try_advisory_lock_shared(key1 int, key2 int)`	`boolean`	获取共享的会话级别咨询锁(如果有)
`pg_try_advisory_xact_lock(key bigint)`	`boolean`	获得独家 Transaction 级别的咨询锁(如果有)
`pg_try_advisory_xact_lock(key1 int, key2 int)`	`boolean`	获得独家 Transaction 级别的咨询锁(如果有)
`pg_try_advisory_xact_lock_shared(key bigint)`	`boolean`	获取共享事务级别咨询锁(如果有)
`pg_try_advisory_xact_lock_shared(key1 int, key2 int)`	`boolean`	获取共享事务级别咨询锁(如果有)

pg_advisory_lock锁定应用程序定义的资源，该资源可以由单个 64 位键值或两个 32 位键值标识(请注意，这两个键空间不重叠)。如果另一个会话已经在同一资源标识符上持有锁，则此功能将 await，直到资源可用为止。锁是排他的。多个锁定请求会堆叠在一起，因此，如果同一资源被锁定三次，则必须将其解锁三次才能释放以供其他会话使用。

pg_advisory_lock_shared与pg_advisory_lock的工作原理相同，除了可以与其他请求共享锁的会话共享该锁。只有可能的专用储物柜被锁定。

pg_try_advisory_lock与pg_advisory_lock类似，不同之处在于该功能将不 await 锁变为可用。它将立即获得锁并返回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将释放当前会话持有的所有会话级别的咨询锁。 (即使 Client 端不正常断开连接，该函数也会在会话结束时隐式调用.)

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相同，不同之处在于，锁(如果已获取)将在当前事务结束时自动释放，并且无法显式释放。

Name	PostgreSQL 中文文档
Version
Language
Badge
Last Updated	2021-07-07T13:04:41