| PostgreSQL 9.3.4 文档 | ||||
|---|---|---|---|---|
| Prev | Up | Chapter 9. 函数和操作符 | Next | |
这一节描述的函数被用来控制和监视一个PostgreSQL安装。
Table 9-58展示了那些可以用于查询以及修改运行时配置参数的函数。
Table 9-58. 配置设定函数
| 名称 | 返回类型 | 描述 |
|---|---|---|
current_setting(setting_name)
| text | 获得设置的当前值 |
set_config(setting_name,
new_value,
is_local)
| text | 设置一个参数并返回新值 |
current_setting得到setting_name设置的当前值。它对应于SQL命令SHOW。一个例子：
SELECT current_setting('datestyle');
current_setting
-----------------
ISO, MDY
(1 row)
set_config将参数setting_name设置为new_value。如果 is_local设置为true，那么新值将只应用于当前事务。 如果你希望新值应用于当前会话，那么应该使用false。 它等效于 SQL 命令 SET。例如：
SELECT set_config('log_statement_stats', 'off', false);
set_config
------------
off
(1 row)
在Table 9-59中展示的函数向其它服务器进程发送控制信号。这些函数的使用通常限制为超级用户。
Table 9-59. 服务器信号函数
| 名称 | 返回类型 | 描述 |
|---|---|---|
pg_cancel_backend(pid int)
| boolean | 取消一个后端的当前查询。你可以对另一个后端执行这个函数，只要该后端的角色正好和调用该函数的用户相同。在所有其他情况下，你都必须是一个超级用户。 |
pg_reload_conf()
| boolean | 导致服务器进程重载它们的配置文件 |
pg_rotate_logfile()
| boolean | 切换服务器的日志文件 |
pg_terminate_backend(pid int)
| boolean | 中止一个后端。你可以对另一个后端执行这个函数，只要该后端的角色正好和调用该函数的用户相同。在所有其他情况下，你都必须是一个超级用户。 |
这些函数中的每一个都在成功时返回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.
Table 9-60中展示的函数可以辅助制作在线备份。这些函数不能在恢复期间执行（pg_is_in_backup、pg_backup_start_time和pg_xlog_location_diff除外）。
Table 9-60. 备份控制函数
| 名称 | 返回类型 | 描述 |
|---|---|---|
pg_create_restore_point(name text)
| text | 为执行恢复创建一个命名点（只限于超级用户） |
pg_current_xlog_insert_location()
| text | 获得当前事务日志插入位置 |
pg_current_xlog_location()
| text | 获得当前事务日志写入位置 |
pg_start_backup(label text [, fast boolean ])
| text | 准备执行在线备份（只限于超级用户或者复制角色） |
pg_stop_backup()
| text | 完成执行在线备份（只限于超级用户或者复制角色） |
pg_is_in_backup()
| bool | 如果一个在线排他备份仍在进行中则为真。 |
pg_backup_start_time()
| timestamp with time zone | 获得一个进行中的在线排他备份的开始时间。 |
pg_switch_xlog()
| text | 强制切换到一个新的事务日志文件（只限于超级用户） |
pg_xlogfile_name(location text)
| text | 转换事务日志位置字符串为文件名 |
pg_xlogfile_name_offset(location text)
| text, integer | 转换事务日志位置字符串为文件名以及文件内的十进制字节偏移 |
pg_xlog_location_diff(location text, location text)
| numeric | 计算两个事务日志位置间的差别 |
pg_start_backup接受一个参数，这个参数可以是备份的任意用户定义的标签（通常这是备份转储文件将被存储的名字）。该函数向数据库集簇的数据目录写入一个备份标签文件（backup_label），执行一个检查点，然后以文本方式返回备份的起始事务日志位置。用户可以忽略这个结果值，但是为了可能需要的场合我们还是提供该值。
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创建的标签文件， 并且在事务日志归档区里创建一个备份历史文件。这个历史文件包含给予pg_start_backup的标签、备份的起始与终止事务日志位置以及备份的起始和终止时间。返回值是备份的终止事务日志位置（同样也可以被忽略）。在记录结束位置之后，当前事务日志插入点被自动地推进到下一个事务日志文件，这样结束的事务日志文件可以立即被归档来结束备份。
pg_switch_xlog移动到下一个事务日志文件，允许当前文件被归档（假定你正在使用连续归档）。返回值是在甘冈完成的事务日志文件中结束事务日志位置 + 1。如果从上一次事务日志切换依赖没有事务日志活动，pg_switch_xlog不会做任何事情并且返回当前正在使用的事务日志文件的开始位置。
pg_create_restore_point创建一个命名事务日志记录，它可以被用作恢复目标，并且返回相应的事务日志位置。这个给定的名字可以用于recovery_target_name来指定恢复要进行到的点。避免使用同一个名称创建多个恢复点，因为恢复会停止在第一个匹配名称的恢复目标。
pg_current_xlog_location使用上述函数使用的相同格式显示当前事务日志写入位置。相似地，pg_current_xlog_insert_location显示当前事务日志插入点。插入点是在任何实例中事务日志的"逻辑"终点，而写入位置表示那些已经确实被从服务器的内部缓存写出的东西的重点。写出位置是哪些可以从服务器外部检查的东西的重点，并且通常是你所需要的，如果你对归档部分完成的事务日志文件感兴趣。插入点主要是为服务器调试目的创造的。这些都是只读操作并且不需要超级用户权限。
你可以使用pg_xlogfile_name_offset从任何上述函数的结果中抽取相应的事务日志文件名称以及字节偏移。例如：
postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
file_name | file_offset
--------------------------+-------------
00000001000000000000000D | 4039624
(1 row)
相似地，pg_xlogfile_name只抽取事务日志文件名。当给定的事务日志位置正好在一个事务日志文件的边界，这些函数都返回之前的事务日志文件的名称。这对管理事务日志归档行为通常是所希望的行为，因为前一个文件是当前需要被归档的最后一个文件。
pg_xlog_location_diff以字节数计算两个事务日志位置之间的差别。它可以和pg_stat_replication或Table 9-60中其他的函数一起使用来获得复制延迟。
关于正确使用这些函数的细节，请见Section 24.3。
Table 9-61中展示的函数提供有关后备机当前状态的信息。这些函数可以在恢复或普通运行过程中被执行。
Table 9-61. 恢复信息函数
| 名称 | 返回类型 | 描述 |
|---|---|---|
pg_is_in_recovery()
| bool | 如果恢复仍在进行中，为真。 |
pg_last_xlog_receive_location()
| text | 获得最后一个收到并由流复制同步到磁盘的事务日志位置。当流复制在进行中时，这将单调增加。如果恢复已经完成，这将保持静止在恢复过程中收到并同步到磁盘的最后一个 WAL 记录。如果流复制被禁用，或者还没有被启动，该函数返回 NULL。 |
pg_last_xlog_replay_location()
| text | 获得恢复过程中被重放的最后一个事务日志位置。当流复制在进行中时，这将单调增加。如果恢复已经完成，这将保持静止在恢复过程中被应用的最后一个 WAL 记录。如果服务器被正常启动而没有恢复，该函数返回 NULL。 |
pg_last_xact_replay_timestamp()
| timestamp with time zone | 获得恢复过程中被重放的最后一个事务的时间戳。这是在主机上产生的事务的提交或中止 WAL 记录的时间。如果在恢复过程中没有事务被重放，这个函数返回 NULL。否则，如果恢复仍在进行这将单调增加。如果恢复已经完成，则这个值会保持静止在恢复过程中最后一个被应用的事务。如果服务器被正常启动而没有恢复，该函数返回 NULL。 |
Table 9-62中展示的函数空值恢复的进程。这些函数只能在恢复过程中被执行。
Table 9-62. 恢复控制函数
| 名称 | 返回类型 | 描述 |
|---|---|---|
pg_is_xlog_replay_paused()
| bool | 如果恢复被暂停，为真。 |
pg_xlog_replay_pause()
| void | 立即暂停恢复。 |
pg_xlog_replay_resume()
| void | 如果恢复被暂停，重启之。 |
在恢复被暂停时，不会有进一步的数据库改变被应用。如果在热备模式，所有新的查询将看到数据库的同一个一致快照，并且在恢复被继续之前不会有更多查询冲突会产生。
如果流复制被禁用，暂停状态可以无限制地继续而不出问题。在流复制进行时，WAL 记录将继续被接收，最后将会填满可用的磁盘空间，取决于暂停的持续时间、WAL 的产生率和可用的磁盘空间。
PostgreSQL允许数据库会话同步它们的快照。一个快照决定对于正在使用该快照的事务哪些数据是可见的。当两个或者更多个会话需要看到数据库中的相同内容时，就需要同步快照。如果两个会话独立开始其事务，就总是有可能有某个第三事务在两个START TRANSACTION命令的执行之间提交，这样其中一个会话就可以看到该事务的效果而另一个则看不到。
为了解决这个问题，PostgreSQL允许一个事务导出它正在使用的快照。只要导出的事务仍然保持打开，其他事务可以导入它的快照，并且因此可以保证它们可以看到和第一个事务看到的完全一样的数据库视图。但是注意这些事务中的任何一个对数据库所作的更改对其他事务仍然保持不可见，和未提交事务所作的修改一样。因此这些事务是针对以前存在的数据同步，而对由它们自己所作的更改则采取正常的动作。
如Table 9-63中所示，快照通过pg_export_snapshot函数导出，并且通过SET TRANSACTION命令导入。
函数pg_export_snapshot保存当前的快照并且返回一个text串标识该快照。该字符串必须被传递（到数据库外）给希望导入快照的客户端。直到导出快照的事务的末尾，快照都可以被导入。如果需要，一个事务可以导出多于一个快照。注意这样做只在 READ COMMITTED事务中有用，因为在REPEATABLE READ和更高隔离级别中，事务在它们的生命期中都使用同一个快照。一旦一个事务已经导出了任何快照，它不能使用PREPARE TRANSACTION。
关于如何使用一个已导出快照的细节请见SET TRANSACTION.
Table 9-64中展示的函数计算数据库对象使用的磁盘空间。
Table 9-64. 数据库对象尺寸函数
| 名称 | 返回类型 | 描述 |
|---|---|---|
pg_column_size(any) | int | 存储一个特定值（可能压缩过）所需的字节数 |
pg_database_size(oid)
| bigint | 指定 OID 的数据库使用的磁盘空间 |
pg_database_size(name)
| bigint | 指定名称的数据库使用的磁盘空间 |
pg_indexes_size(regclass)
| bigint | 附加到指定表的索引所占的总磁盘空间 |
pg_relation_size(relation regclass, fork text)
| bigint | 指定表或索引的指定分叉（'main'、'fsm'或'vm'）使用的磁盘空间 |
pg_relation_size(relation regclass)
| bigint | pg_relation_size(..., 'main')的简写 |
pg_size_pretty(bigint)
| text | 将表示成一个 64位整数的字节尺寸转换为带尺寸单位的人类可读格式 |
pg_size_pretty(numeric)
| text | 将表示成一个数字值的字节尺寸转换为带尺寸单位的人类可读格式 |
pg_table_size(regclass)
| bigint | 被指定表使用的磁盘空间，排除索引（但包括 TOAST、空闲空间映射和可见性映射） |
pg_tablespace_size(oid)
| bigint | 指定 OID 的表空间使用的磁盘空间 |
pg_tablespace_size(name)
| bigint | 指定名称的表空间使用的磁盘空间 |
pg_total_relation_size(regclass)
| bigint | 指定表所用的总磁盘空间，包括所有的索引和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_relation_size接受一个表、索引、TOAST 表的 OID 或名字，然后返回它们以字节计的磁盘尺寸。 指定'main'或省去第二个参数返回关系中主数据分叉的尺寸。指定'fsm'返回 这个关系相关的空闲空间映射的尺寸（见Section 58.3）。指定'vm'返回关联这个关系的可见性映射的尺寸（见Section 58.4）。 注意这个函数只显示一个分叉的尺寸；对于大多目的而言，使用高级别函数pg_total_relation_size或pg_table_size更方便。
pg_size_pretty可以用于把其它函数之一的结果格式化成一种人类易读的格式，可以根据情况使用 KB、MB、GB 或者 TB。
上述操作表和索引的函数接受一个regclass参数，它是该表或索引在pg_class系统目录中的 OID。你不必手工去查找该 OID，因为regclass数据类型的输入转换器会为你代劳。只写包围在单引号内的表名，这样它看起来像一个文字常量。为了与普通SQL名称的处理相兼容，该字符串将被转换为小写形式，除非其中在表名周围包含双引号。
如果一个 OID 不表示一个已有的对象并且被作为参数传递给了上述函数，将会返回 NULL。
Table 9-65中展示的函数帮助标识数据库对象相关的磁盘文件。
Table 9-65. 数据库对象定位函数
| 名称 | 返回类型 | 描述 |
|---|---|---|
pg_relation_filenode(relation regclass)
| oid | 指定关系的文件结点号 |
pg_relation_filepath(relation regclass)
| text | 指定关系的文件路径名 |
pg_relation_filenode接受一个表、索引、序列或 TOAST 表的 OID 或名称，返回当前分配给它的"filenode"号。文件结点是关系的文件名的基本组件（详见Section 58.1）。对于大多数表结果和pg_class.relfilenode相同，但是对于某些系统目录relfilenode为零，并且必须使用此函数获取正确的值。 如果传递一个没有存储的关系（如视图），此函数将返回 NULL。
pg_relation_filepath与pg_relation_filenode类似，但是它返回关系的整个文件路径名（相对于数据库集簇的数据目录PGDATA）。
Table 9-66中展示的函数提供了对数据库服务器所在机器上的文件的本地访问。 只有那些在数据库集簇目录和log_directory目录中的文件可以访问。使用相对路径访问集簇目录里面的文件，以及匹配 log_directory配置设置的路径访问日志文件。只有超级用户才能使用这些函数。
Table 9-66. 通用文件访问函数
| 名称 | 返回类型 | 描述 |
|---|---|---|
pg_ls_dir(dirname text)
| setof text | 列出目录中的内容 |
pg_read_file(filename text [, offset bigint, length bigint])
| text | 返回一个文本文件的内容 |
pg_read_binary_file(filename text [, offset bigint, length bigint])
| bytea | 返回一个文件的内容 |
pg_stat_file(filename text)
| record | 返回关于一个文件的信息 |
pg_ls_dir返回指定目录中所有的名称，除了特殊的项"."和".."。
pg_read_file返回一个文本文件的一部分，从给定的offset开始，返回最多length字节（如果先到达文件末尾则会稍短）。如果offset为负，它相对于文件的末尾。如果offset和length被忽略，整个文件都被返回。从文件中读的字节被使用服务器编码解释成一个字符串；如果它们在编码中不合法则抛出一个错误。
pg_read_binary_file与pg_read_file相似，除了前者的结果是一个bytea值；相应地，不会执行编码检查。通过与convert_from函数结合，这个函数可以用来读取一个指定编码的文件：
SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8');
pg_stat_file返回一个记录，其中包含文件尺寸、最后访问时间戳、最后修改时间戳、最后文件状态改变时间戳（只支持 Unix 平台）、文件创建时间戳（只支持 Windows）和一个boolean指示它是否为目录。通常的用法包括：
SELECT * FROM pg_stat_file('filename');
SELECT (pg_stat_file('filename')).modification;
Table 9-67中展示的函数管理咨询锁。有关正确使用这些函数的细节请参考Section 13.3.4。
Table 9-67. 咨询锁函数
| 名称 | 返回类型 | 描述 |
|---|---|---|
pg_advisory_lock(key bigint)
| void | 获得排他会话级别咨询锁 |
pg_advisory_lock(key1 int, key2 int)
| void | 获得排他会话级别咨询锁 |
pg_advisory_lock_shared(key bigint)
| void | 获得共享会话级别咨询锁 |
pg_advisory_lock_shared(key1 int, key2 int)
| void | 获得共享会话级别咨询锁 |
pg_advisory_unlock(key bigint)
| boolean | 释放一个排他会话级别咨询锁 |
pg_advisory_unlock(key1 int, key2 int)
| boolean | 释放一个排他会话级别咨询锁 |
pg_advisory_unlock_all()
| void | 释放当前会话持有的所有会话级别咨询锁 |
pg_advisory_unlock_shared(key bigint)
| boolean | 释放一个共享会话级别咨询锁 |
pg_advisory_unlock_shared(key1 int, key2 int)
| boolean | 释放一个共享会话级别咨询锁 |
pg_advisory_xact_lock(key bigint)
| void | 获得排他事务级别咨询锁 |
pg_advisory_xact_lock(key1 int, key2 int)
| void | 获得排他事务级别咨询锁 |
pg_advisory_xact_lock_shared(key bigint)
| void | 获得共享事务级别咨询锁 |
pg_advisory_xact_lock_shared(key1 int, key2 int)
| void | 获得共享事务级别咨询锁 |
pg_try_advisory_lock(key bigint)
| boolean | 如果可能，获得排他会话级别咨询锁 |
pg_try_advisory_lock(key1 int, key2 int)
| boolean | 如果可能，获得排他会话级别咨询锁 |
pg_try_advisory_lock_shared(key bigint)
| boolean | 如果可能，获得共享会话级别咨询锁 |
pg_try_advisory_lock_shared(key1 int, key2 int)
| boolean | 如果可能，获得共享会话级别咨询锁 |
pg_try_advisory_xact_lock(key bigint)
| boolean | 如果可能，获得排他事务级别咨询锁 |
pg_try_advisory_xact_lock(key1 int, key2 int)
| boolean | 如果可能，获得排他事务级别咨询锁 |
pg_try_advisory_xact_lock_shared(key bigint)
| boolean | 如果可能，获得共享事务级别咨询锁 |
pg_try_advisory_xact_lock_shared(key1 int, key2 int)
| boolean | 如果可能，获得共享事务级别咨询锁 |
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相同，不过锁（若果获得）是在当前事务的末尾被自动释放的并且不能被显式释放。