Help Center/ GaussDB/ Developer Guide(Centralized_V2.0-8.x)/ SQL Reference/ Functions and Operators/ System Administration Functions/ Universal File Access Functions
Updated on 2025-05-29 GMT+08:00
View PDF
Share

Universal File Access Functions

Universal file access functions provide local access APIs for files on a database server. Only files in the database directory and the log_directory directory can be accessed. A relative path is used for files in the database directory, and a path matching the log_directory configuration setting is used for log files. Only the database initial user can use these functions.

pg_ls_dir(dirname text)

Description: Lists files in a directory.

Return type: setof text

Note: pg_ls_dir returns all the names in the specified directory, except the special entries "." and "..".

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
 
gaussdb=# SELECT pg_ls_dir('./');
      pg_ls_dir       
----------------------
 .gaussdb.conf.swp
 gaussdb.conf
 pg_tblspc
 PG_VERSION
 gs_ident.conf
 core
 server.crt
 pg_serial
 pg_twophase
 gaussdb.conf.lock
 pg_stat_tmp
 pg_notify
 pg_subtrans
 pg_ctl.lock
 pg_xlog
 pg_clog
 base
 pg_snapshots
 postmaster.opts
 postmaster.pid
 server.key.rand
 server.key.cipher
 pg_multixact
 pg_errorinfo
 server.key
 gs_hba.conf
 pg_replslot
 .gs_hba.conf.swp
 cacert.pem
 gs_hba.conf.lock
 global
 gaussdb.state
(32 rows)

pg_read_file(filename text, offset bigint, length bigint)

Description: Returns the content of a text file.

Return type: text

Note: pg_read_file returns part of a text file. It can return a maximum of length bytes from offset. The actual size of fetched data is less than length if the end of the file is reached first. If offset is negative, it is the length rolled back from the file end. If offset and length are omitted, the entire file is returned.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
gaussdb=# SELECT pg_read_file('postmaster.pid',0,100);
             pg_read_file              
---------------------------------------
 53078                                +
 /srv/BigData/hadoop/data1/dbnode+
 1500022474                           +
 8000                                +
 /var/run/FusionInsight               +
 localhost                            +
  2
(1 row)

pg_read_binary_file(filename text [, offset bigint, length bigint,missing_ok boolean])

Description: Returns the content of a binary file. In the multi-tenancy scenario, this function runs properly if it is called in a non-PDB, and an error is reported if it is called in a PDB.

Return type: bytea

Note: pg_read_binary_file is similar to pg_read_file, except that the result is a bytea value; accordingly, no encoding checks are performed. In combination with the convert_from function, this function can be used to read a file in a specified encoding.

1
 
gaussdb=# SELECT convert_from(pg_read_binary_file('filename'), 'UTF8');

pg_read_binary_file_blocks(filename text, blocknum bigint, blockcount bigint)

Description: Returns the binary content of a specified page area of a compressed file. In the multi-tenancy scenario, this function runs properly if it is called in a non-PDB, and an error is reported if it is called in a PDB.

Return type: bytea

Note: pg_read_binary_file_blocks is used only to read the binary content of a compressed file.

pg_stat_file(filename text)

Description: Returns status information about a file.

Return type: record

Note: pg_stat_file returns a record containing the file size, last access timestamp, last modification timestamp, last file status change timestamp, and a Boolean value indicating if it is a directory. Typical usages are as follows:

1
 
gaussdb=# SELECT * FROM pg_stat_file('filename');

1
 
gaussdb=# SELECT (pg_stat_file('filename')).modification;

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
 
gaussdb=# SELECT convert_from(pg_read_binary_file('postmaster.pid'), 'UTF8');
             convert_from             
--------------------------------------
 4881                                +
 /srv/BigData/gaussdb/data1/dbnode+
 1496308688                          +
 25108                               +
 /opt/user/Bigdata/gaussdb/gaussdb_tmp +
 *                                   +
  25108001  43352069                 +

(1 row)

1
2
3
4
5
6
7
8
9
 
gaussdb=# SELECT * FROM pg_stat_file('postmaster.pid');
 
 size |         access         |      modification      |         change         
| creation | isdir 
------+------------------------+------------------------+------------------------
+----------+-------
  117 | 2017-06-05 11:06:34+08 | 2017-06-01 17:18:08+08 | 2017-06-01 17:18:08+08 
|          | f
(1 row)

1
2
3
4
5
 
gaussdb=# SELECT (pg_stat_file('postmaster.pid')).modification;
      modification      
------------------------
 2017-06-01 17:18:08+08
(1 row)