E.11. lt_cheat_funcs

E.11.1. 函数
E.11.2. 编码转换
E.11.3. 配置参数

该扩展提供了在LightDB上使用的作弊(但有用的)函数。

E.11.1. 函数

请注意,在想要执行该扩展提供的函数的所有数据库中,都需要执行CREATE EXTENSION lt_cheat_funcs

=# CREATE EXTENSION lt_cheat_funcs;

E.11.1.1. SETOF record pg_stat_get_memory_context()

返回有关所有内存上下文的统计信息。此函数返回一个记录,如下表所示。

列名 数据类型 描述
name text 上下文名称
parent text 父级上下文的名称
level integer 上下文树中距离TopMemoryContext的距离
total_bytes bigint 从malloc请求的总字节数
total_nblocks bigint malloc块的总数
free_bytes bigint 空闲空间的字节数
free_chunks bigint 空闲块的数量
used_bytes bigint 已使用空间的字节数

默认情况下,此函数仅限超级用户使用,但可以授予其他用户EXECUTE权限以运行此函数。

E.11.1.2. void pg_stat_print_memory_context()

让有关所有内存上下文的统计信息记录在日志中。每个内存上下文的日志消息格式如下:

        [name]: [total_bytes] 总共 [total_nblocks] 个块;[free_bytes] 空闲([free_chunks] 个块);[used_bytes] 已使用
      

有关上述字段的描述,请参见 pg_stat_get_memory_context()

默认情况下,此函数仅限超级用户使用,但可以授予其他用户EXECUTE权限以运行此函数。

E.11.1.3. record pg_cached_plan_source(stmt text)

返回指定准备语句的缓存计划源的信息。此函数返回一个记录,如下表所示。

列名 数据类型 描述
generic_cost double precision 通用计划的成本,如果不知道,则为-1
total_custom_cost double precision 自定义计划的总成本
num_custom_plans integer 总计划包含的计划数
force_generic boolean 是否强制使用通用计划?
force_custom boolean 是否强制使用自定义计划?

E.11.1.4. void pg_signal_process(pid int, signame text)

向LightDB服务器进程发送信号。此函数仅能向postmaster、backend、walsender和walreceiver进程发送信号。有效的信号名称包括HUP、INT、QUIT、ABRT、KILL、TERM、USR1、USR2、CONT和STOP。默认情况下,此函数仅限超级用户使用,但可以授予其他用户EXECUTE权限以运行此函数。

例如,终止walreceiver进程:

=# SELECT pg_signal_process(pid, 'TERM') FROM pg_stat_wal_receiver;

E.11.1.5. integer pg_get_priority(pid int)

返回指定LightDB服务器进程的调度优先级(nice )。此函数仅能获取postmaster、backend、walsender和walreceiver进程的优先级。有关调度优先级的详细信息,请参见getpriority(2)手册页。默认情况下,此函数仅限超级用户使用,但可以授予其他用户EXECUTE权限以运行此函数。

E.11.1.6. void pg_set_priority(pid int, priority int)

将指定LightDB服务器进程的调度优先级(nice )设置为指定的值。此函数仅能更改postmaster、backend、walsender和walreceiver进程的优先级。有关调度优先级的详细信息,请参见getpriority(2)手册页。默认情况下,此函数仅限超级用户使用,但可以授予其他用户EXECUTE权限以运行此函数。

E.11.1.7. void pg_segmentation_fault(treat_fatal_as_error boolean)

引起分段错误。如果启用了lt_cheat_funcs.exit_on_segv并且treat_fatal_as_error为true,则此函数引起的分段错误将导致ERROR而不是FATAL错误。这主要用于测试。默认情况下,此函数仅限超级用户使用,但可以授予其他用户EXECUTE权限以运行此函数。

E.11.1.8. void pg_process_config_file()

读取并处理配置文件。请注意,如果发生错误,则会使用DEBUG2级别记录错误。默认情况下,此函数仅限超级用户使用,但可以授予其他用户EXECUTE权限以运行此函数。

E.11.1.9. text pg_xlogfile_name(location pg_lsn, recovery boolean)

将事务日志位置字符串转换为文件名。此函数与LightDB核心提供的pg_xlogfile_name()函数几乎相同。它们之间的区别在于是否有第二个类型为boolean的参数。如果为false,则此函数在恢复过程中始终失败并显示错误信息。这与pg_xlogfile_name()的核心版本相同。如果为true,则即使在恢复过程中也可以执行此函数。但请注意,返回的WAL文件名的前8个数字(表示时间线ID)可能完全不正确。也就是说,此函数可能返回虚假的WAL文件名。有关此转换的详细信息,请参见 Section 10.27.3

E.11.1.10. SETOF record pg_stat_get_syncrep_waiters()

返回所有等待同步复制的服务器进程的统计信息。此函数为每个等待同步复制的服务器进程返回一个记录,如下表所示。

列名 数据类型 描述
pid integer 服务器进程的进程ID
wait_lsn pg_lsn 等待的事务日志位置
wait_mode text 服务器进程的等待模式

wait_mode的可能值为write、flush和apply。

默认情况下,此函数仅限超级用户使用,但可以授予其他用户EXECUTE权限以运行此函数。

E.11.1.11. void pg_wait_syncrep(location pg_lsn)

等待同步复制。此函数一直等待,直到根据synchronous_commit的设置,给定的事务日志位置被同步备用实例确认。

默认情况下,此函数仅限超级用户使用,但可以授予其他用户EXECUTE权限以运行此函数。

E.11.1.12. xid pg_set_next_xid(transactionid xid)

设置并返回下一个事务ID。请注意,此函数不会检查将给定的事务ID分配给下一个事务ID是否安全。调用者必须谨慎选择安全的事务ID,例如,不会引起事务ID环绕问题。默认情况下,此函数仅限超级用户使用,但可以授予其他用户EXECUTE权限以运行此函数。

E.11.1.13. SETOF record pg_xid_assignment()

返回有关事务ID分配状态的信息。此函数返回一个记录,如下表所示。

列名 数据类型 描述
next_xid xid 要分配的下一个事务ID
oldest_xid xid 集群中最小的datfrozenxid
xid_vac_limit xid 开始强制执行自动清理的位置
xid_warn_limit xid 开始发出警告的位置
xid_stop_limit xid 拒绝将下一个事务ID超越此处
xid_wrap_limit xid 世界末日的位置
oldest_xid_db oid 具有最小datfrozenxid的数据库

默认情况下,此函数仅限超级用户使用,但可以授予其他用户执行此函数的EXECUTE权限。

E.11.1.14. xid pg_set_next_oid(objectid oid)

设置并返回下一个对象ID(OID)。请注意,当给定的OID小于16384(FirstNormalObjectId)时,下一个OID将被设置为16384。默认情况下,此函数仅限超级用户使用,但可以授予其他用户执行此函数的EXECUTE权限。

E.11.1.15. SETOF record pg_oid_assignment()

返回有关对象ID(OID)分配状态的信息。此函数返回一个记录,如下表所示。

列名 数据类型 描述
next_oid oid 要分配的下一个对象ID
oid_count integer 必须执行WAL工作之前可用的OID数量

默认情况下,此函数仅限超级用户使用,但可以授予其他用户执行此函数的EXECUTE权限。

E.11.1.16. integer pg_advance_vacuum_cleanup_age(integer)

指定VACUUM和HOT更新清理死行版本所需推进的事务数。 调用此函数的会话中的vacuum_defer_cleanup_age 被设置为指定数字的负值。如果省略了参数或指定了NULL,则会将vacuum_defer_cleanup_age重置为配置文件中指定的原始设置值。 该函数返回清理VACUUM的年龄(vacuum cleanup age)。

通过推进清理年龄,VACUUM和HOT更新可以清理甚至是自最旧事务开始以来产生的死元组。 因此,这个函数对于防止长时间运行的事务期间由于无法删除的死元组而导致数据库膨胀非常有帮助。

请注意,这是一项极其危险的功能,很容易损坏数据库。任何重要数据都可能消失,数据一致性可能完全丢失。 这个函数除了调试目的外,绝不能用于其他目的。

默认情况下,此函数仅限超级用户使用,但其他用户也可以被授予EXECUTE权限来运行该函数。

E.11.1.17. void pg_checkpoint(fast bool, wait bool, force bool)

执行检查点。如果快速(fast)为true(默认值),检查点将尽快完成。 否则,为了最小化查询处理的影响,检查点所需的I/O将分布在一段时间内。 如果等待(wait)为true(默认值),则此函数在返回之前等待检查点完成。 否则,它只是向检查点发出信号并返回。 如果强制(force)为true(默认值),则此函数即使自上次检查点以来没有WAL活动也会强制执行检查点。 默认情况下,此函数仅限超级用户使用,但其他用户也可以被授予EXECUTE权限来运行该函数。

E.11.1.18. SETOF 记录 pg_recovery_settings()

返回recovery.conf中所有参数设置的信息。此函数返回一个记录,如下表所示。

列名 数据类型 描述
名称 文本 配置参数名称
设置 文本 参数值

默认情况下,此函数仅限超级用户使用,但其他用户也可以被授予EXECUTE权限来运行该函数。

E.11.1.19. 文本型 pg_show_primary_conninfo()

返回primary_conninfo恢复参数的当前值。如果尚未设置,则返回NULL。 默认情况下,此函数仅限超级用户使用,但其他用户也可以被授予EXECUTE权限来运行该函数。 有关primary_conninfo参数的详细信息,请参见primary_conninfo

E.11.1.20. 整数型 pg_postmaster_pid()

返回postmaster进程的进程ID。

E.11.1.21. 带时区的时间戳型 pg_backend_start_time()

返回当前会话所附加的服务器进程启动时间。

E.11.1.22. SETOF 文本型 pg_list_relation_filepath(relation regclass)

列出指定关系的文件路径名称。

E.11.1.23. 文本型 pg_tablespace_version_direcotry()

返回特定于主版本的表空间子目录的名称。

E.11.1.24. 大整数型 pg_file_write_binary(filepath text, data bytea)

将bytea数据写入文件。如果文件不存在,则此函数创建文件,并将其截断为零长度。然后,此函数从文件开头写入bytea数据,并返回写入的字节数。 默认情况下,此函数仅限超级用户使用,但其他用户也可以被授予EXECUTE权限来运行该函数。

E.11.1.25. 无返回值 pg_file_fsync(filepath text)

尝试对文件或目录进行fsync。默认情况下,此函数仅限超级用户使用,但其他用户也可以被授予EXECUTE权限来运行该函数。

E.11.1.26. 文本型 to_octal(integer or bigint)

将数字转换为其等效的八进制表示。

E.11.1.27. 文本型 pg_text_to_hex(str text)

将文本转换为其等效的十六进制表示。

这是一个将文本转换为十六进制的示例:

=# SELECT pg_text_to_hex('LightDB');
    pg_text_to_hex    
----------------------
 4c696768744442
(1 row)

E.11.1.28. 文本型 pg_hex_to_text(hex text)

将十六进制表示转换为其等效的文本。

这是一个将十六进制转换为文本的示例:

=# SELECT pg_hex_to_text('4c696768744442');
 pg_hex_to_text
----------------
 LightDB
(1 row)

E.11.1.29. 文本型 pg_chr(code integer)

返回具有给定代码的字符。此函数与LightDB核心提供的chr()函数几乎相同。它们的区别在于,当请求的字符过大或无效时,此函数返回NULL,而不是抛出错误。请注意,有效的Unicode代码点停止于U+10FFFF(1114111),即使4字节的UTF8序列可以容纳高达U+1FFFFF的值。因此,每当给定的代码大于1114111时,此函数都会返回NULL。

E.11.1.30. 文本型 pg_utf8(code integer)

pg_chr(code integer)函数的别名。

E.11.1.31. SETOF 记录型 pg_all_utf8()

返回所有有效的UTF-8字符。此函数返回一个记录,如下表所示。

列名 数据类型 描述
代码 文本 字符的代码
utf8 文本 UTF-8字符

此函数仅可在UTF-8数据库编码下执行。

E.11.1.32. 文本型 pg_eucjp(code1 bit(8), code2 bit(8), code3 bit(8))

返回具有给定代码的EUC_JP字符。以下表格显示代码的有效组合。

code1 code2 code3
x00 - x7f - -
x8e xa1 - xdf -
xa1 - xfe xa1 - xfe -
x8f xa1 - xfe xa1 - xfe

例如,返回具有代码a1fa(黑色星号)的EUC_JP字符:

=# SELECT pg_eucjp('xa1', 'xfa');

如果请求的字符对于EUC_JP无效,则此函数返回NULL。此函数仅可在EUC_JP数据库编码下执行。

E.11.1.33. SETOF记录 pg_all_eucjp()

返回所有有效的 EUC_JP 字符。该函数返回一个记录,如下表所示。

列名 数据类型 描述
code1 text 字符的第一个字节
code2 text 字符的第二个字节(x00 表示该字节不存在)
code3 text 字符的第三个字节(x00 表示该字节不存在)
eucjp text EUC_JP 字符

该函数只能在 EUC_JP 数据库编码下执行。

E.11.1.34. bytea pglz_compress(data text)

创建并返回文本数据的压缩版本。该函数使用 PGLZ(一种用于 LightDB 的 LZ 压缩实现)进行压缩。如果压缩失败(例如,压缩结果实际上比原始数据更大),则该函数返回原始数据。请注意,即使压缩失败,返回数据可能比原始数据多 4 个字节,因为它始终存储 4 个字节的额外信息,如原始数据的长度。该函数返回的 bytea 数据需要使用 pg_lz_decompress() 进行解压缩,以获取原始文本数据。

E.11.1.35. bytea pglz_compress_bytea(data bytea)

创建并返回 bytea 数据的压缩版本。该函数使用 PGLZ(一种用于 LightDB 的 LZ 压缩实现)进行压缩。如果压缩失败(例如,压缩结果实际上比原始数据更大),则该函数返回原始数据。请注意,即使压缩失败,返回数据可能比原始数据多 4 个字节,因为它始终存储 4 个字节的额外信息,如原始数据的长度。该函数返回的 bytea 数据需要使用 pg_lz_decompress_bytea() 进行解压缩,以获取原始 bytea 数据。

E.11.1.36. text pglz_decompress(data bytea)

将 bytea 数据的压缩版本解压缩为文本。请注意,该函数的输入必须是 pg_lz_compress() 或 pg_lz_compress_bytea() 返回的 bytea 数据。否则该函数可能返回损坏的数据。

E.11.1.37. bytea pglz_decompress_bytea(data bytea)

将 bytea 数据的压缩版本解压缩为 bytea。请注意,该函数的输入必须是 pg_lz_compress() 或 pg_lz_compress_bytea() 返回的 bytea 数据。否则该函数可能返回损坏的数据。

E.11.1.38. text pg_saslprep(input text)

使用 SASLprep 对输入字符串进行规范化处理。SASLprep 规范化主要用于将用户提供的密码处理为 SCRAM 认证的规范形式。请注意,如果输入不是有效的 UTF-8 字符串或规范化后的字符串包含 SASLprep 档案禁止使用的字符,则会引发错误。

E.11.1.39. pg_advisory_xact_unlock(bigint)

释放先前获取的排他事务级别的咨询锁。如果成功释放锁,则返回 true。如果未持有锁,则返回 false,并且服务器将报告一个 SQL 警告。

E.11.1.40. pg_advisory_xact_unlock_shared(bigint)

释放先前获取的共享事务级别的咨询锁。如果成功释放锁,则返回 true。如果未持有锁,则返回 false,并且服务器将报告一个 SQL 警告。

E.11.1.41. pg_advisory_xact_unlock(integer, integer)

与 pg_advisory_xact_unlock(bigint) 相同。

E.11.1.42. pg_advisory_xact_unlock_shared(integer, integer)

与 pg_advisory_xact_unlock_shared(bigint) 相同。

E.11.2. 编码转换

E.11.2.1. pg_euc_jp_to_utf8

这是从 EUC_JP 到 UTF-8 的编码转换。它使用两个转换映射;普通映射和额外映射。它们分别定义在 conv/euc_jp_to_utf8.mapconv/euc_jp_to_utf8.extra 中。对于每个字符,首先查询普通映射。如果没有匹配,则查询额外映射。如果还没有匹配,则会引发错误。

普通映射的内容与 LightDB 提供的默认从 EUC_JP 到 UTF-8 的转换映射 euc_jp_to_utf8 相同。额外映射包含一些普通映射没有的映射(例如,以下罗马数字和全角符号的映射)。

EUC_JP UTF-8 描述
fcf1 e285b0 (U+2170) 小型罗马数字一
fcf2 e285b1 (U+2171) 小型罗马数字二
fcf3 e285b2 (U+2172) 小型罗马数字三
fcf4 e285b3 (U+2173) 小型罗马数字四
fcf5 e285b4 (U+2174) 小型罗马数字五
fcf6 e285b5 (U+2175) 小型罗马数字六
fcf7 e285b6 (U+2176) 小型罗马数字七
fcf8 e285b7 (U+2177) 小型罗马数字八
fcf9 e285b8 (U+2178) 小型罗马数字九
fcfa e285b9 (U+2179) 小型罗马数字十
fcfb efbfa2 (U+FFE2) 全角非符号
fcfc efbfa4 (U+FFE4) 全角破折号
fcfd efbc87 (U+FF07) 全角撇号
fcfe efbc82 (U+FF02) 全角双引号

要将pg_euc_jp_to_utf8作为EUC_JP到UTF-8的默认转换方式,需要启用其 pg_conversion .condefault。 同时需要禁用euc_jp_to_utf8(从EUC_JP到UTF-8的内置转换)的condefault。 这里是这些目录更新的示例:

=# BEGIN;
=# UPDATE pg_conversion SET condefault = 'f' WHERE conname = 'euc_jp_to_utf8';
=# UPDATE pg_conversion SET condefault = 't' WHERE conname = 'pg_euc_jp_to_utf8';
=# COMMIT;

可以通过直接修改映射文件并重建lt_cheat_funcs模块来使用自定义的转换映射表。 注意,映射文件中的条目必须按升序排序。

E.11.3. 配置参数

请注意,如果要使用该扩展提供的配置参数,必须将 shared_preload_librariessession_preload_libraries 设置为lt_cheat_funcs,并写入到lightdb.conf文件中。

E.11.3.1. lt_cheat_funcs.log_memory_context (布尔类型)

在查询执行结束时记录有关内存上下文的统计信息。有关日志格式的详细信息,请参见 pg_stat_print_memory_context()。 默认情况下,此参数处于关闭状态。只有超级用户可以更改此设置。

E.11.3.2. lt_cheat_funcs.hide_appname (布尔类型)

如果为True,则忽略客户端的application_name,并将其设置值存储在lt_cheat_funcs.hidden_appname参数中。 默认情况下,此参数设置为False,因此将使用客户指定的字符串作为应用程序名称。 此参数仅可在lightdb.conf文件中或服务器命令行中设置。

E.11.3.3. lt_cheat_funcs.hidden_appname (字符串类型)

报告客户端隐藏的应用程序名称。默认为空字符串。任何用户都可以更改此设置。

E.11.3.4. lt_cheat_funcs.log_session_start_options (布尔类型)

记录在连接开始时发送到服务器的选项。默认情况下,此参数处于关闭状态。 只有超级用户可以在会话开始时更改此参数,并且无法在会话内部更改此参数。

E.11.3.5. lt_cheat_funcs.scheduling_priority (整数类型)

指定LightDB服务器进程的调度优先级(nice)。有效值介于-20和19之间。 较低的值会导致更有利的调度。默认值为0。任何用户都可以更改此设置。 有关调度优先级的详细信息,请参见getpriority(2)手册页。

E.11.3.6. lt_cheat_funcs.exit_on_segv (布尔类型)

如果为off,则缺页中断将导致服务器崩溃。如果为on,则仅终止导致缺页中断的当前会话。 默认值为off。任何用户都可以更改此设置。