这一节描述的函数被用来控制和监视一个 PostgreSQL 安装。
表 9.89 展示了那些可以用于查询以及修改运行时配置参数的函数。
表 9.89. 配置设定函数
函数
描述
示例
|
|---|
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.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）。一个活动后端的进程 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.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.92 中展示的函数提供有关备库当前状态的信息。这些函数可以在恢复或普通运行过程中被执行。
表 9.92. 恢复信息函数
函数
描述
|
|---|
pg_is_in_recovery ()
→ boolean
如果恢复仍在进行则返回真。
|
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
如果已请求暂停恢复，则返回真。
|
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 生成速度和可用磁盘空间。
PostgreSQL 允许数据库会话同步它们的快照。一个快照决定对于正在使用该快照的事务哪些数据是可见的。当两个或者更多个会话需要看到数据库中的相同内容时，就需要同步快照。如果两个会话独立开始其事务，就总是有可能有某个第三事务在两个 START TRANSACTION 命令的执行之间提交，这样其中一个会话就可以看到该事务的效果而另一个则看不到。
为了解决这个问题，PostgreSQL 允许一个事务导出它正在使用的快照。只要导出快照的事务仍然保持打开，其他事务可以导入它的快照，并且因此可以保证它们可以看到和第一个事务看到的完全一样的数据库视图。但是注意这些事务中的任何一个对数据库所作的更改对其他事务仍然保持不可见，和未提交事务所作的修改一样。因此这些事务是针对以前存在的数据同步，而对由它们自己所作的更改则采取正常的动作。
如表 9.94 中所示，快照通过 pg_export_snapshot 函数导出，并且通过 SET TRANSACTION 命令导入。
表 9.94. 快照同步函数
函数
描述
|
|---|
pg_export_snapshot ()
→ text
保存事务的当前快照并返回 text 字符串以标识该快照。必须将此字符串传递（在数据库之外）给希望导入快照的客户端。快照仅在导出它的事务结束之前才可用于导入。
如果需要的话，一个事务可以导出多个快照。请注意，这样做仅在 READ COMMITTED 事务中有用，因为在 REPEATABLE READ 和更高的隔离级别中，事务在它们的生命周期中使用相同的快照。一旦事务导出了快照，它就不能用 PREPARE TRANSACTION 进行预备。
|
pg_log_standby_snapshot ()
→ pg_lsn
为进行中的事务拍摄快照并将其写入 WAL，无须等待后台写入器或检查点进程记录快照。这对备用服务器上的逻辑解码很有用，因为创建逻辑复制槽必须等待此类记录在备用服务器上重放。
|
表 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 时，指定立即为此复制槽保留 LSN；否则在流复制客户端首次连接时保留 LSN。从物理槽流式传输更改只能使用流复制协议 — 参见第 55.4 节。可选的第三个参数 temporary 为真时，指定该槽不永久存储到磁盘，且仅供当前会话使用。发生任何错误时，临时槽也会被释放。此函数对应复制协议命令 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，当设置为真时，指定槽不应永久存储到磁盘，仅供当前会话使用。临时槽也会在任何错误发生时释放。可选的第四个参数 twophase，当设置为真时，指定为此槽启用预备事务的解码。调用此函数的效果与复制协议命令 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
如果在当前会话中选择了复制源则返回真。
|
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.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
计算指定关系的一个“分支”所使用的磁盘空间。（注意在大多数情况下，使用更高级的函数 pg_total_relation_size 或 pg_table_size 更方便，它们将所有分支的大小相加。）使用一个参数，这将返回关系的主数据分支的大小。第二个参数可以用来指定要检查哪个分支：
main 返回关系的主数据分支的大小。
fsm 返回与该关系关联的空闲空间映射（参见第 73.3 节）的大小。
vm 返回与该关系相关联的可见性映射（参见第 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 数据类型的输入转换器会代为查找。详见第 8.19 节。
表 9.97 中展示的函数帮助标识数据库对象相关的磁盘文件。
表 9.97. 数据库对象位置函数
函数
描述
|
|---|
pg_relation_filenode ( relation regclass )
→ oid
返回当前分配给指定关系的“文件节点”编号。文件节点是关系所用文件名的基本组成部分（更多信息见第 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 的反向映射。对于数据库默认表空间中的关系，表空间可以指定为 0。如果当前数据库中没有与给定值关联的关系，或者该关系是临时关系，则返回 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.100 显示了索引维护任务可以使用的函数。（注意，这些维护任务通常由 autovacuum 自动完成；只有在特殊情况下才需要使用这些函数。）这些函数在恢复过程中无法执行。这些函数的使用局限于超级用户和给定索引的所有者。
表 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.101 中展示的函数提供了对数据库服务器所在机器上的文件的本地访问。只能访问数据库集簇目录以及 log_directory 中的文件，除非用户是超级用户或者被授予了角色 pg_read_server_files。使用相对路径访问集簇目录里面的文件，并使用匹配 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.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，而不等待。
|