==================  系统管理函数 ================== .. container:: sect1 :name: FUNCTIONS-ADMIN .. container:: titlepage .. container:: .. container:: .. rubric:: 9.26. 系统管理函数 :name: 系统管理函数 :class: title .. container:: toc `9.26.1. 配置设定函数 `__ `9.26.2. 服务器信号函数 `__ `9.26.3. 备份控制函数 `__ `9.26.4. 恢复控制函数 `__ `9.26.5. 快照同步函数 `__ `9.26.6. 复制函数 `__ `9.26.7. 数据库对象管理函数 `__ `9.26.8. 索引维护函数 `__ `9.26.9. 通用文件访问函数 `__ `9.26.10. 咨询锁函数 `__ 这一节描述的函数被用来控制和监视一个PostgreSQL安装。 .. container:: sect2 :name: FUNCTIONS-ADMIN-SET .. container:: titlepage .. container:: .. container:: .. rubric:: 9.26.1. 配置设定函数 :name: 配置设定函数 :class: title `表 9.82 `__\ 展示了那些可以用于查询以及修改运行时配置参数的函数。 .. container:: table :name: FUNCTIONS-ADMIN-SET-TABLE **表 9.82. 配置设定函数** .. container:: table-contents +----------------------------+----------+------------------------+ | 名称 | 返回类型 | 描述 | +============================+==========+========================+ | | ``text`` | 获得设置的当前值 | | ``curr | | | | ent_setting(setting_name`` | | | | [, *``missing_ok``* ]) | | | +----------------------------+----------+------------------------+ | | ``text`` | 设置一个参数并返回新值 | | `` | | | | set_config(setting_name``, | | | | *``new_value``*, | | | | *``is_local``*) | | | +----------------------------+----------+------------------------+ ``current_setting``\ 得到\ *``setting_name``*\ 设置的当前值。它对应于SQL命令\ ``SHOW``\ 。一个例子： .. code:: programlisting 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``\ ，那么新值将只应用于当前事务。 如果你希望新值应用于当前会话，那么应该使用\ ``false``\ 。 它等效于 SQL 命令 ``SET``\ 。例如： .. code:: programlisting SELECT set_config('log_statement_stats', 'off', false); set_config ------------ off (1 row) .. container:: sect2 :name: FUNCTIONS-ADMIN-SIGNAL .. container:: titlepage .. container:: .. container:: .. rubric:: 9.26.2. 服务器信号函数 :name: 服务器信号函数 :class: title 在\ `表 9.83 `__\ 中展示的函数向其它服务器进程发送控制信号。默认情况下这些函数只能被超级用户使用，但是如果需要，可以利用\ ``GRANT``\ 把访问特权授予给其他用户。 .. container:: table :name: FUNCTIONS-ADMIN-SIGNAL-TABLE **表 9.83. 服务器信号函数** .. container:: table-contents +--------------------------+-------------+--------------------------+ | 名称 | 返回类型 | 描述 | +==========================+=============+==========================+ | ` | ``boolean`` | 取 | | `pg_cancel_backend(pid`` | | 消一个后端的当前查询。如 | | ``int``) | | 果调用角色是被取消后端的 | | | | 拥有者角色的成员或者调用 | | | | 角色已经被授予\ ``pg_si | | | | gnal_backend``\ ，这也是 | | | | 允许的，不过只有超级用户 | | | | 才能取消超级用户的后端。 | +--------------------------+-------------+--------------------------+ | ``pg_reload_conf()`` | ``boolean`` | 导致服务 | | | | 器进程重载它们的配置文件 | +--------------------------+-------------+--------------------------+ | ``pg_rotate_logfile()`` | ``boolean`` | 切换服务器的日志文件 | +--------------------------+-------------+--------------------------+ | ``pg | ``boolean`` | 中止一个后端。如 | | _terminate_backend(pid`` | | 果调用角色是被取消后端的 | | ``int``) | | 拥有者角色的成员或者调用 | | | | 角色已经被授予\ ``pg_si | | | | gnal_backend``\ ，这也是 | | | | 允许的，不过只有超级用户 | | | | 才能取消超级用户的后端。 | +--------------------------+-------------+--------------------------+ 这些函数中的每一个都在成功时返回\ ``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_reload_conf``\ 给服务器发送一个SIGHUP信号， 导致所有服务器进程重载配置文件。 ``pg_rotate_logfile``\ 给日志文件管理器发送信号，告诉它立即切换到一个新的输出文件。这个函数只有在内建日志收集器运行时才能工作，因为否则就不存在日志文件管理器子进程。 subprocess. .. container:: sect2 :name: FUNCTIONS-ADMIN-BACKUP .. container:: titlepage .. container:: .. container:: .. rubric:: 9.26.3. 备份控制函数 :name: 备份控制函数 :class: title `表 9.84 `__\ 中展示的函数可以辅助制作在线备份。这些函数不能在恢复期间执行（非排他性的\ ``pg_start_backup``\ ，非排他性的\ ``pg_stop_backup``\ ，\ ``pg_is_in_backup``\ 、\ ``pg_backup_start_time``\ 和\ ``pg_wal_lsn_diff``\ 除外）。 .. container:: table :name: FUNCTIONS-ADMIN-BACKUP-TABLE **表 9.84. 备份控制函数** .. container:: table-contents +----------------------+----------------------+----------------------+ | 名称 | 返回类型 | 描述 | +======================+======================+======================+ | ``pg_create_ | ``pg_lsn`` | 为执行 | | restore_point(name`` | | 恢复创建一个命名点（ | | ``text``) | | 默认只限于超级用户， | | | | 但是可以授予其他用户 | | | | EXECUTE | | | | 特权来执行该函数） | +----------------------+----------------------+----------------------+ | ``pg_curre | ``pg_lsn`` | 得到当前 | | nt_wal_flush_lsn()`` | | 的预写式日志刷写位置 | +----------------------+----------------------+----------------------+ | ``pg_curren | ``pg_lsn`` | 获得当 | | t_wal_insert_lsn()`` | | 前预写式日志插入位置 | +----------------------+----------------------+----------------------+ | ``pg | ``pg_lsn`` | 获得当 | | _current_wal_lsn()`` | | 前预写式日志写入位置 | +----------------------+----------------------+----------------------+ | ``pg_ | ``pg_lsn`` | 准备执行在 | | start_backup(label`` | | 线备份（默认只限于超 | | ``text`` [, | | 级用户或者复制角色， | | *``fast``* | | 但是可以授予其他用户 | | ``boolean`` [, | | EXECUTE | | *``exclusive``* | | 特权来执行该函数） | | ``boolean``]]) | | | +----------------------+----------------------+----------------------+ | ``pg_stop_backup()`` | ``pg_lsn`` | 完成执行排他的在 | | | | 线备份（默认只限于超 | | | | 级用户或者复制角色， | | | | 但是可以授予其他用户 | | | | EXECUTE | | | | 特权来执行该函数） | +----------------------+----------------------+----------------------+ | ``pg_sto | ``setof record`` | 结束执行排他 | | p_backup(exclusive`` | | 或者非排他的在线备份 | | ``boolean``) | | （ | | | | 默认只限于超级用户， | | | | 但是可以授予其他用户 | | | | EXECUTE | | | | 特权来执行该函数） | +----------------------+----------------------+----------------------+ | ` | ``bool`` | 如果一个在线排他备 | | `pg_is_in_backup()`` | | 份仍在进行中则为真。 | +----------------------+----------------------+----------------------+ | ``pg_b | ``timest | 获得一个进行中的在线 | | ackup_start_time()`` | amp with time zone`` | 排他备份的开始时间。 | +----------------------+----------------------+----------------------+ | ``pg_switch_wal()`` | ``pg_lsn`` | 强制切换到一个 | | | | 新的预写式日志文件（ | | | | 默认只限于超级用户， | | | | 但是可以授予其他用户 | | | | EXECUTE | | | | 特权来执行该函数） | +----------------------+----------------------+----------------------+ | ``p | ``pg_lsn`` | 转换预写式日 | | g_walfile_name(lsn`` | | 志位置字符串为文件名 | | ``text``) | | | +----------------------+----------------------+----------------------+ | ``pg_walfi | ``pg_lsn``, | 转换预写式日志位置 | | le_name_offset(lsn`` | ``integer`` | 字符串为文件名以及文 | | ``text``) | | 件内的十进制字节偏移 | +----------------------+----------------------+----------------------+ | ``p | ``numeric`` | 计算两个预 | | g_wal_lsn_diff(lsn`` | | 写式日志位置间的差别 | | ``pg_lsn``, | | | | *``lsn``* | | | | ``pg_lsn``) | | | +----------------------+----------------------+----------------------+ ``pg_start_backup``\ 接受一个参数，这个参数可以是备份的任意用户定义的标签（通常这是备份转储文件将被存储的名字）。当被用在排他模式中时，该函数向数据库集簇的数据目录写入一个备份标签文件（\ ``backup_label``\ ）和一个表空间映射文件（\ ``tablespace_map``\ ，如果在\ ``pg_tblspc/``\ 目录中有任何链接），执行一个检查点，然后以文本方式返回备份的起始预写式日志位置。用户可以忽略这个结果值，但是为了可能需要的场合我们还是提供该值。 当在非排他模式中使用时，这些文件的内容会转而由\ ``pg_stop_backup``\ 函数返回，并且应该由调用者写入到备份中去。 .. code:: programlisting 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``\ 类型的第二参数。如果为假，\ ``pg_stop_backup``\ 将在备份完成后立即返回而不等待WAL被归档。这种行为仅对独立监控WAL归档的备份软件有用。否则，让备份一致所要求的WAL可能会丢失，进而让备份变得毫无用处。当这个参数被设置为真时，在启用归档的前提下\ ``pg_stop_backup``\ 将等待WAL被归档，在后备服务器上，这意味只有\ ``archive_mode = always``\ 时才会等待。如果主服务器上的写活动很低，在主服务器上运行\ ``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``\ 从任何上述函数的结果中抽取相应的预写式日志文件名称以及字节偏移。例如： .. code:: programlisting postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); file_name | file_offset --------------------------+------------- 00000001000000000000000D | 4039624 (1 row) 相似地，\ ``pg_walfile_name``\ 只抽取预写式日志文件名。当给定的预写式日志位置正好在一个预写式日志文件的边界，这些函数都返回之前的预写式日志文件的名称。这对管理预写式日志归档行为通常是所希望的行为，因为前一个文件是当前需要被归档的最后一个文件。 ``pg_wal_lsn_diff``\ 以字节数计算两个预写式日志位置之间的差别。它可以和\ ``pg_stat_replication``\ 或\ `表 9.84 `__\ 中其他的函数一起使用来获得复制延迟。 .. container:: sect2 :name: FUNCTIONS-RECOVERY-CONTROL .. container:: titlepage .. container:: .. container:: .. rubric:: 9.26.4. 恢复控制函数 :name: 恢复控制函数 :class: title `表 9.85 `__\ 中展示的函数提供有关后备机当前状态的信息。这些函数可以在恢复或普通运行过程中被执行。 .. container:: table :name: FUNCTIONS-RECOVERY-INFO-TABLE **表 9.85. 恢复信息函数** .. container:: table-contents +----------------------+----------------------+----------------------+ | 名称 | 返回类型 | 描述 | +======================+======================+======================+ | ``p | ``bool`` | 如果恢 | | g_is_in_recovery()`` | | 复仍在进行中，为真。 | +----------------------+----------------------+----------------------+ | ``pg_last | ``pg_lsn`` | 获得最后一个收到 | | _wal_receive_lsn()`` | | 并由流复制同步到磁盘 | | | | 的预写式日志位置。当 | | | | 流复制在进行中时，这 | | | | 将单调增加。如果恢复 | | | | 已经完成，这将保持静 | | | | 止在恢复过程中收到并 | | | | 同步到磁盘的最后一个 | | | | WAL | | | | 记录。如果流 | | | | 复制被禁用，或者还没 | | | | 有被启动，该函数返回 | | | | NULL。 | +----------------------+----------------------+----------------------+ | ``pg_las | ``pg_lsn`` | 获得恢复过程中被重 | | t_wal_replay_lsn()`` | | 放的最后一个预写式日 | | | | 志位置。当流复制在进 | | | | 行中时，这将单调增加 | | | | 。如果恢复已经完成， | | | | 这将保持静止在恢复过 | | | | 程中被应用的最后一个 | | | | WAL | | | | 记录。如 | | | | 果服务器被正常启动而 | | | | 没有恢复，该函数返回 | | | | NULL。 | +----------------------+----------------------+----------------------+ | ``pg_last_xact_ | ``timest | 获得恢复过程中被重 | | replay_timestamp()`` | amp with time zone`` | 放的最后一个事务的时 | | | | 间戳。这是在主机上产 | | | | 生的事务的提交或中止 | | | | WAL | | | | 记录的时间。如果 | | | | 在恢复过程中没有事务 | | | | 被重放，这个函数返回 | | | | NULL。否则，如 | | | | 果恢复仍在进行这将单 | | | | 调增加。如果恢复已经 | | | | 完成，则这个值会保持 | | | | 静止在恢复过程中最后 | | | | 一个被应用的事务。如 | | | | 果服务器被正常启动而 | | | | 没有恢复，该函数返回 | | | | NULL。 | +----------------------+----------------------+----------------------+ `表 9.86 `__\ 中展示的函数空值恢复的进程。这些函数只能在恢复过程中被执行。 .. container:: table :name: FUNCTIONS-RECOVERY-CONTROL-TABLE **表 9.86. 恢复控制函数** .. container:: table-contents +--------------------------+-------------+--------------------------+ | 名称 | 返回类型 | 描述 | +==========================+=============+==========================+ | ``pg_ | ``bool`` | 如果恢复被暂停，为真。 | | is_wal_replay_paused()`` | | | +--------------------------+-------------+--------------------------+ | ``pg_promote(wait`` | ``boolean`` | 促进物理备用服务器。 当 | | ``boolean`` DEFAULT | | *``wait``* | | true, *``wait_seconds``* | | \ 设置为\ ``true``\ （默 | | ``integer`` DEFAULT 60) | | 认值）时，该函数将等待晋 | | | | 升完成或\ *``wait_second | | | | s``*\ 秒，如果晋升成功， | | | | 则返回\ ``true``\ ，否则 | | | | 返回\ ``false``\ 。如果 | | | | \ *``wait``*\ 被设置为\ | | | | ``false``\ ，则会返回\ | | | | ``true``\ 。函数在发送后 | | | | 立即返回\ ``true``\ 。\ | | | | ``SIGUSR1``\ 给postmast | | | | er触发推广。此功能默认只 | | | | 限于超级用户，但其他用户 | | | | 可以被 | | | | 授予EXECUTE来运行函数。 | +--------------------------+-------------+--------------------------+ | ` | ``void`` | 立即暂停恢 | | `pg_wal_replay_pause()`` | | 复（默认仅限于超级用户, | | | | 但是可以授予其他用户 | | | | EXECUTE | | | | 特权来执行该函数）。 | +--------------------------+-------------+--------------------------+ | `` | ``void`` | 如果恢复被暂停， | | pg_wal_replay_resume()`` | | 重启之（默认仅限于超级用 | | | | 户，但是可以授予其他用户 | | | | EXECUTE | | | | 特权来执行该函数）。 | +--------------------------+-------------+--------------------------+ 在恢复被暂停时，不会有进一步的数据库改变被应用。如果在热备模式，所有新的查询将看到数据库的同一个一致快照，并且在恢复被继续之前不会有更多查询冲突会产生。 如果流复制被禁用，暂停状态可以无限制地继续而不出问题。在流复制进行时，WAL 记录将继续被接收，最后将会填满可用的磁盘空间，取决于暂停的持续时间、WAL 的产生率和可用的磁盘空间。 .. container:: sect2 :name: FUNCTIONS-SNAPSHOT-SYNCHRONIZATION .. container:: titlepage .. container:: .. container:: .. rubric:: 9.26.5. 快照同步函数 :name: 快照同步函数 :class: title PostgreSQL允许数据库会话同步它们的快照。一个\ *快照*\ 决定对于正在使用该快照的事务哪些数据是可见的。当两个或者更多个会话需要看到数据库中的相同内容时，就需要同步快照。如果两个会话独立开始其事务，就总是有可能有某个第三事务在两个\ ``START TRANSACTION``\ 命令的执行之间提交，这样其中一个会话就可以看到该事务的效果而另一个则看不到。 为了解决这个问题，PostgreSQL允许一个事务\ *导出*\ 它正在使用的快照。只要导出的事务仍然保持打开，其他事务可以\ *导入*\ 它的快照，并且因此可以保证它们可以看到和第一个事务看到的完全一样的数据库视图。但是注意这些事务中的任何一个对数据库所作的更改对其他事务仍然保持不可见，和未提交事务所作的修改一样。因此这些事务是针对以前存在的数据同步，而对由它们自己所作的更改则采取正常的动作。 如\ `表 9.87 `__\ 中所示，快照通过\ ``pg_export_snapshot``\ 函数导出，并且通过\ `SET TRANSACTION `__\ 命令导入。 .. container:: table :name: FUNCTIONS-SNAPSHOT-SYNCHRONIZATION-TABLE **表 9.87. 快照同步函数** .. container:: table-contents ======================== ======== ============================ 名称 返回类型 描述 ======================== ======== ============================ ``pg_export_snapshot()`` ``text`` 保存当前快照并返回它的标识符 ======================== ======== ============================ 函数\ ``pg_export_snapshot``\ 保存当前的快照并且返回一个\ ``text``\ 串标识该快照。该字符串必须被传递（到数据库外）给希望导入快照的客户端。直到导出快照的事务的末尾，快照都可以被导入。如果需要，一个事务可以导出多于一个快照。注意这样做只在 ``READ COMMITTED``\ 事务中有用，因为在\ ``REPEATABLE READ``\ 和更高隔离级别中，事务在它们的生命期中都使用同一个快照。一旦一个事务已经导出了任何快照，它不能使用\ `PREPARE TRANSACTION `__\ 。 关于如何使用一个已导出快照的细节请见\ `SET TRANSACTION `__. .. container:: sect2 :name: FUNCTIONS-REPLICATION .. container:: titlepage .. container:: .. container:: .. rubric:: 9.26.6. 复制函数 :name: 复制函数 :class: title `表 9.88 `__\ 中展示的函数 用于控制以及与复制特性交互。 复制原点函数的使用仅限于超级用户。 复制槽的函数只限于超级用户和拥有\ ``REPLICATION``\ 权限的用户。 很多这些函数在复制协议中都有等价的命令。 .. container:: table :name: FUNCTIONS-REPLICATION-TABLE **表 复制 SQL 函数** .. container:: table-contents +----------------------+----------------------+----------------------+ | 函数 | 返回类型 | 描述 | +======================+======================+======================+ | | (*``slot_name``* | 创建一个新的名 | | ``pg_crea | ``name``, | 为\ *``slot_name``* | | te_physical_replicat | *``xlog_position``* | \ 的物理复制槽。第二 | | ion_slot(slot_name`` | ``pg_lsn``) | 个参数是可选的，当它 | | ``name`` [, | | 为\ ``true``\ 时，立 | | *``im | | 即为这个物理槽指定要 | | mediately_reserve``* | | 被保留的LSN。否则该 | | ``boolean``]) | | LSN会被保留在来自一 | | | | 个流复制客户端的第一 | | | | 个连接上。来自一个物 | | | | 理槽的流改变只可能出 | | | | 现在使用流复制协议时 | | | | — | | | | 见\ `第 52 | | | | .4 节 `__\ 。 | | | | 当可选的第三参数\ * | | | | ``temporary``*\ 被设 | | | | 置为真时，指定那个槽 | | | | 不会被持久地存储在磁 | | | | 盘上并且仅对当前会话 | | | | 的使用有意义。临时槽 | | | | 也会在发生任何错误时 | | | | 被释放。这个函数对应 | | | | 于复制协议命令\ ``CR | | | | EATE_REPLICATION_SLO | | | | T ... PHYSICAL``\ 。 | +----------------------+----------------------+----------------------+ | | ``void`` | 丢弃名为 | | ``pg_drop_replicat | | \ *``slot_name``*\ | | ion_slot(slot_name`` | | 的物理或逻辑复制槽。 | | ``name``) | | 和复制协议命令\ ``D | | | | ROP_REPLICATION_SLOT | | | | ``\ 相同。对于逻辑槽 | | | | ，在连接到在其中创建 | | | | 该槽的同一个数据库时 | | | | ，必须调用这个函数。 | +----------------------+----------------------+----------------------+ | | (*``slot_name``* | 使用输出插件\ *``plu | | ``pg_cre | ``name``, *``lsn``* | gin``*\ 创建一个名为 | | ate_logical_replicat | ``pg_lsn``) | *``slot_name``*\ 的 | | ion_slot(slot_name`` | | 新逻辑（解码）复制槽 | | ``name``, | | 。当可选的第三参数\ | | *``plugin``* | | *``temporary``*\ 被 | | ``name``) | | 设置为真时，指定那个 | | | | 槽不会被持久地存储在 | | | | 磁盘上并且仅对当前会 | | | | 话的使用有意义。临时 | | | | 槽也会在发生任何错误 | | | | 时被释放。对这个函数 | | | | 的调用与复制协议命令 | | | | ``CREATE_REPLICAT | | | | ION_SLOT ... LOGICAL | | | | ``\ 具有相同的效果。 | +----------------------+----------------------+----------------------+ | | (*``slot_name``* | 将一个名为\ * | | ``pg_copy_p | ``name``, *``lsn``* | ``src_slot_name``*\ | | hysical_replication_ | ``pg_lsn``) | 的现有物理复制槽复制 | | slot(src_slot_name`` | | 到一个名为\ *``dst_ | | ``name``, | | slot_name``*\ 的物理 | | *``dst_slot_name``* | | 复制槽。被复制的物理 | | ``name`` [, | | 槽开始从与源槽相同的 | | *``temporary``* | | LSN开始保留WAL。\ * | | ``boolean``]) | | ``temporary``*\ 是可 | | | | 选的。如果省略了\ * | | | | ``temporary``*\ ，则 | | | | 使用与源槽相同的值。 | +----------------------+----------------------+----------------------+ | | (*``slot_name``* | 复制一 | | ``pg_copy_ | ``name``, *``lsn``* | 个名为\ *``src_slot | | logical_replication_ | ``pg_lsn``) | _name``*\ 的现有逻辑 | | slot(src_slot_name`` | | 复制槽。到一个名为\ | | ``name``, | | *``dst_slot_name``* | | *``dst_slot_name``* | | \ 的逻辑复制槽。同时 | | ``name`` [, | | 改变输出插件和持久性 | | *``temporary``* | | 。被复制的逻辑槽开始 | | ``boolean`` [, | | 来自与源逻辑 | | *``plugin``* | | 槽相同的LSN。这两个 | | ``name``]]) | | *``temporary``*\ 和 | | | | \ *``plugin``*\ 是可 | | | | 选的。如果省略了\ * | | | | ``temporary``*\ 或\ | | | | *``plugin``*\ 。使用 | | | | 与源逻辑槽相同的值。 | +----------------------+----------------------+----------------------+ | | (*``lsn``* | 返回槽\ | | ` | ``pg_lsn``, | *``slot_name``*\ 中 | | `pg_logical_slot_get | *``xid``* ``xid``, | 的改变，从上一次已经 | | _changes(slot_name`` | *``data``* ``text``) | 被消费的点开始返回。 | | ``name``, | | 如果\ *`` | | *``upto_lsn``* | | upto_lsn``*\ 和\ *`` | | ``pg_lsn``, | | upto_nchanges``*\ 为 | | *``upto_nchanges``* | | NULL，逻辑解码将一 | | ``int``, VARIADIC | | 直继续到 WAL | | *``options``* | | 的末尾。如果\ | | ``text[]``) | | *``upto_lsn``*\ 为非 | | | | NULL， | | | | 解码将只包括那些在指 | | | | 定 LSN | | | | 之前提交 | | | | 的事务。如果\ *``up | | | | to_nchanges``*\ 为非 | | | | NULL， | | | | 解码将在其 | | | | 产生的行数超过指定值 | | | | 后停止。不过要注意， | | | | 被 | | | | 返回的实际行数可能更 | | | | 大，因为对这个限制的 | | | | 检查只会在增加了解码 | | | | 每个新的提交事务产生 | | | | 的行之后进行。 | +----------------------+----------------------+----------------------+ | | (*``lsn``* ``text``, | 行为就像\ ` | | `` | *``xid``* ``xid``, | `pg_logical_slot_get | | pg_logical_slot_peek | *``data``* ``text``) | _changes()``\ 函数， | | _changes(slot_name`` | | 不过改变不会被消费， | | ``name``, | | 即在未来的调用 | | *``upto_lsn``* | | 中还会返回这些改变。 | | ``pg_lsn``, | | | | *``upto_nchanges``* | | | | ``int``, VARIADIC | | | | *``options``* | | | | ``text[]``) | | | +----------------------+----------------------+----------------------+ | | (*``lsn``* | 行为就像\ ` | | ``pg_log | ``pg_lsn``, | `pg_logical_slot_get | | ical_slot_get_binary | *``xid``* ``xid``, | _changes()``\ 函数， | | _changes(slot_name`` | *``data``* | 不过改变会以 | | ``name``, | ``bytea``) | \ ``bytea``\ 返回。 | | *``upto_lsn``* | | | | ``pg_lsn``, | | | | *``upto_nchanges``* | | | | ``int``, VARIADIC | | | | *``options``* | | | | ``text[]``) | | | +----------------------+----------------------+----------------------+ | | (*``lsn``* | 行为就像\ ` | | ``pg_logi | ``pg_lsn``, | `pg_logical_slot_get | | cal_slot_peek_binary | *``xid``* ``xid``, | _changes()``\ 函数， | | _changes(slot_name`` | *``data``* | 不过改变会以\ | | ``name``, | ``bytea``) | ``bytea``\ 返回并且 | | *``upto_lsn``* | | 这些改变不会被消费， | | ``pg_lsn``, | | 即在未来的调用 | | *``upto_nchanges``* | | 中还会返回这些改变。 | | ``int``, VARIADIC | | | | *``options``* | | | | ``text[]``) | | | +----------------------+----------------------+----------------------+ | | (*``slot_name``* | 将复 | | ` | ``name``, | 制槽的当前确认的位置 | | `pg_replication_slot | *``end_lsn``* | 提前到名为\ *``slot | | _advance(slot_name`` | ``pg_lsn``) ``bool`` | _name``*\ 的复制槽的 | | ``name``, | | 当前确认位置。该槽不 | | *``upto_lsn``* | | 会向后移动，也不会移 | | ``pg_lsn``) | | 动到当前插入位置之外 | | | | 。返回该槽的名称和它 | | | | 被推进到的真实位置。 | | | | 如果有任何推进，则在 | | | | 后续的检查点中写出更 | | | | 新后的槽的信息。如果 | | | | 发生崩溃，该槽位可能 | | | | 会返回到之前的位置。 | +----------------------+----------------------+----------------------+ | | ``oid`` | 用给定的外部名 | | `` | | 称创建一个复制源，并 | | pg_replication_origi | | 且返回分配给它的内部 | | n_create(node_name`` | | id。 | | ``text``) | | | +----------------------+----------------------+----------------------+ | | ``void`` | 删除一个之 | | ``pg_replication_ori | | 前创建的复制源，包括 | | gin_drop(node_name`` | | 任何相关的重放进度。 | | ``text``) | | | +----------------------+----------------------+----------------------+ | | ``oid`` | 用名称查 | | ``pg_replication_or | | 找复制源并且返回内部 | | igin_oid(node_name`` | | id。如果 | | ``text``) | | 没有找到则抛出错误。 | +----------------------+----------------------+----------------------+ | | ``void`` | 把当 | | ``pg_repl | | 前会话标记为正在从给 | | ication_origin_sessi | | 定的源进行重放，允许 | | on_setup(node_name`` | | 重放进度被跟踪。使用 | | ``text``) | | ``pg_repl | | | | ication_origin_sessi | | | | on_reset``\ 可以取消 | | | | 标记。只有之前没有 | | | | 源被配置时才能使用。 | +----------------------+----------------------+----------------------+ | | ``void`` | 取消\ ``pg_replic | | ` | | ation_origin_session | | `pg_replication_orig | | _setup()``\ 的效果。 | | in_session_reset()`` | | | +----------------------+----------------------+----------------------+ | | ``bool`` | 当前会话中是否已 | | ``pg | | 经配置了一个复制源？ | | _replication_origin_ | | | | session_is_setup()`` | | | +----------------------+----------------------+----------------------+ | | ``pg_lsn`` | 返 | | ``pg_rep | | 回当前会话中配置的复 | | lication_origin_sess | | 制源的重放位置。参数 | | ion_progress(flush`` | | * | | ``bool``) | | ``flush``*\ 决定对应 | | | | 的本地事务是否被确保 | | | | 已经刷入磁盘。 | +----------------------+----------------------+----------------------+ | | ``void`` | 标 | | ``pg_re | | 记当前事务为正在重放 | | plication_origin_xac | | 一个已经在给定的LSN | | t_setup(origin_lsn`` | | 和时间戳提交的事 | | ``pg_lsn``, | | 务。只有当之前已经用 | | *` | | ``pg_repl | | `origin_timestamp``* | | ication_origin_sessi | | ``timestamptz``) | | on_setup()``\ 配置过 | | | | 一个 | | | | 复制源时才能被调用。 | +----------------------+----------------------+----------------------+ | | ``void`` | 取消\ ``pg_rep | | ``pg_replication_o | | lication_origin_xact | | rigin_xact_reset()`` | | _setup()``\ 的效果。 | +----------------------+----------------------+----------------------+ | | ``void`` | 把给 | | ``p | | 定节点的复制进度设置 | | g_replication_origin | | 为给定的位置。这主要 | | _advance(node_name`` | | 用于配置更改或者类似 | | ``text``, *``pos``* | | 操作 | | ``pg_lsn``) | | 之后设置初始位置或者 | | | | 新位置。注意这个函数 | | | | 的不当使用可能会导致 | | | | 不一致的复制数据。 | +----------------------+----------------------+----------------------+ | | ``pg_lsn`` | 返回给定复 | | ``pg | | 制元的重放位置。参数 | | _replication_origin_ | | * | | progress(node_name`` | | ``flush``*\ 决定对应 | | ``text``, | | 的本地事务是否被确保 | | *``flush``* | | 已经刷入磁盘。 | | ``bool``) | | | +----------------------+----------------------+----------------------+ | | ``pg_lsn`` | 发出 | | ` | | 文本形式的逻辑解码消 | | `pg_logical_emit_mes | | 息。这可以被用来通过 | | sage(transactional`` | | WAL | | ``bool``, | | 向逻辑解码 | | *``prefix``* | | 插件传递一般消息。参 | | ``text``, | | 数\ *``transactiona | | *``content``* | | l``*\ 指定该消息是否 | | ``text``) | | 应该是当前事务的一部 | | | | 分或者当逻辑解码读到 | | | | 该记录时该消息是否应 | | | | 该被立刻写入并且解码 | | | | 。\ *``prefix``*\ 是 | | | | 逻辑解码插件用来识别 | | | | 它们感兴趣的消息的文 | | | | 本前缀。\ *``conten | | | | t``*\ 是消息的文本。 | +----------------------+----------------------+----------------------+ | ` | ``pg_lsn`` | 发出二进制 | | `pg_logical_emit_mes | | 逻辑解码消息。这可以 | | sage(transactional`` | | 被用来通过WAL向逻辑 | | ``bool``, | | 解码插件传递一般性消 | | *``prefix``* | | 息。参数\ *``transa | | ``text``, | | ctional``*\ 指定该消 | | *``content``* | | 息是否应该成为当前事 | | ``bytea``) | | 务的一部分或者是否应 | | | | 该在逻辑解码过程读到 | | | | 该记录时立刻进行写入 | | | | 和解码。参数\ *``pre | | | | fix``*\ 是一个逻辑解 | | | | 码插件使用的文本前缀 | | | | ，逻辑解码插件用它来 | | | | 识别感兴趣的消息。参 | | | | 数\ *``content``*\ | | | | 是消息的二进制内容。 | +----------------------+----------------------+----------------------+ .. container:: sect2 :name: FUNCTIONS-ADMIN-DBOBJECT .. container:: titlepage .. container:: .. container:: .. rubric:: 9.26.7. 数据库对象管理函数 :name: 数据库对象管理函数 :class: title `表 9.89 `__\ 中展示的函数计算数据库对象使用的磁盘空间。 .. container:: table :name: FUNCTIONS-ADMIN-DBSIZE **表 9.89. 数据库对象尺寸函数** .. container:: table-contents +---------------------------+------------+---------------------------+ | 名称 | 返回类型 | 描述 | +===========================+============+===========================+ | ``pg_column_size(any``) | ``int`` | 存储一个特定值（ | | | | 可能压缩过）所需的字节数 | +---------------------------+------------+---------------------------+ | ``pg_database_size(oid``) | ``bigint`` | 指定 OID | | | | 的数据库使用的磁盘空间 | +---------------------------+------------+---------------------------+ | ` | ``bigint`` | 指定名 | | `pg_database_size(name``) | | 称的数据库使用的磁盘空间 | +---------------------------+------------+---------------------------+ | ``pg | ``bigint`` | 附加到指定 | | _indexes_size(regclass``) | | 表的索引所占的总磁盘空间 | +---------------------------+------------+---------------------------+ | ``pg | ``bigint`` | 指定表或索引的指定分叉（ | | _relation_size(relation`` | | \ ``'main'``\ 、\ ``'fsm' | | ``regclass``, *``fork``* | | ``\ 、\ ``'vm'``\ 或\ ``' | | ``text``) | | init'``\ ）使用的磁盘空间 | +---------------------------+------------+---------------------------+ | ``pg | ``bigint`` | ``pg_relation_ | | _relation_size(relation`` | | size(..., 'main')的简写`` | | ``regclass``) | | | +---------------------------+------------+---------------------------+ | ``pg_size_bytes(text``) | ``bigint`` | 把人类可读格式的带 | | | | 有单位的尺寸转换成字节数 | +---------------------------+------------+---------------------------+ | ` | ``text`` | 将表示成一个 | | `pg_size_pretty(bigint``) | | 64位整数的字节尺寸转换为 | | | | 带尺寸单位的人类可读格式 | +---------------------------+------------+---------------------------+ | `` | ``text`` | 将表示成一 | | pg_size_pretty(numeric``) | | 个数字值的字节尺寸转换为 | | | | 带尺寸单位的人类可读格式 | +---------------------------+------------+---------------------------+ | `` | ``bigint`` | 被指定表使用的磁 | | pg_table_size(regclass``) | | 盘空间，排除索引（但包括 | | | | TOAST、空 | | | | 闲空间映射和可见性映射） | +---------------------------+------------+---------------------------+ | `` | ``bigint`` | 指定 OID | | pg_tablespace_size(oid``) | | 的表空间使用的磁盘空间 | +---------------------------+------------+---------------------------+ | ``p | ``bigint`` | 指定名 | | g_tablespace_size(name``) | | 称的表空间使用的磁盘空间 | +---------------------------+------------+---------------------------+ | ``pg_total_ | ``bigint`` | 指定表所用的总磁盘空间， | | relation_size(regclass``) | | 包括所有的索引和TOAST数据 | +---------------------------+------------+---------------------------+ ``pg_column_size``\ 显示用于存储任意独立数据值的空间。 ``pg_total_relation_size``\ 接受一个表或 TOAST 表的 OID 或名称，并返回该表所使用的总磁盘空间，包括所有相关的索引。这个函数等价于\ ``pg_table_size`` ``+`` ``pg_indexes_size``\ 。 ``pg_table_size``\ 接受一个表的 OID 或名称，并返回该表所需的磁盘空间，但是排除索引（TOAST 空间、空闲空间映射和可见性映射包含在内） ``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``\ 接受一个表、索引或 TOAST 表的 OID 或者名称，并且返回那个关系的一个分叉所占的磁盘空间的字节尺寸（注意 对于大部分目的，使用更高层的函数\ ``pg_total_relation_size`` 或者\ ``pg_table_size``\ 会更方便，它们会合计所有分叉的尺寸）。 如果只得到一个参数，它会返回该关系的主数据分叉的尺寸。提供第二个参数 可以指定要检查哪个分叉： .. container:: itemizedlist - ``'main'``\ 返回该关系主数据分叉的尺寸。 - ``'fsm'``\ 返回与该关系相关的空闲空间映射的尺寸。 - ``'vm'``\ 返回与该关系相关的可见性映射的尺寸。 - ``'init'``\ 返回与该关系相关的初始化分叉的尺寸。 ``pg_size_pretty``\ 可以用于把其它函数之一的结果格式化成一种人类易读的格式，可以根据情况使用字节、kB、MB、GB 或者 TB。 ``pg_size_bytes``\ 可以被用来从人类可读格式的字符串得到其中所表示的字节数。其输入可能带有的单位包括字节、kB、MB、GB 或者 TB，并且对输入进行解析时是区分大小写的。如果没有指定单位，会假定单位为字节。 .. note:: .. rubric:: 注意 :name: 注意 :class: title 函数\ ``pg_size_pretty``\ 和\ ``pg_size_bytes``\ 所使用的单位 kB、MB、GB 和 TB 是用 2 的幂而不是 10 的幂来定义，因此 1kB 是 1024 字节，1MB 是 1024\ :sup:`2` = 1048576 字节，以此类推。 上述操作表和索引的函数接受一个\ ``regclass``\ 参数，它是该表或索引在\ ``pg_class``\ 系统目录中的 OID。你不必手工去查找该 OID，因为\ ``regclass``\ 数据类型的输入转换器会为你代劳。只写包围在单引号内的表名，这样它看起来像一个文字常量。为了与普通SQL名称的处理相兼容，该字符串将被转换为小写形式，除非其中在表名周围包含双引号。 如果一个 OID 不表示一个已有的对象并且被作为参数传递给了上述函数，将会返回 NULL。 `表 9.90 `__\ 中展示的函数帮助标识数据库对象相关的磁盘文件。 .. container:: table :name: FUNCTIONS-ADMIN-DBLOCATION **表 9.90. 数据库对象定位函数** .. container:: table-contents +--------------------------+--------------+--------------------------+ | 名称 | 返回类型 | 描述 | +==========================+==============+==========================+ | ``pg_rela | ``oid`` | 指定关系的文件结点号 | | tion_filenode(relation`` | | | | ``regclass``) | | | +--------------------------+--------------+--------------------------+ | ``pg_rela | ``text`` | 指定关系的文件路径名 | | tion_filepath(relation`` | | | | ``regclass``) | | | +--------------------------+--------------+--------------------------+ | ``pg_fileno | ``regclass`` | 查找与给定的表 | | de_relation(tablespace`` | | 空间和文件节点相关的关系 | | ``oid``, *``filenode``* | | | | ``oid``) | | | +--------------------------+--------------+--------------------------+ ``pg_relation_filenode``\ 接受一个表、索引、序列或 TOAST 表的 OID 或名称，返回当前分配给它的“filenode”号。文件结点是关系的文件名的基本组件。对于大多数表结果和\ ``pg_class``.\ ``relfilenode``\ 相同，但是对于某些系统目录\ ``relfilenode``\ 为零，并且必须使用此函数获取正确的值。 如果传递一个没有存储的关系（如视图），此函数将返回 NULL。 ``pg_relation_filepath``\ 与\ ``pg_relation_filenode``\ 类似，但是它返回关系的整个文件路径名（相对于数据库集簇的数据目录\ ``PGDATA``\ ）。 ``pg_filenode_relation``\ 是\ ``pg_relation_filenode``\ 的反向函数。给定一个“tablespace” OID 以及一个 “filenode”，它会返回相关关系的 OID。对于一个在数据库的默认表空间中的表，该表空间可以指定为 0。 `表 9.91 `__\ 列出了用来管理排序规则的函数。 .. container:: table :name: FUNCTIONS-ADMIN-COLLATION **表 9.91. 排序规则管理函数** .. container:: table-contents +--------------------------+-------------+--------------------------+ | 名称 | 返回类型 | 描述 | +==========================+=============+==========================+ | | ``text`` | 返回来自操作 | | ``pg_collati | | 系统的排序规则的实际版本 | | on_actual_version(oid``) | | | +--------------------------+-------------+--------------------------+ | | ``integer`` | 导入操作系统排序规则 | | ``pg_import_sy | | | | stem_collations(schema`` | | | | ``regnamespace``) | | | +--------------------------+-------------+--------------------------+ ``pg_collation_actual_version``\ 返回当前安装在操作系统中的该排序规则对象的实际版本。如果这个版本与\ ``pg_collation.collversion``\ 中的值不同，则依赖于该排序规则的对象可能需要被重建。还可以参考\ `ALTER COLLATION `__\ 。 ``pg_import_system_collations``\ 基于在操作系统中找到的所有locale在系统目录\ ``pg_collation``\ 中加入排序规则。这是\ ``initdb``\ 会使用的函数。如果后来在操作系统上安装了额外的locale，可以再次运行这个函数加入新locale的排序规则。匹配\ ``pg_collation``\ 中现有项的locale将被跳过（但是这个函数不会移除以在操作系统中不再存在的locale为基础的排序规则对象）。\ *``schema``*\ 参数通常是\ ``pg_catalog``\ ，但这不是一种要求，排序规则也可以被安装到其他的方案中。该函数返回其创建的新排序规则对象的数量。 .. container:: table :name: FUNCTIONS-INFO-PARTITION **表 9.92. 分区信息函数** .. container:: table-contents +-----------------------+--------------------+-----------------------+ | 名称 | 返回类型 | 描述 | +=======================+====================+=======================+ | | ``setof record`` | 列出一个分区树 | | ``pg_parti | | 中的表或索引的相关信 | | tion_tree(regclass``) | | 息。给定的分区表或分 | | | | 区索引，每张表有一行 | | | | 分区。 | | | | 提供的信息 | | | | 包括分区的名称，它的 | | | | 直系父级的名称，一个 | | | | 布尔值，表示该分区是 | | | | 否是一个叶子，以及一 | | | | 个整数，表示它在层次 | | | | 结构中的级别。level的 | | | | 值从\ ``0``\ 开始，表 | | | | 示输入表或索引作为分 | | | | 区树的根，\ ``1``\ 表 | | | | 示其分区，\ ``2``\ 表 | | | | 示其分区，以此类推。 | +-----------------------+--------------------+-----------------------+ | | ``setof regclass`` | 列出给定分区的祖先 | | ``pg_partition_ | | 关系，包括分区本身。 | | ancestors(regclass``) | | | +-----------------------+--------------------+-----------------------+ | | ``regclass`` | R返回给定关系所属的分 | | ``pg_parti | | 区树的最上层父节点。 | | tion_root(regclass``) | | | +-----------------------+--------------------+-----------------------+ 要检查\ `第 5.11.2.1 节 `__\ 中描述的\ ``measurement``\ 表中的数据的总大小，可以使用下面的查询: .. code:: programlisting =# SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size FROM pg_partition_tree('measurement'); total_size ------------ 24 kB (1 row) .. container:: sect2 :name: FUNCTIONS-ADMIN-INDEX .. container:: titlepage .. container:: .. container:: .. rubric:: 9.26.8. 索引维护函数 :name: 索引维护函数 :class: title `表 9.93 `__\ 展示了可用于 索引维护任务的函数。这些函数不能在恢复期间执行。只有超级用户以及给定索引的拥有者才能是用这些函数。 .. container:: table :name: FUNCTIONS-ADMIN-INDEX-TABLE **表 9.93. 索引维护函数** .. container:: table-contents +--------------------------+-------------+--------------------------+ | 名称 | 返回类型 | 描述 | +==========================+=============+==========================+ | ``brin_summ | ``integer`` | 对还没有建 | | arize_new_values(index`` | | 立概要的页面范围建立概要 | | ``regclass``) | | | +--------------------------+-------------+--------------------------+ | ``brin | ``integer`` | 如果还没 | | _summarize_range(index`` | | 有对覆盖给定块的页面范围 | | ``regclass``, | | 建立概要，则对其建立概要 | | *``blockNumber``* | | | | ``bigint``) | | | +--------------------------+-------------+--------------------------+ | ``brin_d | ``integer`` | 如 | | esummarize_range(index`` | | 果覆盖给定块的页面范围已 | | ``regclass``, | | 经建立有概要，则去掉概要 | | *``blockNumber``* | | | | ``bigint``) | | | +--------------------------+-------------+--------------------------+ | ``gin_cl | ``bigint`` | 把 GIN | | ean_pending_list(index`` | | 待处理 | | ``regclass``) | | 列表项移动到主索引结构中 | +--------------------------+-------------+--------------------------+ ``brin_summarize_new_values``\ 接收一个 BRIN 索引的 OID 或者名称作为参数并且检查该索引以找到基表中当前还没有被该索引汇总的页面范围。对任意一个这样的范围，它将通过扫描那些表页面创建一个新的摘要索引元组。它会返回被插入到该索引的新页面范围摘要的数量。\ ``brin_summarize_range``\ 做同样的事情，不过它只对覆盖给定块号的范围建立概要。 ``gin_clean_pending_list``\ 接受一个 GIN 索引的 OID 或者名字，并且通过把指定索引的待处理列表中的项批量移动到主 GIN 数据结构来清理该索引的待处理列表。它会返回从待处理列表中移除的页数。注意如果其参数是一个禁用\ ``fastupdate``\ 选项构建的 GIN 索引，那么不会做清理并且返回值为 0，因为该索引根本没有待处理列表。 .. container:: sect2 :name: FUNCTIONS-ADMIN-GENFILE .. container:: titlepage .. container:: .. container:: .. rubric:: 9.26.9. 通用文件访问函数 :name: 通用文件访问函数 :class: title `表 9.94 `__\ 中展示的函数提供了对数据库服务器所在机器上的文件的本地访问。只能访问数据库集簇目录以及\ ``log_directory``\ 中的文件，除非用户被授予了角色\ ``pg_read_server_files``\ 。 使用相对路径访问集簇目录里面的文件，以及匹配 ``log_directory``\ 配置设置的路径访问日志文件。 注意向用户授予\ ``pg_read_file()``\ 或者相关函数上的EXECUTE特权，函数会允许他们读取服务器上该数据库能读取的任何文件并且这些读取动作会绕过所有的数据库内特权检查。这意味着，除了别的之外，具有这种访问的用户能够读取\ ``pg_authid``\ 表中包含着认证信息的内容，也能读取数据库中的任意文件。因此，授予对这些函数的访问应该要很仔细地考虑。 .. container:: table :name: FUNCTIONS-ADMIN-GENFILE-TABLE **表 9.94. 通用文件访问函数** .. container:: table-contents +------------------------+------------------+------------------------+ | 名称 | 返回类型 | 描述 | +========================+==================+========================+ | ``pg_ls_dir(dirname`` | ``setof text`` | 列出 | | ``text`` [, | | 目录中的内容。默认仅限 | | *``missing_ok``* | | 于超级用户使用，但是可 | | ``boolean``, | | 以给其他用户授予EXECU | | *``include_dot_dirs``* | | TE让他们运行这个函数。 | | ``boolean``]) | | | +------------------------+------------------+------------------------+ | ``pg_ls_logdir()`` | ``setof record`` | 列出日志目录中文 | | | | 件的名称、尺寸以及最后 | | | | 修改时间。访问被授予给 | | | | \ ``pg_monitor``\ 角色 | | | | 的成员，并且可以被授予 | | | | 给其他非超级用户角色。 | +------------------------+------------------+------------------------+ | ``pg_ls_waldir()`` | ``setof record`` | 列出WAL目录中文 | | | | 件的名称、尺寸以及最后 | | | | 修改时间。访问被授予给 | | | | \ ``pg_monitor``\ 角色 | | | | 的成员，并且可以被授予 | | | | 给其他非超级用户角色。 | +------------------------+------------------+------------------------+ | ``pg_ls | ``setof record`` | 列出WAL存档状态目录中 | | _archive_statusdir()`` | | 文件的名称、大小和最后 | | | | 一次修改时间。访问权限 | | | | 只授予\ ``pg_monitor`` | | | | \ 角色的成员，也可以授 | | | | 予其他非超级用户角色。 | +------------------------+------------------+------------------------+ | ``pg_l | ``setof record`` | 为\ *` | | s_tmpdir([tablespace`` | | `tablespace``*\ 列出临 | | ``oid``]) | | 时目录中文件的名称、大 | | | | 小和最后一次修改时间。 | | | | 如果没 | | | | 有提供\ *``tablespace` | | | | `*\ ，则在临时目录中的 | | | | ``pg_def | | | | ault``\ 表空间被使用。 | | | | ``pg_monitor``\ 角色的 | | | | 成员可以访问，其他非超 | | | | 级用户角色也可以访问。 | +------------------------+------------------+------------------------+ | ``p | ``text`` | 返回一个文 | | g_read_file(filename`` | | 本文件的内容。默认仅限 | | ``text`` [, | | 于超级用户使用，但是可 | | *``offset``* | | 以给其他用户授予EXECU | | ``bigint``, | | TE让他们运行这个函数。 | | *``length``* | | | | ``bigint`` [, | | | | *``missing_ok``* | | | | ``boolean``] ]) | | | +------------------------+------------------+------------------------+ | ``pg_read_ | ``bytea`` | 返回一 | | binary_file(filename`` | | 个文件的内容。默认仅限 | | ``text`` [, | | 于超级用户使用，但是可 | | *``offset``* | | 以给其他用户授予EXECU | | ``bigint``, | | TE让他们运行这个函数。 | | *``length``* | | | | ``bigint`` [, | | | | *``missing_ok``* | | | | ``boolean``] ]) | | | +------------------------+------------------+------------------------+ | ``p | ``record`` | 返回关于一 | | g_stat_file(filename`` | | 个文件的信息。默认仅限 | | ``text``\ [, | | 于超级用户使用，但是可 | | *``missing_ok``* | | 以给其他用户授予EXECU | | ``boolean``]) | | TE让他们运行这个函数。 | +------------------------+------------------+------------------------+ 这些函数中的某些有一个可选的\ *``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_ls_archive_statusdir``\ 返回WAL归档状态目录\ ``pg_wal/archive_status``\ 中每个文件的名称、大小和最后一次修改时间（mtime）。默认情况下，只有超级用户和\ ``pg_monitor``\ 角色的成员才能使用此函数。可使用\ ``GRANT``\ 授权其他用户访问。 ``pg_ls_tmpdir``\ 返回指定的\ *``tablespace``*\ 临时文件目录中每个文件的名称、大小和最后一次修改时间（mtime）。 如果没有提供\ *``tablespace``*\ ，则使用\ ``pg_default``\ 表空间。 默认情况下，只有超级用户和\ ``pg_monitor``\ 角色的成员才能使用这个函数。 可使用\ ``GRANT``\ 授权其他用户访问。 ``pg_read_file``\ 返回一个文本文件的一部分，从给定的\ *``offset``*\ 开始，返回最多\ *``length``*\ 字节（如果先到达文件末尾则会稍短）。如果\ *``offset``*\ 为负，它相对于文件的末尾。如果\ *``offset``*\ 和\ *``length``*\ 被忽略，整个文件都被返回。从文件中读的字节被使用服务器编码解释成一个字符串；如果它们在编码中不合法则抛出一个错误。 ``pg_read_binary_file``\ 与\ ``pg_read_file``\ 相似，除了前者的结果是一个\ ``bytea``\ 值；相应地，不会执行编码检查。通过与\ ``convert_from``\ 函数结合，这个函数可以用来读取一个指定编码的文件： .. code:: programlisting SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8'); ``pg_stat_file``\ 返回一个记录，其中包含文件尺寸、最后访问时间戳、最后修改时间戳、最后文件状态改变时间戳（只支持 Unix 平台）、文件创建时间戳（只支持 Windows）和一个\ ``boolean``\ 指示它是否为目录。通常的用法包括： .. code:: programlisting SELECT * FROM pg_stat_file('filename'); SELECT (pg_stat_file('filename')).modification; .. container:: sect2 :name: FUNCTIONS-ADVISORY-LOCKS .. container:: titlepage .. container:: .. container:: .. rubric:: 9.26.10. 咨询锁函数 :name: 咨询锁函数 :class: title .. container:: table :name: FUNCTIONS-ADVISORY-LOCKS-TABLE **表 9.95. 咨询锁函数** .. container:: table-contents +--------------------------+-------------+--------------------------+ | 名称 | 返回类型 | 描述 | +==========================+=============+==========================+ | ``pg_advisory_lock(key`` | ``void`` | 获得排他会话级别咨询锁 | | ``bigint``) | | | +--------------------------+-------------+--------------------------+ | ` | ``void`` | 获得排他会话级别咨询锁 | | `pg_advisory_lock(key1`` | | | | ``int``, *``key2``* | | | | ``int``) | | | +--------------------------+-------------+--------------------------+ | ``pg_ad | ``void`` | 获得共享会话级别咨询锁 | | visory_lock_shared(key`` | | | | ``bigint``) | | | +--------------------------+-------------+--------------------------+ | ``pg_adv | ``void`` | 获得共享会话级别咨询锁 | | isory_lock_shared(key1`` | | | | ``int``, *``key2``* | | | | ``int``) | | | +--------------------------+-------------+--------------------------+ | `` | ``boolean`` | 释 | | pg_advisory_unlock(key`` | | 放一个排他会话级别咨询锁 | | ``bigint``) | | | +--------------------------+-------------+--------------------------+ | ``p | ``boolean`` | 释 | | g_advisory_unlock(key1`` | | 放一个排他会话级别咨询锁 | | ``int``, *``key2``* | | | | ``int``) | | | +--------------------------+-------------+--------------------------+ | ``pg | ``void`` | 释放当前会话 | | _advisory_unlock_all()`` | | 持有的所有会话级别咨询锁 | +--------------------------+-------------+--------------------------+ | ``pg_advi | ``boolean`` | 释 | | sory_unlock_shared(key`` | | 放一个共享会话级别咨询锁 | | ``bigint``) | | | +--------------------------+-------------+--------------------------+ | ``pg_advis | ``boolean`` | 释 | | ory_unlock_shared(key1`` | | 放一个共享会话级别咨询锁 | | ``int``, *``key2``* | | | | ``int``) | | | +--------------------------+-------------+--------------------------+ | ``pg_ | ``void`` | 获得排他事务级别咨询锁 | | advisory_xact_lock(key`` | | | | ``bigint``) | | | +--------------------------+-------------+--------------------------+ | ``pg_a | ``void`` | 获得排他事务级别咨询锁 | | dvisory_xact_lock(key1`` | | | | ``int``, *``key2``* | | | | ``int``) | | | +--------------------------+-------------+--------------------------+ | ``pg_advisor | ``void`` | 获得共享事务级别咨询锁 | | y_xact_lock_shared(key`` | | | | ``bigint``) | | | +--------------------------+-------------+--------------------------+ | ``pg_advisory | ``void`` | 获得共享事务级别咨询锁 | | _xact_lock_shared(key1`` | | | | ``int``, *``key2``* | | | | ``int``) | | | +--------------------------+-------------+--------------------------+ | ``pg | ``boolean`` | 如果可能 | | _try_advisory_lock(key`` | | ，获得排他会话级别咨询锁 | | ``bigint``) | | | +--------------------------+-------------+--------------------------+ | ``pg_ | ``boolean`` | 如果可能 | | try_advisory_lock(key1`` | | ，获得排他会话级别咨询锁 | | ``int``, *``key2``* | | | | ``int``) | | | +--------------------------+-------------+--------------------------+ | ``pg_try_ad | ``boolean`` | 如果可能 | | visory_lock_shared(key`` | | ，获得共享会话级别咨询锁 | | ``bigint``) | | | +--------------------------+-------------+--------------------------+ | ``pg_try_adv | ``boolean`` | 如果可能 | | isory_lock_shared(key1`` | | ，获得共享会话级别咨询锁 | | ``int``, *``key2``* | | | | ``int``) | | | +--------------------------+-------------+--------------------------+ | ``pg_try_ | ``boolean`` | 如果可能 | | advisory_xact_lock(key`` | | ，获得排他事务级别咨询锁 | | ``bigint``) | | | +--------------------------+-------------+--------------------------+ | ``pg_try_a | ``boolean`` | 如果可能 | | dvisory_xact_lock(key1`` | | ，获得排他事务级别咨询锁 | | ``int``, *``key2``* | | | | ``int``) | | | +--------------------------+-------------+--------------------------+ | ``pg_try_advisor | ``boolean`` | 如果可能 | | y_xact_lock_shared(key`` | | ，获得共享事务级别咨询锁 | | ``bigint``) | | | +--------------------------+-------------+--------------------------+ | ``pg_try_advisory | ``boolean`` | 如果可能 | | _xact_lock_shared(key1`` | | ，获得共享事务级别咨询锁 | | ``int``, *``key2``* | | | | ``int``) | | | +--------------------------+-------------+--------------------------+ ``pg_advisory_lock``\ 锁住一个应用定义的资源，可以使用一个单一64位键值或两个32位键值标识（注意这些两个键空间不重叠）。如果另一个会话已经在同一个资源标识符上持有了一个锁，这个函数将等待直到该资源变成可用。该锁是排他的。多个锁请求会入栈，因此如果同一个资源被锁住三次，则它必须被解锁三次来被释放给其他会话使用。 ``pg_advisory_lock_shared``\ 的工作和\ ``pg_advisory_lock``\ 相同，不过该锁可以与其他请求共享锁的会话共享。只有想要排他的锁请求会被排除。 ``pg_try_advisory_lock``\ 与\ ``pg_advisory_lock``\ 相似，不过该函数将不会等待锁变为可用。它要么立刻获得锁并返回\ ``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``\ 将释放当前会话所持有的所有会话级别咨询锁（这个函数隐式地在会话末尾被调用，即使客户端已经不雅地断开）。 ``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``\ 相同，不过锁（若果获得）是在当前事务的末尾被自动释放的并且不能被显式释放。