Postgresql 中文操作指南

9.27. System Administration Functions #

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

9.27.1. Configuration Settings Functions #

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

Table 9.89. Configuration Settings Functions

Function

Description

Example(s)

current_setting ( setting_name text [, missing_ok boolean ] ) → text 返回设置 setting_name 的当前值。如果没有此设置， current_setting 将抛出错误，除非提供了 missing_ok 并且它为 true （在这种情况下返回 NULL）。此函数对应于 SQL 命令 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. Server Signaling Functions #

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

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

Table 9.90. Server Signaling Functions

Function

Description

pg_cancel_backend ( pid integer ) → boolean 取消会话中当前查询会话，其后台进程具有指定的进程 ID。如果调用角色是其后端正在取消的角色的成员，或调用角色具有 pg_signal_backend 权限，则这也允许，但是只有超级用户可以取消超级用户后端。

pg_log_backend_memory_contexts ( pid integer ) → boolean 请求记录具有指定进程 ID 的后端的内存上下文。此函数可以向后端和辅助进程（日志记录器除外）发送请求。这些内存上下文将在 LOG 消息级别记录。它们将根据已设置的日志配置显示在服务器日志中（有关更多信息，请参见 Section 20.8 ），但无论 client_min_messages 如何，都不会发送给客户端。

pg_reload_conf () → boolean 使 PostgreSQL 服务器的所有进程重新加载其配置文件。（这是通过向 postmaster 进程发送 SIGHUP 信号来启动的，后者又向每个子进程发送 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）。已激活后端的进程 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 个子上下文，并提供剩余上下文摘要。请注意，频繁调用此功能可能会产生大量的开销，因为它可能会生成大量日志消息。

9.27.3. Backup Control Functions #

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

有关如何正确使用这些功能的详细信息，请参阅 Section 26.3 。

Table 9.91. Backup Control Functions

Function

Description

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 或 Table 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. Recovery Control Functions #

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

Table 9.92. Recovery Information Functions

Function

Description

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 列指示它是内置资源管理器还是扩展加载的自定义资源管理器。

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

Table 9.93. Recovery Control Functions

Function

Description

pg_is_wal_replay_paused () → boolean 如果请求恢复暂停，则返回 true。如果未请求暂停，则返回值为 not paused ；如果请求暂停但恢复尚未暂停，则为 pause requested ；如果实际上已暂停恢复，则为 paused 。

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. Snapshot Synchronization Functions #

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

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

快照使用 pg_export_snapshot 函数导出，如 Table 9.94 中所示，并使用 SET TRANSACTION 命令导入。

Table 9.94. Snapshot Synchronization Functions

Function

Description

pg_export_snapshot () → text 保存事务当前的快照，并返回一个用于标识快照的 text 字符串。此字符串必须传递给（在数据库外部）想要导入快照的客户端。快照仅在导出的事务结束前可供导入。如有需要，一个事务可以导出多个快照。请注意，仅在 READ COMMITTED 事务中这样做有意义，因为在 REPEATABLE READ 和更高的隔离级别中，事务在其整个生命周期中使用相同的快照。一旦事务导出了任何快照，便不能使用 PREPARE TRANSACTION 准备它。

pg_log_standby_snapshot () → pg_lsn 拍摄正在运行的事务的快照，并将其写入 WAL，而无需等待 bgwriter 或检测点记录仪记录一个。这对于备用数据库中的逻辑解码很有用，因为逻辑槽创建必须等到此类记录在备用数据库中重放后。

9.27.6. Replication Management Functions #

Table 9.95 中所示的函数用于控制和与复制功能交互。有关基础功能的信息，请参见 Section 27.2.5、 Section 27.2.6 和 Chapter 50。默认情况下，只有超级用户可以复制原点函数，但是通过使用 GRANT 命令可以让其他用户有此权限。只有超级用户和具有 REPLICATION 权限的用户才能使用复制槽函数。

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

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

Table 9.95. Replication Management Functions

Function

Description

pg_create_physical_replication_slot ( slot_name name [, immediately_reserve boolean , temporary boolean ] ) → record ( slot_name name , lsn pg_lsn )创建名为 slot_name 的新物理复制槽。可选的第二个参数为 true 时，指定此复制槽的 LSN 立即保留；否则，LSN 将在从流复制客户端的第一次连接时保留。仅可使用流复制协议从物理槽流式传输更改——参见 Section 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 )创建名为 slot_name 的新逻辑（解码）复制槽，使用输出插件 plugin 。可选的第三个参数 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 的物理复制槽。已复制的物理槽开始从与源槽相同的 LSN 保留 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 的逻辑复制槽，可以选择更改输出插件和持久性。已复制的逻辑槽从与源逻辑槽相同的 LSN 开始。 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 将当前事务标记为重播在给定的 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 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. Database Object Management Functions #

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

Table 9.96. Database Object Size Functions

Function

Description

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 计算由指定关系的一个“分支”使用的磁盘空间。（请注意，对于大多数目的，使用更高级别的函数 pg_total_relation_size 或 pg_table_size 更方便，这些函数对所有分支的大小求和。）使用单一自变量时，此函数将返回关系的主数据分支的大小。可以提供第二个自变量来指定要检查的分支： main 返回关系的主数据分支的大小。 fsm 返回与关系关联的空闲空间映射（请参阅 Section 73.3 ）的大小。 vm 返回与关系关联的可视性映射（请参阅 Section 73.4 ）的大小。 init 如果存在，则返回与关系关联的初始化分支的大小。

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 计算指定表使用的总磁盘空间，包括所有索引和 TOAST 数据。该结果相当于 pg_table_size + pg_indexes_size 。

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

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

Table 9.97. Database Object Location Functions

Function

Description

pg_relation_filenode ( relation regclass ) → oid 返回当前分配给指定关系的“文件节点”号。文件节点是用于该关系的文件名的基本组成部分（有关详细信息，请参见 Section 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 。

Table 9.98 列出用于管理校对规则的函数。

Table 9.98. Collation Management Functions

Function

Description

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 所使用的；有关详细信息，请参见 Section 24.2.2 。如果以后在操作系统中安装了其他语言环境，则可以再次运行此函数为新语言环境添加排序规则。将跳过与 pg_collation 中现有条目匹配的语言环境。（但此函数不会删除基于不再存在于操作系统中的语言环境的排序规则对象。） schema 参数通常为 pg_catalog ，但这不是必需的；排序规则也可以安装到其他模式中。该函数返回它创建的新排序规则对象的数目。此函数的使用仅限于超级用户。

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

Table 9.99. Partitioning Information Functions

Function

Description

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. Index Maintenance Functions #

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

Table 9.100. Index Maintenance Functions

Function

Description

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 选项的详细信息，请参见 Section 70.4.1 和 Section 70.5 。

9.27.9. Generic File Access Functions #

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

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

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

其中一些函数采用可选的 missing_ok 参数，当文件或目录不存在时，指定行为。如果为 true，则函数根据需要返回 NULL 或空结果集。如果为 false，则会引发一个错误。（无论如何，除“未找到文件”之外的故障条件都会作为错误进行报告。）默认值为 false。

Table 9.101. Generic File Access Functions

Function

Description

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. Advisory Lock Functions #

Table 9.102 中显示的函数管理咨询锁。有关正确使用这些函数的详细信息，请参见 Section 13.3.5。

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

Table 9.102. Advisory Lock Functions

Function

Description

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 。