From 9cd92d1a33699f86aa53d44ab04cc3eb50c18d11 Mon Sep 17 00:00:00 2001
From: Michael Paquier <michael@paquier.xyz>
Date: Fri, 5 Oct 2018 09:21:48 +0900
Subject: Add pg_ls_tmpdir function

This lists the contents of a temporary directory associated to a given
tablespace, useful to get information about on-disk consumption caused
by temporary files used by a session query.  By default, pg_default is
scanned, and a tablespace can be specified as argument.

This function is intended to be used by monitoring tools, and, unlike
pg_ls_dir(), access to them can be granted to non-superusers so that
those monitoring tools can observe the principle of least privilege.
Access is also given by default to members of pg_monitor.

Author: Nathan Bossart
Reviewed-by: Laurenz Albe
Discussion: https://postgr.es/m/92F458A2-6459-44B8-A7F2-2ADD3225046A@amazon.com
---
 doc/src/sgml/func.sgml | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

(limited to 'doc/src')

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 9a7f6836581..f984d069e1f 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -20355,6 +20355,20 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
         role and may be granted to other non-superuser roles.
        </entry>
       </row>
+      <row>
+       <entry>
+        <literal><function>pg_ls_tmpdir(<optional><parameter>tablespace</parameter> <type>oid</type></optional>)</function></literal>
+       </entry>
+       <entry><type>setof record</type></entry>
+       <entry>
+        List the name, size, and last modification time of files in the
+        temporary directory for <parameter>tablespace</parameter>.  If
+        <parameter>tablespace</parameter> is not provided, the
+        <literal>pg_default</literal> tablespace is used.  Access is granted
+        to members of the <literal>pg_monitor</literal> role and may be
+        granted to other non-superuser roles.
+       </entry>
+      </row>
       <row>
        <entry>
         <literal><function>pg_read_file(<parameter>filename</parameter> <type>text</type> [, <parameter>offset</parameter> <type>bigint</type>, <parameter>length</parameter> <type>bigint</type> [, <parameter>missing_ok</parameter> <type>boolean</type>] ])</function></literal>
@@ -20428,6 +20442,19 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
     <command>GRANT</command>.
    </para>
 
+   <indexterm>
+    <primary>pg_ls_tmpdir</primary>
+   </indexterm>
+   <para>
+    <function>pg_ls_tmpdir</function> returns the name, size, and last modified
+    time (mtime) of each file in the temporary file directory for the specified
+    <parameter>tablespace</parameter>.  If <parameter>tablespace</parameter> is
+    not provided, the <literal>pg_default</literal> tablespace is used.  By
+    default only superusers and members of the <literal>pg_monitor</literal>
+    role can use this function.  Access may be granted to others using
+    <command>GRANT</command>.
+   </para>
+
    <indexterm>
     <primary>pg_read_file</primary>
    </indexterm>
-- 
cgit v1.2.3