KingbaseES数据库与系统文件交互函数

一、函数列表

sys_ls_archive_statusdir    --返回WAL归档状态目录（sys_wal/archive_status）中的每个文件的名称、大小和最后修改时间。
sys_ls_dir                  --返回指定目录下的所有文件和子目录。
sys_ls_logdir               --返回KingbaseES数据库日志目录中的每个文件的名称、大小和最后修改时间。
sys_ls_tmpdir               --返回KingbaseES数据库临时文件目录中的每个文件的名称、大小和最后修改时间。
sys_ls_waldir               --返回KingbaseES数据库的日志（WAL）目录中的每个文件的名称、大小和最后修改时间。
sys_read_binary_file        --读取指定的二进制文件，返回一个字节类型的值。
sys_read_file               --读取指定的文本文件，返回一个字符串类型的值。
sys_stat_file               --获取数据库服务器上的文件的状态信息.

二、函数功能及使用方法

sys_ls_archive_statusdir函数:

   Schema    |           Name           | Result data type |                            Argument data types                            | Type 
-------------+--------------------------+------------------+---------------------------------------------------------------------------+------
 sys_catalog | sys_ls_archive_statusdir | SETOF record     | name OUT text, size OUT bigint, modification OUT timestamp with time zone | func

• sys_ls_archive_statusdir函数没有参数。
• sys_ls_archive_statusdir函数返回值：
  • name：归档状态文件的名称。
  • size：归档状态文件的大小，以字节为单位。
  • modification：归档状态文件最后一次被修改的时间戳。

使用sys_ls_archive_statusdir函数:

-- 列出归档状态目录中的所有文件
select * from sys_ls_archive_statusdir();

-- 列出未归档的WAL文件
select name from sys_ls_archive_statusdir() where name like '%.ready';

-- 列出正在归档的WAL文件
select name from sys_ls_archive_statusdir() where name like '%.inprogress';

-- 列出已归档的WAL文件
select name from sys_ls_archive_statusdir() where name like '%.done';

• sys_ls_archive_statusdir使用：
  • 只有超级用户才能使用这个函数。

sys_ls_dir函数:

   Schema    |    Name    | Result data type |  Argument data types   | Type 
-------------+------------+------------------+------------------------+------
 sys_catalog | sys_ls_dir | SETOF text       | text                   | func
 sys_catalog | sys_ls_dir | SETOF text       | text, boolean, boolean | func

• sys_ls_dir参数：sys_ls_dir(dirname text [,missing_ok boolean, include_dot_dirs boolean]) setof text
  • dirname：要列出的目录名，必须是相对于数据目录的路径。
  • missing_ok：可选参数，表示如果目录不存在是否返回空集合。
  • include_dot_dirs：可选参数，表示是否包含以点开头的隐藏目录。
• sys_ls_dir函数返回值：
  • 是一个文本类型的集合，每个元素是一个文件或子目录的名称。

sys_ls_dir函数:

-- 列出数据库服务器上的根目录下的所有文件和子目录
select * from sys_ls_dir('/');

-- 列出数据库服务器kingbase用户下的data目录所有文件和子目录，包括隐藏目录
select * from sys_ls_dir('/home/kingbase/data', false, true);

• sys_ls_dir使用：
  • 只有超级用户才能使用这个函数。
  • 目录必须有可读权限，否则会报错。

sys_ls_logdir函数:

   Schema    |     Name      | Result data type |                            Argument data types                            | Type 
-------------+---------------+------------------+---------------------------------------------------------------------------+------
 sys_catalog | sys_ls_logdir | SETOF record     | name OUT text, size OUT bigint, modification OUT timestamp with time zone | func

• sys_ls_logdir没有可选参数：默认为KingbaseES数据库日志目录。
• sys_ls_logdir函数返回值：
  • name是文件或目录的名称，size是文件或目录的大小（字节）。
  • modification是文件或目录的最后修改时间。
  • isdir是一个布尔值，表示是否是一个目录。

使用sys_ls_logdir函数:

-- 列出当前数据库日志文件目录中的所有文件
select * from sys_ls_logdir();

• sys_ls_logdir使用：
  • 只有超级用户才能使用这个函数。

sys_ls_tmpdir函数:

   Schema    |     Name      | Result data type |                                    Argument data types                                    | Type 
-------------+---------------+------------------+-------------------------------------------------------------------------------------------+------
 sys_catalog | sys_ls_tmpdir | SETOF record     | name OUT text, size OUT bigint, modification OUT timestamp with time zone                 | func
 sys_catalog | sys_ls_tmpdir | SETOF record     | tablespace oid, name OUT text, size OUT bigint, modification OUT timestamp with time zone | func

• sys_ls_tmpdir参数:
  • tablespace：表空间的OID，如果省略则默认为当前数据库的默认表空间。
• sys_ls_tmpdir返回值：
  • name是文件或目录的名称
  • size是文件或目录的大小（字节）
  • modification是文件或目录的最后修改时间
  • isdir是一个布尔值，表示是否是一个目录。

使用sys_ls_tmpdir函数:

-- 列出当前数据库默认表空间的临时文件目录中的所有文件和目录
select * from sys_ls_tmpdir();

-- 列出指定表空间的临时文件目录中的所有文件和目录
select * from sys_ls_tmpdir(1663);

• sys_ls_tmpdir使用：
  • 只有超级用户才能使用这个函数。

sys_ls_waldir函数:

   Schema    |     Name      | Result data type |                            Argument data types                            | Type 
-------------+---------------+------------------+---------------------------------------------------------------------------+------
 sys_catalog | sys_ls_waldir | SETOF record     | name OUT text, size OUT bigint, modification OUT timestamp with time zone | func

• sys_ls_waldir函数没有参数。
• sys_ls_waldir返回值：
  • name：WAL文件的名称。
  • size：WAL文件的大小，以字节为单位。
  • modification：WAL文件最后一次被修改的时间戳。

使用sys_ls_waldir函数:

-- 列出服务器的写前日志（WAL）目录中的所有文件和目录
select * from sys_ls_waldir();

• sys_ls_waldir使用：
  • 只有超级用户才能使用这个函数。

sys_read_binary_file函数:

   Schema    |         Name         | Result data type |      Argument data types      | Type 
-------------+----------------------+------------------+-------------------------------+------
 sys_catalog | sys_read_binary_file | bytea            | text                          | func
 sys_catalog | sys_read_binary_file | bytea            | text, bigint, bigint          | func
 sys_catalog | sys_read_binary_file | bytea            | text, bigint, bigint, boolean | func

• sys_read_binary_file参数：
  • filename：要读取的文件名，必须是相对于数据目录的路径。
  • offset：要开始读取的字节偏移量，从0开始。
  • length：要读取的字节数，如果超过文件大小，则返回整个文件。
• sys_read_binary_file返回值：
  • 一个bytea值，表示从文件中读取的二进制数据。

使用sys_read_binary_file函数:

-- 读取数据目录下的kingbase.conf文件的前100个字节
select sys_read_binary_file('kingbase.conf', 0, 100);

• sys_read_binary_file使用：
  • 只有超级用户才能使用这个函数。
  • 文件必须在数据目录或其子目录下，不能在其他位置。
  • 文件必须有可读权限，否则会报错。

sys_read_file函数:

   Schema    |     Name      | Result data type |      Argument data types      | Type 
-------------+---------------+------------------+-------------------------------+------
 sys_catalog | sys_read_file | text             | text                          | func
 sys_catalog | sys_read_file | text             | text, bigint, bigint          | func
 sys_catalog | sys_read_file | text             | text, bigint, bigint, boolean | func

• sys_read_file参数：
  • filename：要读取的文件名，必须是相对于数据目录的路径。
  • offset：要开始读取的字节偏移量，从0开始。
  • length：要读取的字节数，如果超过文件大小，则返回整个文件。
• sys_read_file返回值：
  • 一个文本值，表示从文件中读取的内容。

使用sys_read_file函数:

-- 读取数据目录下的kingbase.conf文件的前100个字节
select sys_read_file('kingbase.conf', 0, 100);

• sys_read_file使用：
  • 只有超级用户才能使用这个函数。
  • 文件必须是文本格式，不能是二进制格式。
  • 文件必须在数据目录或其子目录下，不能在其他位置。
  • 文件必须有可读权限，否则会报错。

sys_stat_file函数:

   Schema    |     Name      | Result data type |                                                                                                        Argument data types                                                                                                        | Type 
-------------+---------------+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------
 sys_catalog | sys_stat_file | record           | filename text, missing_ok boolean, size OUT bigint, access OUT timestamp with time zone, modification OUT timestamp with time zone, change OUT timestamp with time zone, creation OUT timestamp with time zone, isdir OUT boolean | func
 sys_catalog | sys_stat_file | record           | filename text, size OUT bigint, access OUT timestamp with time zone, modification OUT timestamp with time zone, change OUT timestamp with time zone, creation OUT timestamp with time zone, isdir OUT boolean                     | func

• sys_stat_file参数：
  • filename：要获取状态信息的文件名，必须是相对于数据目录的路径。
• sys_stat_file返回值是：
  • size：文件的大小，以字节为单位。
  • access：文件最后一次被访问的时间戳。
  • modification：文件最后一次被修改的时间戳。
  • change：文件最后一次状态改变的时间戳。
  • creation：文件创建的时间戳，如果不可用则为null。
  • isdir：文件是否是一个目录。

使用sys_stat_file函数:

--读取数据目录下的kingbase.conf文件的状态信息
select * from pg_stat_file('kingbase.conf');

• sys_stat_file使用：
  • 只有超级用户才能使用这个函数。
  • 文件必须在数据目录或其子目录下，不能在其他位置。
  • 文件必须有可读权限，否则会报错。