9.26. 系统 Management 功能

• 9 .26.1. 配置设置功能

• 9 0.26.2. 服务器信令功能

• 9 0.26.3. 备份控制功能

• 9 .26.4. 恢复控制功能

• 9 .26.5. 快照同步功能

• 9 .26.6. 复制功能

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

• 9 .26.8. 索引维护功能

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

• 9 .26.10. 咨询锁功能

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

9 .26.1. 配置设置功能

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

表 9.77. 配置设置功能

函数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. 服务器信令功能

如果成功，每个函数都将返回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. 备份控制功能

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. 恢复信息功能

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

表 9.81. 恢复控制功能

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

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

9 .26.5. 快照同步功能

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

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

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

表 9.82. 快照同步功能

函数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 49。复制源的功能使用仅限于超级用户。复制插槽功能的使用仅限于超级用户和具有REPLICATION特权的用户。

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

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

表 9.83. 复制 SQL 函数

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

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

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

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 66.3)。

• 'vm'返回与该关系关联的“可见性 Map”(请参见Section 66.4)的大小。

• 'init'返回与该关系关联的初始化分支的大小(如果有)。

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

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

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

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

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

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

pg_relation_filenode接受表，索引，序列或 Toast 表的 OID 或名称，并返回当前为其分配的“文件节点”号。 filenode 是用于该关系的文件名的基本组成部分(有关更多信息，请参见Section 66.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 功能

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. 索引维护功能

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

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

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

Table 9.88中显示的功能提供对托管服务器的计算机上文件的本地访问。只能访问数据库集群目录和log_directory中的文件。为群集目录中的文件使用相对路径，为日志文件使用与log_directory配置设置匹配的路径。除非另有说明，否则这些功能的使用仅限于超级用户。

表 9.88. 通用文件访问功能

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

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