PostgreSQL 10.1 手册_部分 II. SQL 语言_第 9 章函数和操作符

9.26. 系统管理函数

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

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

9.26.1. 配置设定函数

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

表 9.77. 配置设定函数

名称	返回类型	描述
`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的设置， current_setting会抛出错误，除非提供 missing_ok并且其值为true。

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.78中展示的函数向其它服务器进程发送控制信号。这些函数的使用通常限制为超级用户，但是可以使用GRANT将访问权限授予其他用户，并注明例外情况。

表 9.78. 服务器信号函数

名称	返回类型	描述
`pg_cancel_backend(pid int)`	`boolean`	取消一个后端的当前查询。如果调用角色是其后端正在被取消的角色的成员，然而只有超级用户可以取消超级用户的后端。这也是允许的。
`pg_reload_conf()`	`boolean`	导致服务器进程重载它们的配置文件
`pg_rotate_logfile()`	`boolean`	切换服务器的日志文件
`pg_terminate_backend(pidint)`	`boolean`	中止一个后端。如果调用角色是其后端被终止的角色成员，然而只有超级用户可以终止超级用户的后端。这也是允许的。

这些函数中的每一个都在成功时返回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.79中展示的函数可以辅助制作在线备份。这些函数不能在恢复期间执行（pg_is_in_backup、pg_backup_start_time和pg_wal_lsn_diff除外）。

表 9.79. 备份控制函数

名称	返回类型	描述
`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`	完成执行排他的在线备份（默认只限于超级用户或者复制角色，但是可以授予其他用户 EXECUTE 特权来执行该函数）
`pg_stop_backup(exclusive boolean [, wait_for_archiveboolean ])`	`setof record`	结束执行排他或者非排他的在线备份（默认只限于超级用户，但是可以授予其他用户 EXECUTE 特权来执行该函数）
`pg_is_in_backup()`	`bool`	如果一个在线排他备份仍在进行中则为真。
`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/目录中有任何链接，表空间映射文件(tablespace_map)到数据库集群的数据目录中，执行一个检查点，然后以文本方式返回备份的起始预写式日志位置。用户可以忽略这个结果值，但是为了可能需要的场合我们还是提供该值。

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.79中其他的函数一起使用来获得复制延迟。

关于正确使用这些函数的细节，请见第 25.3 节。

9.26.4. 恢复控制函数

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

表 9.80. 恢复信息函数

名称	返回类型	描述
`pg_is_in_recovery()`	`bool`	如果恢复仍在进行中，为真。
`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。

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

表 9.81. 恢复控制函数

名称	返回类型	描述
`pg_is_wal_replay_paused()`	`bool`	如果恢复被暂停，为真。
`pg_wal_replay_pause()`	`void`	立即暂停恢复（仅限于超级用户）。
`pg_wal_replay_resume()`	`void`	如果恢复被暂停，重启之（仅限于超级用户）。

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

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

9.26.5. 快照同步函数

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

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

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

表 9.82. 快照同步函数

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

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

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

9.26.6. Replication Functions

表 9.83中显示的函数为了控制和交互复制功能。参阅第 26.2.5 节，第 26.2.6 节以及第 49 章获取基本功能信息。这些函数的使用受制于超级用户。

在复制协议中有许多这些函数的相等命令；参阅第 52.4 节。

第 9.26.5 节，第 9.26.4 节以及第 9.26.3 节中的函数也是与复制有关的。

表 9.83. 复制SQL函数

函数	返回类型	描述
`pg_create_physical_replication_slot(slot_namename [, immediately_reserve boolean, temporary boolean])`	(`slot_name``name`, `lsn``pg_lsn`)	创建一个名为`slot_name`的新物理复制槽。只有用流复制协议才能从一个物理槽流式传送变化 - 见第 52.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_namename, 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，逻辑解码将一直继续到 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_namename, 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_namename, 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_origin_create(node_name text)`	`oid`	创建具有给定外部名称的复制源，并返回分配给它的内部标识。
`pg_replication_origin_drop(node_name text)`	`void`	删除之前创建的复制源，包含任何相关的回放进程。
`pg_replication_origin_oid(node_name text)`	`oid`	通过名称查找复制源并返回内部标识。如果没有发现相应的复制源，则抛出一个错误。
`pg_replication_origin_session_setup(node_nametext)`	`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(flushbool)`	`pg_lsn`	返回当前会话中配置的复制源的重播位置。参数`flush`决定是否相应的本地事务将被刷新到磁盘或者不刷新。
`pg_replication_origin_xact_setup(origin_lsnpg_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_nametext, 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. 数据库对象管理函数

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

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

名称	返回类型	描述
`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 空间、空闲空间映射和可见性映射包含在内）

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'返回与该关系相关的空闲空间映射（见第 66.3 节）的尺寸。
'vm'返回与该关系相关的可见性映射（见第 66.4 节）的尺寸。
'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.85 中展示的函数帮助标识数据库对象相关的磁盘文件。

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

名称	返回类型	描述
`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”号。文件结点是关系的文件名的基本组件（详见第 66.1 节）。对于大多数表结果和pg_class.relfilenode相同，但是对于某些系统目录relfilenode为零，并且必须使用此函数获取正确的值。如果传递一个没有存储的关系（如视图），此函数将返回 NULL。

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

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

表 9.86列出了用于管理排序规则的函数。

表 9.86. 排序规则管理函数

名称	返回类型	描述
`pg_collation_actual_version(oid)`	`text`	返回操作系统的排序规则的实际版本
`pg_import_system_collations(schema regnamespace)`	`integer`	导入操作系统排序规则

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

pg_import_system_collations基于它在操作系统中找到的所有语言环境，将排序规则添加到系统目录pg_collation。这是initdb使用的内容；有关更多详细信息，请参阅第 23.2.2 节。如果稍后将其他语言环境安装到操作系统中，则可以再次运行此函数以添加新语言环境的排序规则。匹配pg_collation 中现有条目的语言环境将被跳过。（但是，基于不再存在于操作系统中的语言环境的排序规则对象不会被此函数删除。） schema参数通常是pg_catalog，但这不是必需的；排序规则也可以安装到其他模式中。该函数返回它创建的新排序规则对象的数量。

9.26.8. 索引维护函数

表 9.87显示可用于索引维护功能的函数。

表 9.87. Index Maintenance Functions

名称	返回类型	描述
`brin_summarize_new_values(index_oid 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接收BRIN索引OID作为参数，并检查索引以查找基表中的页范围，它不是目前所总结的索引；对于任何这样的范围，它通过扫描表页创建一个新的汇总索引元组。它返回插入索引的新页范围汇总的数量。 brin_summarize_range完成相同的操作，只是它只总结覆盖给定块编号的范围。

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

9.26.9. 通用文件访问函数

表 9.88中展示的函数提供了对数据库服务器所在机器上的文件的本地访问。只有那些在数据库集簇目录和log_directory目录中的文件可以访问。使用相对路径访问集簇目录里面的文件，以及匹配 log_directory配置设置的路径访问日志文件。除非另有说明，否则只有超级用户才能使用这些函数。

表 9.88. 通用文件访问函数

名称	返回类型	描述
`pg_ls_dir(dirname text [, missing_ok boolean, include_dot_dirsboolean])`	`setof text`	列出目录内容。
`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`	返回文本文件的内容。
`pg_read_binary_file(filename text [, offset bigint, length bigint[, missing_ok boolean] ])`	`bytea`	返回一个文件的内容。
`pg_stat_file(filename text[, missing_ok boolean])`	`record`	返回文件信息。

其中一些函数接受可选的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. 咨询锁函数

表 9.89中展示的函数管理咨询锁。有关正确使用这些函数的细节请参考第 13.3.5 节。

表 9.89. 咨询锁函数

名称	返回类型	描述
`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`	获得排他事务级别咨询锁
`pg_advisory_xact_lock(key1 int, key2 int)`	`void`	获得排他事务级别咨询锁
`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`	如果可能，获得排他事务级别咨询锁
`pg_try_advisory_xact_lock(key1 int, key2 int)`	`boolean`	如果可能，获得排他事务级别咨询锁
`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位键值标识（注意这些两个键空间不重叠）。如果另一个会话已经在同一个资源标识符上持有了一个锁，这个函数将等待直到该资源变成可用。该锁是排他的。多个锁请求会入栈，因此如果同一个资源被锁住三次，则它必须被解锁三次来被释放给其他会话使用。

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相同，不过锁（若果获得）是在当前事务的末尾被自动释放的并且不能被显式释放。

本文转自PostgreSQL中文社区，原文链接：9.26. 系统管理函数