9.27。系统管理函数#

9.27.1。配置设置函数

9.27.2。服务器信号函数

9.27.3。备份控制函数

9.27.4。恢复控制函数

9.27.5。快照同步函数

9.27.6。复制管理函数

9.27.7。数据库对象管理函数

9.27.8。索引维护函数

9.27.9。通用文件访问函数

9.27.10。咨询锁函数

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

9.27.1。配置设置函数#

表 9.89显示了可用于查询和更改运行时配置参数的函数。

表 9.89。配置设置函数

函数 说明 示例
current_setting ( setting_name text [, missing_ok boolean ] ) → text 返回设置 setting_name 的当前值。如果不存在此设置，则 current_setting 会引发错误，除非提供了 missing_ok 并且为 true（在这种情况下，将返回 NULL）。此函数对应于 命令 SHOW。 current_setting('datestyle') → ISO, MDY
set_config ( setting_name text, new_value text, is_local boolean ) → text 将参数 setting_name 设置为 new_value，并返回该值。如果 is_local 为 true，则新值仅在当前事务期间应用。如果您希望新值在当前会话的剩余时间内应用，请改用 false。此函数对应于 SQL 命令 SET。 set_config('log_statement_stats', 'off', false) → off

9.27.2。服务器信号函数#

在表 9.90中显示的函数向其他服务器进程发送控制信号。默认情况下，只有超级用户才能使用这些函数，但可以使用GRANT授予其他人访问权限，但有例外情况。

如果信号已成功发送，则这些函数中的每个函数将返回true，如果发送信号失败，则返回false。

表 9.90。服务器信号函数

函数 说明
pg_cancel_backend ( pid integer ) → boolean 取消后台进程具有指定进程 ID 的会话的当前查询。如果调用角色是其后台正在取消的角色的成员，或者调用角色具有 pg_signal_backend 的权限，则也允许这样做，但是只有超级用户才能取消超级用户后台。
pg_log_backend_memory_contexts ( pid integer ) → boolean 请求记录具有指定进程 ID 的后台的内存上下文。此函数可以将请求发送到后台和辅助进程（记录器除外）。这些内存上下文将记录在 LOG 消息级别。它们将根据设置的日志配置出现在服务器日志中（有关详细信息，请参见 第 20.8 节），但无论 client_min_messages 如何，都不会发送到客户端。
pg_reload_conf () → boolean 导致 PostgreSQL 服务器的所有进程重新加载其配置文件。（这是通过向 postmaster 进程发送 SIGHUP 信号来启动的，postmaster 进程又向其每个子进程发送 SIGHUP。）在重新加载之前，可以使用 pg_file_settings、pg_hba_file_rules 和 pg_ident_file_mappings 视图检查配置文件是否有可能的错误。
pg_rotate_logfile () → boolean 向日志文件管理器发出信号，立即切换到新的输出文件。这仅在内置日志收集器正在运行时才有效，因为否则没有日志文件管理器子进程。
pg_terminate_backend ( pid integer, timeout bigint DEFAULT 0 ) → boolean 终止具有指定进程 ID 的后端进程的会话。如果调用角色是正在终止的后端的角色的成员，或者调用角色具有 pg_signal_backend 的权限，则这也允许，但是只有超级用户可以终止超级用户后端。 如果未指定 timeout 或为零，则无论进程是否实际终止，此函数都会返回 true，仅表示发送信号成功。如果指定了 timeout（以毫秒为单位）并且大于零，则该函数将一直等到进程实际终止或给定时间过去。如果进程终止，则该函数将返回 true。超时时，将发出警告并返回 false。

pg_cancel_backend和pg_terminate_backend向由进程 ID 标识的后端进程发送信号（分别为SIGINT或SIGTERM）。可以在pg_stat_activity视图的pid列中找到活动后端的进程 ID，或通过列出服务器上的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 个子上下文，以及剩余上下文的摘要。请注意，频繁调用此函数可能会产生大量开销，因为它可能会生成大量的日志消息。

9.27.3. 备份控制函数#

表 9.91中显示的函数有助于进行在线备份。这些函数不能在恢复期间执行（pg_backup_start、pg_backup_stop和pg_wal_lsn_diff除外）。

有关正确使用这些函数的详细信息，请参见第 26.3 节。

表 9.91. 备份控制函数

函数 说明
pg_create_restore_point ( name text ) → pg_lsn 在预写日志中创建一个命名的标记记录，该记录稍后可用作恢复目标，并返回相应的预写日志位置。然后，可以在 recovery_target_name 中使用给定的名称来指定恢复将继续进行到的点。避免创建具有相同名称的多个还原点，因为恢复将在名称与恢复目标匹配的第一个还原点处停止。 此函数默认仅限超级用户使用，但可以授予其他用户 EXECUTE 权限来运行该函数。
pg_current_wal_flush_lsn () → pg_lsn 返回当前预写日志刷新位置（请参见以下注释）。
pg_current_wal_insert_lsn () → pg_lsn 返回当前预写日志插入位置（请参见以下注释）。
pg_current_wal_lsn () → pg_lsn 返回当前预写日志写入位置（请参见以下注释）。
pg_backup_start ( label text [, fast boolean ] ) → pg_lsn 准备服务器开始在线备份。唯一必需的参数是备份的任意用户定义标签。（通常这将是备份转储文件将存储在其下的名称。）如果将可选的第二个参数指定为 true，则指定尽可能快地执行 pg_backup_start。这会强制立即检查点，这会导致 I/O 操作激增，从而减慢任何并发执行的查询。 此函数默认仅限超级用户使用，但可以授予其他用户 EXECUTE 权限来运行该函数。
pg_backup_stop ( [wait_for_archive boolean ] ) → record ( lsn pg_lsn, labelfile text, spcmapfile text ) 完成执行在线备份。备份标签文件和表空间映射文件所需的内容作为函数结果的一部分返回，并且必须写入备份区域中的文件。这些文件不得写入实时数据目录（这样做会导致 PostgreSQL 在发生崩溃时无法重新启动）。 有一个类型为 boolean 的可选参数。如果为 false，则该函数将在备份完成后立即返回，而无需等待 WAL 存档。此行为仅适用于独立监控 WAL 存档的备份软件。否则，使备份保持一致所需的 WAL 可能会丢失，从而使备份变得无用。默认情况下或当此参数为 true 时，pg_backup_stop 将在启用存档时等待 WAL 存档。（在备用服务器上，这意味着它仅在 archive_mode = always 时才等待。如果主服务器上的写入活动较低，则在主服务器上运行 pg_switch_wal 以触发立即段切换可能很有用。） 在主服务器上执行时，此函数还会在预写日志存档区域中创建一个备份历史文件。历史文件包括提供给 pg_backup_start 的标签、备份的开始和结束预写日志位置以及备份的开始和结束时间。在记录结束位置后，当前预写日志插入点将自动前进到下一个预写日志文件，以便可以立即存档结束预写日志文件以完成备份。 该函数的结果是一条记录。lsn 列保存备份的结束预写日志位置（可以再次忽略）。第二列返回备份标签文件的内容，第三列返回表空间映射文件的内容。这些内容必须作为备份的一部分进行存储，并且是还原过程的一部分要求。 此函数默认仅限超级用户使用，但可以授予其他用户 EXECUTE 权限来运行该函数。
pg_switch_wal () → pg_lsn 强制服务器切换到一个新的预写日志文件，这允许存档当前文件（假设您正在使用连续存档）。结果是结束预写日志位置加上 1，在刚刚完成的预写日志文件中。如果自上次预写日志切换以来没有预写日志活动，pg_switch_wal 将不执行任何操作，并返回当前正在使用的预写日志文件的开始位置。 此函数默认仅限超级用户使用，但可以授予其他用户 EXECUTE 权限来运行该函数。
pg_walfile_name ( lsn pg_lsn ) → text 将预写式日志位置转换为包含该位置的 WAL 文件的名称。
pg_walfile_name_offset ( lsn pg_lsn ) → record ( file_name text, file_offset integer ) 将预写式日志位置转换为 WAL 文件名和该文件中的字节偏移量。
pg_split_walfile_name ( file_name text ) → record ( segment_number numeric, timeline_id bigint ) 从 WAL 文件名中提取序列号和时间线 ID。
pg_wal_lsn_diff ( lsn1 pg_lsn, lsn2 pg_lsn ) → numeric 计算两个预写式日志位置之间的字节差值（lsn1 - lsn2）。可将其与 pg_stat_replication 或 表 9.91 中显示的某些函数配合使用，以获取复制延迟。

pg_current_wal_lsn显示当前预写式日志写入位置，格式与上述函数所用格式相同。类似地，pg_current_wal_insert_lsn显示当前预写式日志插入位置，pg_current_wal_flush_lsn显示当前预写式日志刷新位置。插入位置是任何时刻预写式日志的“逻辑”结束，而写入位置是实际从服务器内部缓冲区写入的结束，刷新位置是已知写入到持久性存储的最后一个位置。写入位置是可以从服务器外部检查的结束，如果您有兴趣归档部分完成的预写式日志文件，通常需要此位置。插入位置和刷新位置主要用于服务器调试目的。这些都是只读操作，不需要超级用户权限。

您可以使用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仅提取预写日志文件名。当给定的预写日志位置恰好位于预写日志文件边界时，这两个函数都会返回前一个预写日志文件的名称。这通常是管理预写日志归档行为所需的，因为前一个文件是当前需要归档的最后一个文件。

pg_split_walfile_name可用于从文件偏移量和 WAL 文件名计算LSN，例如

postgres=# \set file_name '000000010000000100C000AB'
postgres=# \set offset 256
postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset AS lsn
  FROM pg_split_walfile_name(:'file_name') pd,
       pg_show_all_settings() ps
  WHERE ps.name = 'wal_segment_size';
      lsn
---------------
 C001/AB000100
(1 row)

9.27.4. 恢复控制函数#

表 9.92中显示的函数提供有关备用服务器当前状态的信息。这些函数可以在恢复期间和正常运行期间执行。

表 9.92. 恢复信息函数

函数 说明
pg_is_in_recovery () → boolean 如果恢复仍在进行中，则返回 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。
pg_get_wal_resource_managers () → setof record ( rm_id integer, rm_name text, rm_builtin boolean ) 返回系统中当前加载的 WAL 资源管理器。列 rm_builtin 指示它是一个内置资源管理器，还是由扩展加载的自定义资源管理器。

在表 9.93中显示的函数控制恢复的进度。这些函数只能在恢复期间执行。

表 9.93。恢复控制函数

函数 说明
pg_is_wal_replay_paused () → boolean 如果请求恢复暂停，则返回 true。
pg_get_wal_replay_pause_state () → text 返回恢复暂停状态。如果未请求暂停，则返回值为 not paused；如果请求暂停但恢复尚未暂停，则返回值为 pause requested；如果恢复实际已暂停，则返回值为 paused。
pg_promote ( wait boolean DEFAULT true, wait_seconds integer DEFAULT 60 ) → boolean 将备用服务器提升为主服务器状态。将 wait 设置为 true（默认值）时，该函数将等待提升完成或 wait_seconds 秒已过，如果提升成功则返回 true，否则返回 false。如果将 wait 设置为 false，则该函数在向 postmaster 发送 SIGUSR1 信号以触发提升后立即返回 true。 此函数默认仅限超级用户使用，但可以授予其他用户 EXECUTE 权限来运行该函数。
pg_wal_replay_pause () → void 请求暂停恢复。请求并不意味着恢复会立即停止。如果您希望确保恢复实际已暂停，则需要检查 pg_get_wal_replay_pause_state() 返回的恢复暂停状态。请注意，pg_is_wal_replay_paused() 返回是否已发出请求。在恢复暂停期间，不会应用进一步的数据库更改。如果热备用处于活动状态，则所有新查询都将看到数据库的相同一致快照，并且在恢复恢复之前不会生成进一步的查询冲突。 此函数默认仅限超级用户使用，但可以授予其他用户 EXECUTE 权限来运行该函数。
pg_wal_replay_resume () → void 如果已暂停，则重新启动恢复。 此函数默认仅限超级用户使用，但可以授予其他用户 EXECUTE 权限来运行该函数。

pg_wal_replay_pause和pg_wal_replay_resume在提升正在进行时无法执行。如果在恢复暂停时触发提升，则暂停状态结束且提升继续。

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

9.27.5 快照同步函数#

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

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

快照使用pg_export_snapshot函数导出，该函数在表 9.94中显示，并使用SET TRANSACTION命令导入。

表 9.94。快照同步函数

函数 说明
pg_export_snapshot () → text 保存事务的当前快照，并返回一个标识该快照的 text 字符串。此字符串必须传递给想要导入快照的客户端（在数据库外部）。快照仅在导出它的事务结束之前可用于导入。 如果需要，一个事务可以导出多个快照。请注意，这样做仅在 READ COMMITTED 事务中有用，因为在 REPEATABLE READ 和更高的隔离级别中，事务在其整个生命周期中使用相同的快照。一旦事务导出了任何快照，就不能使用 PREPARE TRANSACTION 来准备它。
pg_log_standby_snapshot () → pg_lsn 对正在运行的事务进行快照，并将其写入 WAL，而无需等待 bgwriter 或检查点记录一个。这对于备用上的逻辑解码很有用，因为逻辑槽的创建必须等到此类记录在备用上重放。

9.27.6。复制管理函数#

在表 9.95中显示的函数用于控制和与复制功能交互。有关底层功能的信息，请参见第 27.2.5 节、第 27.2.6 节和第 50 章。默认情况下，只有超级用户才能使用复制源函数，但可以使用GRANT命令允许其他用户使用。复制槽函数的使用仅限于超级用户和具有REPLICATION权限的用户。

这些函数中的许多函数在复制协议中具有等效命令；请参阅第 55.4 节。

第 9.27.3 节、第 9.27.4 节和第 9.27.5 节中描述的函数也与复制相关。

表 9.95. 复制管理函数

函数 说明
pg_create_physical_replication_slot ( slot_name name [, immediately_reserve boolean, temporary boolean ] ) → record ( slot_name name, lsn pg_lsn ) 创建一个名为 slot_name 的新物理复制槽。当第二个可选参数为 true 时，指定立即保留此复制槽的 ；否则，在流复制客户端首次连接时保留 。只能使用流复制协议从物理槽流式传输更改 — 请参阅第 55.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, twophase boolean ] ) → record ( slot_name name, lsn pg_lsn ) 使用输出插件 plugin 创建一个名为 slot_name 的新逻辑（解码）复制槽。可选的第三个参数 temporary 设置为 true 时，指定该槽不应永久存储到磁盘，并且仅供当前会话使用。临时槽在发生任何错误时也会释放。可选的第四个参数 twophase 设置为 true 时，指定启用此槽的已准备事务解码。调用此函数的效果与复制协议命令 CREATE_REPLICATION_SLOT ... LOGICAL 相同。
pg_copy_physical_replication_slot ( src_slot_name name, dst_slot_name name [, temporary boolean ] ) → record ( slot_name name, lsn pg_lsn ) 将名为 src_slot_name 的现有物理复制槽复制到名为 dst_slot_name 的物理复制槽。复制的物理槽开始从与源槽相同的 保留 WAL。 temporary 是可选的。如果省略 temporary，则使用与源槽相同的值。
pg_copy_logical_replication_slot ( src_slot_name name, dst_slot_name name [, temporary boolean [, plugin name ]] ) → record ( slot_name name, lsn pg_lsn ) 将名为 src_slot_name 的现有逻辑复制槽复制到名为 dst_slot_name 的逻辑复制槽，可以选择更改输出插件和持久性。复制的逻辑槽从与源逻辑槽相同的 开始。 temporary 和 plugin 都是可选的；如果省略它们，则使用源槽的值。
pg_logical_slot_get_changes ( slot_name name, upto_lsn pg_lsn, upto_nchanges integer, VARIADIC options text[] ) → setof record ( 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 integer, VARIADIC options text[] ) → setof record ( 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 integer, VARIADIC options text[] ) → setof record ( 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 integer, VARIADIC options text[] ) → setof record ( lsn pg_lsn, xid xid, data bytea ) 行为与 pg_logical_slot_peek_changes() 函数完全相同，但更改将作为 bytea 返回。
pg_replication_slot_advance ( slot_name name, upto_lsn pg_lsn ) → record ( slot_name name, end_lsn pg_lsn ) 推进名为 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。如果找不到此类复制源，则返回 NULL。
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 () → boolean 如果在当前会话中已选择复制源，则返回 true。
pg_replication_origin_session_progress ( flush boolean ) → pg_lsn 返回当前会话中选择的复制源的重放位置。参数 flush 确定相应的本地事务是否已保证刷新到磁盘。
pg_replication_origin_xact_setup ( origin_lsn pg_lsn, origin_timestamp timestamp with time zone ) → void 将当前事务标记为重放已在给定 和时间戳提交的事务。仅当已使用 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 boolean ) → pg_lsn 返回给定复制源的重放位置。参数 flush 确定相应的本地事务是否已保证刷新到磁盘。
pg_logical_emit_message ( transactional boolean, prefix text, content text ) → pg_lsn pg_logical_emit_message ( transactional boolean, prefix text, content bytea ) → pg_lsn 发出逻辑解码消息。这可用于通过 WAL 向逻辑解码插件传递通用消息。 transactional 参数指定消息是否应为当前事务的一部分，或者是否应立即写入并在逻辑解码器读取记录后立即解码。 prefix 参数是逻辑解码插件可用于轻松识别对其感兴趣的消息的文本前缀。 content 参数是消息的内容，以文本或二进制形式给出。

9.27.7. 数据库对象管理函数#

表 9.96中显示的函数计算数据库对象磁盘空间使用情况，或帮助呈现或理解使用情况结果。bigint结果以字节为单位进行测量。如果将不表示现有对象的 OID 传递给其中一个函数，则返回NULL。

表 9.96。数据库对象大小函数

函数 说明
pg_column_size ( "any" ) → integer 显示用于存储任何单个数据值所使用的字节数。如果直接应用于表列值，这将反映所做的任何压缩。
pg_column_compression ( "any" ) → text 显示用于压缩单个可变长度值所使用的压缩算法。如果值未压缩，则返回 NULL。
pg_database_size ( name ) → bigint pg_database_size ( oid ) → bigint 计算指定名称或 OID 的数据库使用的总磁盘空间。要使用此函数，您必须对指定数据库（默认情况下已授予）具有 CONNECT 权限，或具有 pg_read_all_stats 角色的权限。
pg_indexes_size ( regclass ) → bigint 计算附加到指定表的索引使用的总磁盘空间。
pg_relation_size ( relation regclass [, fork text ] ) → bigint 计算指定关系的一个 “fork” 所使用的磁盘空间。（请注意，对于大多数目的，使用更高级别的函数 pg_total_relation_size 或 pg_table_size 会更方便，它们会对所有 fork 的大小求和。）使用一个参数时，这会返回关系的主数据 fork 的大小。可以提供第二个参数来指定要检查哪个 fork main 返回关系的主数据 fork 的大小。 fsm 返回与关系关联的空闲空间图（请参见 第 73.3 节）的大小。 vm 返回与关系关联的可见性图（请参见 第 73.4 节）的大小。 init 返回与关系关联的初始化 fork（如果有）的大小。
pg_size_bytes ( text ) → bigint 将以人类可读格式（由 pg_size_pretty 返回）的大小转换为字节。有效单位为 bytes、B、kB、MB、GB、TB 和 PB。
pg_size_pretty ( bigint ) → text pg_size_pretty ( numeric ) → text 将以字节为单位的大小转换为更易于人类阅读的格式，并带有大小单位（根据需要为字节、kB、MB、GB、TB 或 PB）。请注意，单位是 2 的幂而不是 10 的幂，因此 1kB 为 1024 字节，1MB 为 10242 = 1048576 字节，依此类推。
pg_table_size ( regclass ) → bigint 计算指定表使用的磁盘空间，不包括索引（但包括其 TOAST 表（如果有）、空闲空间图和可见性图）。
pg_tablespace_size ( name ) → bigint pg_tablespace_size ( oid ) → bigint 计算指定名称或 OID 的表空间中使用的总磁盘空间。要使用此函数，您必须对指定表空间拥有 CREATE 权限，或拥有 pg_read_all_stats 角色的权限，除非它是当前数据库的默认表空间。
pg_total_relation_size ( regclass ) → bigint 计算指定表使用的总磁盘空间，包括所有索引和 数据。结果等同于 pg_table_size + pg_indexes_size。

上面对表或索引进行操作的函数接受regclass参数，它只是pg_class系统目录中表或索引的 OID。但是，您不必手动查找 OID，因为regclass数据类型的输入转换器将为您完成这项工作。有关详细信息，请参见第 8.19 节。

表 9.97中显示的函数有助于识别与数据库对象关联的特定磁盘文件。

表 9.97. 数据库对象位置函数

函数 说明
pg_relation_filenode ( relation regclass ) → oid 返回当前分配给指定关系的 “filenode” 号码。filenode 是用于关系的文件名的基本组件（有关更多信息，请参见 第 73.1 节）。对于大多数关系，结果与 pg_class.relfilenode 相同，但对于某些系统目录，relfilenode 为零，并且必须使用此函数来获取正确的值。如果传递给没有存储的关系（例如视图），则该函数返回 NULL。
pg_relation_filepath ( relation regclass ) → text 返回关系的整个文件路径名（相对于数据库集群的数据目录 PGDATA）。
pg_filenode_relation ( tablespace oid, filenode oid ) → regclass 返回给定表空间 OID 和其存储的文件节点的关系的 OID。这本质上是 pg_relation_filepath 的反向映射。对于数据库默认表空间中的关系，表空间可以指定为零。如果当前数据库中没有关系与给定值相关联，则返回 NULL。

表 9.98列出了用于管理整理规则的函数。

表 9.98。整理规则管理函数

函数 说明
pg_collation_actual_version ( oid ) → text 返回整理规则对象在操作系统中当前安装的实际版本。如果这与 pg_collation.collversion 中的值不同，则可能需要重建依赖于整理规则的对象。另请参见 ALTER COLLATION。
pg_database_collation_actual_version ( oid ) → text 返回数据库整理规则在操作系统中当前安装的实际版本。如果这与 pg_database.datcollversion 中的值不同，则可能需要重建依赖于整理规则的对象。另请参见 ALTER DATABASE。
pg_import_system_collations ( schema regnamespace ) → integer 根据操作系统中找到的所有语言环境，将对照添加到系统目录 pg_collation 中。这是 initdb 使用的内容；有关更多详细信息，请参见 第 24.2.2 节。如果稍后在操作系统中安装了其他语言环境，则可以再次运行此函数以添加新语言环境的对照。将跳过与 pg_collation 中现有条目匹配的语言环境。（但此函数不会删除基于不再存在于操作系统中的语言环境的对照对象。）schema 参数通常为 pg_catalog，但这并不是必需的；对照也可以安装到其他一些模式中。该函数返回它创建的新对照对象的数量。此函数的使用仅限于超级用户。

表 9.99列出了提供有关分区表结构的信息的函数。

表 9.99. 分区信息函数

函数 说明
pg_partition_tree ( regclass ) → setof record ( relid regclass, parentrelid regclass, isleaf boolean, level integer ) 列出给定分区表或分区索引的分区树中的表或索引，每行一个分区。提供的信息包括分区的 OID、其直接父级的 OID、一个布尔值（指示分区是否是叶子）和一个整数（指示其在层次结构中的级别）。对于输入表或索引，级别值为 0，对于其直接子分区，级别值为 1，对于其分区，级别值为 2，依此类推。如果关系不存在或不是分区或分区表，则不返回任何行。
pg_partition_ancestors ( regclass ) → setof regclass 列出给定分区的祖先关系，包括关系本身。如果关系不存在或不是分区或分区表，则不返回任何行。
pg_partition_root ( regclass ) → regclass 返回给定关系所属的分区树的最顶层父级。如果关系不存在或不是分区或分区表，则返回 NULL。

例如，要检查分区表measurement中包含的数据的总大小，可以使用以下查询

SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size
  FROM pg_partition_tree('measurement');

9.27.8. 索引维护函数#

表 9.100显示了可用于索引维护任务的函数。（请注意，这些维护任务通常由自动清理程序自动完成；仅在特殊情况下才需要使用这些函数。）这些函数不能在恢复期间执行。这些函数的使用仅限于超级用户和给定索引的所有者。

表 9.100. 索引维护函数

函数 说明
brin_summarize_new_values ( index regclass ) → integer 扫描指定的 BRIN 索引以查找基本表中当前未由索引总结的页面范围；对于任何此类范围，它通过扫描那些表页面来创建一个新的总结索引元组。返回插入到索引中的新页面范围总结的数量。
brin_summarize_range ( index regclass, blockNumber bigint ) → integer 总结覆盖给定块的页面范围（如果尚未总结）。这类似于 brin_summarize_new_values，但它仅处理覆盖给定表块号的页面范围。
brin_desummarize_range ( index regclass, blockNumber bigint ) → void 如果存在，则删除总结覆盖给定表块的页面范围的 BRIN 索引元组。
gin_clean_pending_list ( index regclass ) → bigint 清理指定 GIN 索引的 “待处理” 列表，将其中的条目批量移动到 GIN 主数据结构中。返回从待处理列表中移除的页数。如果参数是使用禁用了 fastupdate 选项构建的 GIN 索引，则不会执行清理，结果为零，因为该索引没有待处理列表。有关待处理列表和 fastupdate 选项的详细信息，请参见 第 70.4.1 节 和 第 70.5 节。

9.27.9. 通用文件访问函数#

在表 9.101中显示的函数提供对托管服务器的机器上的文件的本机访问。除非用户是超级用户或被授予pg_read_server_files角色，否则只能访问数据库集群目录和log_directory中的文件。对集群目录中的文件使用相对路径，对日志文件使用与log_directory配置设置匹配的路径。

请注意，向用户授予对pg_read_file()或相关函数的 EXECUTE 权限，允许他们读取数据库服务器进程可以读取的服务器上的任何文件；这些函数绕过了所有数据库内权限检查。这意味着，例如，具有此类访问权限的用户能够读取存储身份验证信息的pg_authid表的内容，以及读取数据库中的任何表数据。因此，应仔细考虑授予对这些函数的访问权限。

在授予对这些函数的权限时，请注意，显示可选参数的表条目主要作为具有不同参数列表的多个物理函数实现。如果要使用此类函数，则必须分别授予每个函数的权限。psql的\df命令可用于检查实际函数签名。

其中一些函数采用可选的*missing_ok*参数，该参数指定文件或目录不存在时的行为。如果为true，则该函数将返回NULL或空结果集（视情况而定）。如果为false，则会引发错误。（无论如何，都会将“文件未找到”以外的故障条件报告为错误。）默认值为false。

表 9.101. 通用文件访问函数

函数 说明
pg_ls_dir ( dirname text [, missing_ok boolean, include_dot_dirs boolean ] ) → setof text 返回指定目录中的所有文件（以及目录和其他特殊文件）的名称。include_dot_dirs 参数指示是否将 “.” 和 “..” 包含在结果集中；默认情况下不包含它们。当 missing_ok 为 true 时，包含它们可能很有用，以区分空目录和不存在的目录。 此函数默认仅限超级用户使用，但可以授予其他用户 EXECUTE 权限来运行该函数。
pg_ls_logdir () → setof record ( name text, size bigint, modification timestamp with time zone ) 返回服务器日志目录中每个普通文件的名称、大小和上次修改时间 (mtime)。以点开头的文件名、目录和其他特殊文件将被排除在外。 默认情况下，此函数仅限于超级用户和具有 pg_monitor 角色权限的角色，但可以向其他用户授予 EXECUTE 以运行此函数。
pg_ls_waldir () → setof record ( name text, size bigint, modification timestamp with time zone ) 返回服务器预写日志 (WAL) 目录中每个普通文件的名称、大小和上次修改时间 (mtime)。以点开头的文件名、目录和其他特殊文件将被排除在外。 默认情况下，此函数仅限于超级用户和具有 pg_monitor 角色权限的角色，但可以向其他用户授予 EXECUTE 以运行此函数。
pg_ls_logicalmapdir () → setof record ( name text, size bigint, modification timestamp with time zone ) 返回服务器 pg_logical/mappings 目录中每个普通文件的名称、大小和上次修改时间 (mtime)。以点开头的文件名、目录和其他特殊文件将被排除在外。 默认情况下，此函数仅限于超级用户和 pg_monitor 角色的成员，但可以向其他用户授予 EXECUTE 以运行此函数。
pg_ls_logicalsnapdir () → setof record ( name text, size bigint, modification timestamp with time zone ) 返回服务器 pg_logical/snapshots 目录中每个普通文件的文件名、大小和最后修改时间 (mtime)。以点开头的文件名、目录和其他特殊文件将被排除在外。 默认情况下，此函数仅限于超级用户和 pg_monitor 角色的成员，但可以向其他用户授予 EXECUTE 以运行此函数。
pg_ls_replslotdir ( slot_name text ) → setof record ( name text, size bigint, modification timestamp with time zone ) 返回服务器 pg_replslot/slot_name 目录中每个普通文件的文件名、大小和最后修改时间 (mtime)，其中 slot_name 是作为函数输入提供的复制槽的名称。以点开头的文件名、目录和其他特殊文件将被排除在外。 默认情况下，此函数仅限于超级用户和 pg_monitor 角色的成员，但可以向其他用户授予 EXECUTE 以运行此函数。
pg_ls_archive_statusdir () → setof record ( name text, size bigint, modification timestamp with time zone ) 返回服务器 WAL 归档状态目录 (pg_wal/archive_status) 中每个普通文件的文件名、大小和最后修改时间 (mtime)。以点开头的文件名、目录和其他特殊文件将被排除在外。 默认情况下，此函数仅限于超级用户和 pg_monitor 角色的成员，但可以向其他用户授予 EXECUTE 以运行此函数。
pg_ls_tmpdir ( [ tablespace oid ] ) → setof record ( name text, size bigint, modification timestamp with time zone ) 返回指定 tablespace 中临时文件目录中每个普通文件的名称、大小和最后修改时间 (mtime)。如果未提供 tablespace，则检查 pg_default 表空间。以点开头的文件名、目录和其他特殊文件将被排除。 默认情况下，此函数仅限于超级用户和 pg_monitor 角色的成员，但可以向其他用户授予 EXECUTE 以运行此函数。
pg_read_file ( filename text [, offset bigint, length bigint ] [, missing_ok boolean ] ) → text 返回文本文件的部分或全部内容，从给定的字节 offset 开始，最多返回 length 字节（如果先达到文件结尾，则返回的字节数更少）。如果 offset 为负，则它相对于文件的结尾。如果省略 offset 和 length，则返回整个文件。从文件中读取的字节在数据库的编码中解释为字符串；如果它们在该编码中无效，则会引发错误。 此函数默认仅限超级用户使用，但可以授予其他用户 EXECUTE 权限来运行该函数。
pg_read_binary_file ( filename text [, offset bigint, length bigint ] [, missing_ok boolean ] ) → bytea 返回文件的部分或全部内容。此函数与 pg_read_file 相同，但它可以读取任意二进制数据，将结果作为 bytea 而不是 text 返回；因此，不会执行任何编码检查。 此函数默认仅限超级用户使用，但可以授予其他用户 EXECUTE 权限来运行该函数。 此函数结合 convert_from 函数可用于读取指定编码的文本文件并转换为数据库的编码 SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8');
pg_stat_file ( filename text [, missing_ok boolean ] ) → record ( size bigint, access timestamp with time zone, modification timestamp with time zone, change timestamp with time zone, creation timestamp with time zone, isdir boolean ) 返回包含文件大小、最后访问时间戳、最后修改时间戳、最后文件状态更改时间戳（仅限 Unix 平台）、文件创建时间戳（仅限 Windows）以及指示它是否为目录的标志的记录。 此函数默认仅限超级用户使用，但可以授予其他用户 EXECUTE 权限来运行该函数。

9.27.10. 咨询锁功能#

在表 9.102中显示的功能管理咨询锁。有关这些功能的正确使用详细信息，请参阅第 13.3.5 节。

所有这些功能都旨在用于锁定应用程序定义的资源，这些资源可以通过单个 64 位键值或两个 32 位键值来标识（请注意，这两个键空间不重叠）。如果另一个会话已对同一资源标识符持有冲突锁，则这些功能将等待资源可用，或返回false结果，具体取决于该功能。锁可以是共享的或独占的：共享锁不会与同一资源上的其他共享锁冲突，只会与独占锁冲突。锁可以在会话级别（以便在释放或会话结束之前一直持有）或在事务级别（以便在当前事务结束之前一直持有；没有手动释放的规定）进行获取。多个会话级锁请求堆叠，因此如果同一资源标识符被锁定了三次，则必须有三个解锁请求才能在会话结束之前释放资源。

表 9.102. 咨询锁功能

函数 说明
pg_advisory_lock ( key bigint ) → void pg_advisory_lock ( key1 integer, key2 integer ) → void 获取独占会话级咨询锁，必要时等待。
pg_advisory_lock_shared ( key bigint ) → void pg_advisory_lock_shared ( key1 integer, key2 integer ) → void 获取一个共享会话级咨询锁，必要时等待。
pg_advisory_unlock ( key bigint ) → boolean pg_advisory_unlock ( key1 integer, key2 integer ) → boolean 释放先前获取的独占会话级咨询锁。如果锁成功释放，则返回 true。如果未持有锁，则返回 false，此外，服务器将报告 SQL 警告。
pg_advisory_unlock_all () → void 释放当前会话持有的所有会话级咨询锁。（即使客户端不正常断开连接，也会在会话结束时隐式调用此函数。）
pg_advisory_unlock_shared ( key bigint ) → boolean pg_advisory_unlock_shared ( key1 integer, key2 integer ) → boolean 释放先前获取的共享会话级咨询锁。如果锁成功释放，则返回 true。如果未持有锁，则返回 false，此外，服务器将报告 SQL 警告。
pg_advisory_xact_lock ( key bigint ) → void pg_advisory_xact_lock ( key1 integer, key2 integer ) → void 获取一个独占事务级咨询锁，必要时等待。
pg_advisory_xact_lock_shared ( key bigint ) → void pg_advisory_xact_lock_shared ( key1 integer, key2 integer ) → void 获取一个共享事务级别的咨询锁，必要时等待。
pg_try_advisory_lock ( key bigint ) → boolean pg_try_advisory_lock ( key1 integer, key2 integer ) → boolean 如果可用，获取一个独占会话级别的咨询锁。这将立即获取锁并返回 true，或在无法立即获取锁时返回 false，而不等待。
pg_try_advisory_lock_shared ( key bigint ) → boolean pg_try_advisory_lock_shared ( key1 integer, key2 integer ) → boolean 如果可用，获取一个共享会话级别的咨询锁。这将立即获取锁并返回 true，或在无法立即获取锁时返回 false，而不等待。
pg_try_advisory_xact_lock ( key bigint ) → boolean pg_try_advisory_xact_lock ( key1 integer, key2 integer ) → boolean 如果可用，获取一个独占事务级别的咨询锁。这将立即获取锁并返回 true，或在无法立即获取锁时返回 false，而不等待。
pg_try_advisory_xact_lock_shared ( key bigint ) → boolean pg_try_advisory_xact_lock_shared ( key1 integer, key2 integer ) → boolean 如果可用，获取一个共享事务级别的咨询锁。这将立即获取锁并返回 true，或在无法立即获取锁时返回 false，而不等待。