这一节描述的函数被用来控制和监视一个PostgreSQL安装。
Table 9.89展示了那些可以用于查询以及修改运行时配置参数的函数。
Table 9.89. 配置设定函数
|
函数 描述 示例 |
|---|
|
返回设置的
|
|
将参数
|
在Table 9.90中展示的函数向其它服务器进程发送控制信号。默认情况下这些函数只能被超级用户使用，但是如果需要，可以利用GRANT把访问权限授予给其他用户。
每个这样的函数如果信号成功发出则返回true，如果发送信号失败则返回false。
Table 9.90. 服务器信号函数
|
函数 描述 |
|---|
|
取消具有指定进程ID的后端进程的会话的当前查询。如果调用角色是被取消的后端进程所属角色的成员， 或者调用角色具有 |
|
请求记录具有指定进程ID的后端的内存上下文。此函数可以将请求发送到后端和辅助进程，但不包括记录器。这些内存上下文将以 |
|
使PostgreSQL服务器的所有进程重新加载其配置文件。 （这是通过向postmaster进程发送SIGHUP信号来启动的， postmaster进程又向其每个子进程发送SIGHUP。） 您可以使用 |
|
通知日志文件管理器立即切换到一个新的输出文件。 这仅在内置日志收集器运行时有效，因为否则没有日志文件管理器子进程。 |
|
终止具有指定进程ID的后端进程的会话。如果调用角色是正在终止的后端的角色的成员，或者调用角色具有 如果未指定或超时 |
pg_cancel_backend和pg_terminate_backend向由进程 ID 标识的后端进程发送信号（分别是SIGINT或SIGTERM）。 一个活动后端的进程 ID可以从pg_stat_activity视图的pid列中找到，或者通过在服务器上列出postgres进程（在 Unix 上使用ps或者在Windows上使用任务管理器）得到。 一个活动后端的角色可以在pg_stat_activity视图的usename列中找到。
pg_log_backend_memory_contexts可以用来记录后端进程的内存上下文。例如：
postgres=# SELECT pg_log_backend_memory_contexts(pg_backend_pid()); pg_log_backend_memory_contexts -------------------------------- t (1 row)
每个内存上下文将被记录一条消息。例如：
LOG: logging memory contexts of PID 10377 STATEMENT: SELECT pg_log_backend_memory_contexts(pg_backend_pid()); LOG: level: 0; TopMemoryContext: 80800 total in 6 blocks; 14432 free (5 chunks); 66368 used LOG: level: 1; pgstat TabStatusArray lookup hash table: 8192 total in 1 blocks; 1408 free (0 chunks); 6784 used LOG: level: 1; TopTransactionContext: 8192 total in 1 blocks; 7720 free (1 chunks); 472 used LOG: level: 1; RowDescriptionContext: 8192 total in 1 blocks; 6880 free (0 chunks); 1312 used LOG: level: 1; MessageContext: 16384 total in 2 blocks; 5152 free (0 chunks); 11232 used LOG: level: 1; Operator class cache: 8192 total in 1 blocks; 512 free (0 chunks); 7680 used LOG: level: 1; smgr relation table: 16384 total in 2 blocks; 4544 free (3 chunks); 11840 used LOG: level: 1; TransactionAbortContext: 32768 total in 1 blocks; 32504 free (0 chunks); 264 used ... LOG: level: 1; ErrorContext: 8192 total in 1 blocks; 7928 free (3 chunks); 264 used LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560 used
如果在同一父级下有超过100个子上下文，则将记录前100个子上下文，并附上其余上下文的摘要。 请注意，频繁调用此函数可能会产生显著的开销，因为它可能会生成大量的日志消息。
在Table 9.91中显示的函数有助于进行在线备份。 这些函数在恢复过程中无法执行（除了pg_backup_start、 pg_backup_stop和pg_wal_lsn_diff）。
有关正确使用这些函数的详细信息，参见Section 25.3。
Table 9.91. 备份控制函数
|
函数 描述 |
|---|
|
在预写式日志中创建一个命名标记记录，稍后可以将其用作恢复目标，并返回相应的预写日志位置。 然后可以将给定的名称与 recovery_target_name一起使用，以指定进行恢复的点。 要避免创建多个名称相同的恢复点，因为恢复将在第一个名称与恢复目标匹配的恢复点停止。 默认情况下，该函数仅限超级用户使用，但可以授权给其他用户执行该函数。 |
|
返回当前预写式日志刷新位置(参见下面的说明)。 |
|
返回当前预式日志插入位置(参见下面的说明)。 |
|
返回当前预写式日志写位置(参见下面的说明)。 |
|
准备服务器开始在线备份。唯一必需的参数是备份的任意用户定义标签。 （通常这将是备份转储文件存储的名称。） 如果将可选的第二个参数指定为 默认情况下，此函数仅限于超级用户，但可以授予其他用户执行权限以运行该函数。 |
|
完成在线备份。函数的结果中返回备份标签文件和表空间映射文件的期望内容，并必须写入备份区域的文件中。 这些文件不得写入实时数据目录（这样做将导致PostgreSQL在崩溃时无法重新启动）。 有一个类型为 在主机上执行时，此函数还会在预写式日志归档区域中创建一个备份历史文件。 历史文件包括给定给 函数的结果是一个记录。 默认情况下，此函数仅限于超级用户，但可以授予其他用户EXECUTE权限来运行该函数。 |
|
强制服务器切换到一个新的预写式日志文件，这允许对当前文件进行归档(假设你正在使用连续归档)。 其结果是在刚刚完成的预写式日志文件中结束预写式日志位置加1。 如果自从上次预写式日志切换以来没有提前写日志活动， 默认情况下该函数仅限超级用户使用，但可以授权其他用户执行该函数。 |
|
将预写式日志位置转换为保持该位置的WAL文件的名称。 |
|
将预写式日志位置转换为WAL文件名和该文件中的字节偏移量。 |
|
计算两个预写式日志位置之间的字节( |
pg_current_wal_lsn 显示当前预写式日志写位置，与上述函数所用的格式相同。 类似地，pg_current_wal_insert_lsn显示当前预写式日志插入位置，pg_current_wal_flush_lsn显示当前预写式日志刷新位置。 插入位置是预写式日志在任何时刻的“逻辑(logical)” 结束，而写位置是已经从服务器内部缓冲区实际写入的内容的结束，而刷新位置是已知的要写入持久化存储的最后一个位置。 写位置是可以从服务器外部检查的最后位置，如果你对归档部分完成的预写式日志文件感兴趣，那么它通常就是你想要的位置。 插入和刷新位置主要用于服务器调试目的。这些都是只读操作，不需要超级用户权限。
您可以使用pg_walfile_name_offset从pg_lsn值中提取相应的预写式日志文件名和字节偏移量。例如：
postgres=# SELECT * FROM pg_walfile_name_offset((pg_backup_stop()).lsn);
file_name | file_offset
--------------------------+-------------
00000001000000000000000D | 4039624
(1 row)
类似地，pg_walfile_name仅提取预写式日志文件名。 当给定的预写式日志位置恰好位于预写式日志文件边界时，这两个函数都会返回前一个预写式日志文件的名称。 这通常是管理预写式日志归档行为的期望行为，因为前一个文件是当前需要归档的最后一个文件。
Table 9.92中展示的函数提供有关备库当前状态的信息。 这些函数可以在恢复或普通运行过程中被执行。
Table 9.92. 恢复信息函数
控制恢复进度的功能如 Table 9.93所示。这些函数只能在恢复过程中执行。
Table 9.93. 恢复控制函数
pg_wal_replay_pause和pg_wal_replay_resume不能在提升(promotion)进行时执行。 如果在恢复暂停时触发了提升(promotion)，则暂停状态结束，升级继续进行。
如果禁用了流复制，则暂停状态可能会无限期地持续下去，不会出现问题。 如果正在进行流复制，那么将继续接收WAL记录，这将最终填满可用磁盘空间，这取决于暂停持续时间、WAL生成速度和可用磁盘空间。
PostgreSQL允许数据库会话同步它们的快照。一个快照决定对于正在使用该快照的事务哪些数据是可见的。当两个或者更多个会话需要看到数据库中的相同内容时，就需要同步快照。如果两个会话独立开始其事务，就总是有可能有某个第三事务在两个START TRANSACTION命令的执行之间提交，这样其中一个会话就可以看到该事务的效果而另一个则看不到。
为了解决这个问题，PostgreSQL允许一个事务导出它正在使用的快照。只要导出的事务仍然保持打开，其他事务可以导入它的快照，并且因此可以保证它们可以看到和第一个事务看到的完全一样的数据库视图。但是注意这些事务中的任何一个对数据库所作的更改对其他事务仍然保持不可见，和未提交事务所作的修改一样。因此这些事务是针对以前存在的数据同步，而对由它们自己所作的更改则采取正常的动作。
如Table 9.94中所示，快照通过pg_export_snapshot函数导出，并且通过SET TRANSACTION命令导入。
Table 9.94. 快照同步函数
|
函数 描述 |
|---|
|
保存事务的当前快照并返回 如果需要的话，一个事务可以导出多个快照。 请注意，这样做仅在 |
Table 9.95中展示的函数用于控制以及与复制特性交互。 有关底层特性的信息请见Section 26.2.5、Section 26.2.6以及Chapter 48。 复制原点函数的使用仅限于超级用户。 默认只允许超级用户使用复制源的函数，但可以通过GRANT命令允许其他用户使用。 复制槽的函数只限于超级用户和拥有REPLICATION权限的用户。
很多这些函数在复制协议中都有等价的命令，见 Section 53.4。
Section 9.27.3、 Section 9.27.4和 Section 9.27.5 中描述的函数也与复制相关。
Table 9.95. 复制管理函数
|
函数 描述 |
|---|
|
创建一个新的名为 |
|
丢弃名为 |
|
创建一个名为 |
|
将一个名为 |
|
复制一个名为 |
|
返回槽 |
|
行为就像 |
|
行为就像 |
|
行为就像 |
|
将复制槽的当前确认的位置提前到名为 |
|
用给定的外部名称创建一个复制源，并且返回分配给它的内部 ID。 |
|
删除一个以前创建的复制源，包括任何相关的重放进度。 |
|
通过名称查找复制源并返回其内部ID。如果未找到这样的复制源，则返回 |
|
将当前会话标记为从给定的原点回放，从而允许跟踪回放进度。 只能在当前没有选择原点时使用。使用 |
|
取消 |
|
如果在当前会话中选择了复制源则返回真。 |
|
返回当前会话中选择的复制源的重放位置。参数 |
|
将当前事务标记为重放在给定LSN和时间戳上提交的事务。 只能在使用 |
|
取消 |
|
将给定节点的复制进度设置为给定的位置。这主要用于设置初始位置，或在配置更改或类似的变更后设置新位置。 请注意这个函数的不当使用可能会导致不一致的复制数据。 |
|
返回给定复制元的重放位置。参数 |
|
发出逻辑解码消息。这可以用于通过WAL将通用消息传递给逻辑解码插件。 |
Table 9.96中所示的函数计算数据库对象的磁盘空间使用情况，或帮助表示或理解使用结果。 bigint结果以字节为单位。 如果将不代表已有对象的OID传递给这些函数之一，则返回NULL。
Table 9.96. 数据库对象尺寸函数
|
函数 描述 |
|---|
|
显示用于存储任何单个数据值的字节数。如果直接应用于表的列值，则反映所做的任何压缩。 |
|
显示用于压缩单个变长值的压缩算法。 如果值没有被压缩，则返回 |
|
计算具有指定名称或OID的数据库使用的总磁盘空间。要使用此函数，您必须对指定数据库具有 |
|
计算附加到指定表的索引所使用的总磁盘空间。 |
|
计算指定关系的一个“fork”所使用的磁盘空间。 (注意在大多数情况下，使用更高级的函数
|
|
将人可阅读的格式的大小(由 |
|
将字节大小转换为更易于人类阅读的格式，带有大小单位（字节，kB，MB，GB，TB或PB）。请注意，单位是2的幂，而不是10的幂，因此1kB是1024字节， 1MB是10242 = 1048576字节，依此类推。 |
|
计算指定表所使用的磁盘空间，不包括索引(但包括它的TOAST表，如果有的话，空闲空间映射，以及可见性映射)。 |
|
计算具有指定名称或OID的表空间中使用的总磁盘空间。 要使用此函数，您必须对指定的表空间具有 |
|
计算指定表所使用的总磁盘空间，包括所有索引和TOAST数据。 结果等价 |
上述操作表和索引的函数接受一个regclass参数，它是该表或索引在pg_class系统目录中的 OID。 你不必手工去查找该 OID，因为regclass数据类型的输入转换器会为你代劳。 只写包围在单引号内的表名，这样它看起来像一个文字常量。 为了与普通SQL名称的处理相兼容，该字符串将被转换为小写形式，除非其中在表名周围包含双引号。 详见Section 8.19。
Table 9.97中展示的函数帮助标识数据库对象相关的磁盘文件。
Table 9.97. 数据库对象位置函数
|
函数 描述 |
|---|
|
返回当前分配给指定关系的“filenode”数字。文件节点是用于该关系的文件名称的基本组件(更多信息请参阅Section 64.1 )。 对于大多数关系，其结果与 |
|
返回关系的完整文件路径名称（相对于数据库集簇的数据目录，即关系的 |
|
返回一个给定表空间OID和存储它的文件节点的关系的OID。这本质上是 |
Table 9.98 列出用于管理排序规则的函数。
Table 9.98. 排序规则管理函数
|
函数 描述 |
|---|
|
返回当前安装在操作系统中的该排序规则对象的实际版本。 如果这个版本与 |
|
返回数据库当前在操作系统中安装的排序规则的实际版本。如果这与 |
|
基于在操作系统中找到的所有区域设置（locale），将排序规则加入系统目录 |
Table 9.99 列出提供有关分区表结构信息的函数。
Table 9.99. 分区信息函数
例如，要检查分区表measurement中包含的数据的总大小，可以使用以下查询:
SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size
FROM pg_partition_tree('measurement');
Table 9.100 显示了索引维护任务可以使用的函数。 (注意，这些维护任务通常由自动清理(autovacuum)自动完成;只有在特殊情况下才需要使用这些函数。) 这些函数在恢复过程中无法执行。这些函数的使用局限于超级用户和给定索引的所有者。
Table 9.100. 索引维护函数
|
函数 描述 |
|---|
|
扫描指定的BRIN索引以查找基表中当前没有被索引归纳的页面范围; 对于任何这样的范围，它都通过扫描这些表页来创建一个新的摘要索引元组。 返回插入到索引中的新页面范围摘要的数量。 |
|
对覆盖给定块的页面范围执行摘要（如果尚未摘要）。 这类似于 |
|
删除归纳了覆盖给定表块的页面范围的BRIN索引元组，如果有的话。 |
|
清理指定GIN索引的“pending”列表，通过移除里面的条目，以大批的方式，到主要的GIN数据结构。 返回从挂起列表中删除的页数。如果参数是使用禁用 |
Table 9.101中展示的函数提供了对数据库服务器所在机器上的文件的本地访问。 只能访问数据库集簇目录以及log_directory中的文件，除非用户是超级用户或者被授予了角色pg_read_server_files。 使用相对路径访问集簇目录里面的文件，以及匹配 log_directory配置设置的路径访问日志文件。
注意在pg_read_file()或者相关函数上，向用户授予EXECUTE权限， 以允许他们有能力读取服务器上该数据库服务器进程能读取的任何文件；这些函数会绕过所有的数据库内权限检查。 这意味着，例如，具有这种访问的用户能够读取pg_authid表中存储着认证信息的内容，也能读取数据库中的任何表数据。 因此，授予对这些函数的访问应该要很仔细地考虑。
这些函数中的一些函数有可选的missing_ok参数，可以指定当文件或目录不存在时的行为。 如果为true，函数返回NULL或着空结果集，根据适合情况。 如果为false，会产生一个错误。默认为false。
Table 9.101. 通用文件访问函数
Table 9.102中展示的函数管理咨询锁。 有关正确使用这些函数的细节请参考Section 13.3.5。
所有这些函数都打算用于锁定应用程序定义的资源，可以通过一个64位键值或两个32位键值来标识(注意这两个键空间不能重叠)。 如果另一个会话已经在相同的资源标识符上持有一个冲突的锁，函数将等待直到资源变成可用，或者返回一个false结果，合适于函数的。 锁可以是共享或排他的:共享锁不会与同一资源上的其他共享锁发生冲突，只会与排他锁发生冲突。 锁可以在会话级(这样它们被保持直到释放或会话结束)或在事务级(这样它们被保持直到当前事务结束;没有手动释放的供应)。 多个会话级锁请求堆栈，因此如果同一个资源标识符被锁定三次，那么必须有三个解锁请求来释放资源，在会话结束之前。
Table 9.102. 咨询锁函数
如果您发现文档中有不正确的内容、与您使用特定功能的经验不符或需要进一步说明，请使用此表单来报告文档问题。