Add pg_ls_summariesdir().

This function returns the name, size, and last modification time of
each regular file in pg_wal/summaries.  This allows administrators
to grant privileges to view the contents of this directory without
granting privileges on pg_ls_dir(), which allows listing the
contents of many other directories.  This commit also gives the
pg_monitor predefined role EXECUTE privileges on the new
pg_ls_summariesdir() function.

Bumps catversion.

Author: Yushi Ogiwara
Reviewed-by: Michael Paquier, Fujii Masao
Discussion: https://postgr.es/m/a0a3af15a9b9daa107739eb45aa9a9bc%40oss.nttdata.com

Author: nathan-bossart

doc/src/sgml/func.sgml

@@ -30530,6 +30530,30 @@ SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size
        </para></entry>
       </row>
 
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>pg_ls_summariesdir</primary>
+        </indexterm>
+        <function>pg_ls_summariesdir</function> ()
+        <returnvalue>setof record</returnvalue>
+        ( <parameter>name</parameter> <type>text</type>,
+        <parameter>size</parameter> <type>bigint</type>,
+        <parameter>modification</parameter> <type>timestamp with time zone</type> )
+       </para>
+       <para>
+        Returns the name, size, and last modification time (mtime) of each
+        ordinary file in the server's WAL summaries directory
+        (<filename>pg_wal/summaries</filename>).  Filenames beginning
+        with a dot, directories, and other special files are excluded.
+       </para>
+       <para>
+        This function is restricted to superusers and members of
+        the <literal>pg_monitor</literal> role by default, but other users can
+        be granted EXECUTE to run the function.
+       </para></entry>
+      </row>
+
       <row>
        <entry role="func_table_entry"><para role="func_signature">
         <indexterm>

src/backend/catalog/system_functions.sql

@@ -700,6 +700,8 @@ REVOKE EXECUTE ON FUNCTION pg_ls_waldir() FROM public;
 
 REVOKE EXECUTE ON FUNCTION pg_ls_archive_statusdir() FROM public;
 
+REVOKE EXECUTE ON FUNCTION pg_ls_summariesdir() FROM public;
+
 REVOKE EXECUTE ON FUNCTION pg_ls_tmpdir() FROM public;
 
 REVOKE EXECUTE ON FUNCTION pg_ls_tmpdir(oid) FROM public;
@@ -770,6 +772,8 @@ GRANT EXECUTE ON FUNCTION pg_ls_waldir() TO pg_monitor;
 
 GRANT EXECUTE ON FUNCTION pg_ls_archive_statusdir() TO pg_monitor;
 
+GRANT EXECUTE ON FUNCTION pg_ls_summariesdir() TO pg_monitor;
+
 GRANT EXECUTE ON FUNCTION pg_ls_tmpdir() TO pg_monitor;
 
 GRANT EXECUTE ON FUNCTION pg_ls_tmpdir(oid) TO pg_monitor;

src/backend/utils/adt/genfile.c

@@ -689,6 +689,15 @@ pg_ls_archive_statusdir(PG_FUNCTION_ARGS)
 	return pg_ls_dir_files(fcinfo, XLOGDIR "/archive_status", true);
 }
 
+/*
+ * Function to return the list of files in the WAL summaries directory.
+ */
+Datum
+pg_ls_summariesdir(PG_FUNCTION_ARGS)
+{
+	return pg_ls_dir_files(fcinfo, XLOGDIR "/summaries", true);
+}
+
 /*
  * Function to return the list of files in the PG_LOGICAL_SNAPSHOTS_DIR
  * directory.

src/include/catalog/catversion.h

@@ -57,6 +57,6 @@
  */
 
 /*							yyyymmddN */
-#define CATALOG_VERSION_NO	202410112
+#define CATALOG_VERSION_NO	202410113
 
 #endif

src/include/catalog/pg_proc.dat

@@ -12186,6 +12186,12 @@
   provolatile => 'v', prorettype => 'record', proargtypes => '',
   proallargtypes => '{text,int8,timestamptz}', proargmodes => '{o,o,o}',
   proargnames => '{name,size,modification}', prosrc => 'pg_ls_waldir' },
+{ oid => '9220', descr => 'list of files in the pg_wal/summaries directory',
+  proname => 'pg_ls_summariesdir', procost => '10', prorows => '20',
+  proretset => 't', provolatile => 'v', prorettype => 'record',
+  proargtypes => '', proallargtypes => '{text,int8,timestamptz}',
+  proargmodes => '{o,o,o}', proargnames => '{name,size,modification}',
+  prosrc => 'pg_ls_summariesdir' },
 { oid => '5031', descr => 'list of files in the archive_status directory',
   proname => 'pg_ls_archive_statusdir', procost => '10', prorows => '20',
   proretset => 't', provolatile => 'v', prorettype => 'record',

src/test/regress/expected/misc_functions.out

@@ -412,6 +412,12 @@ select count(*) >= 0 as ok from pg_ls_archive_statusdir();
  t
 (1 row)
 
+select count(*) >= 0 as ok from pg_ls_summariesdir();
+ ok 
+----
+ t
+(1 row)
+
 -- pg_read_file()
 select length(pg_read_file('postmaster.pid')) > 20;
  ?column? 

src/test/regress/sql/misc_functions.sql

@@ -163,6 +163,7 @@ select (w).size = :segsize as ok
 from (select pg_ls_waldir() w) ss where length((w).name) = 24 limit 1;
 
 select count(*) >= 0 as ok from pg_ls_archive_statusdir();
+select count(*) >= 0 as ok from pg_ls_summariesdir();
 
 -- pg_read_file()
 select length(pg_read_file('postmaster.pid')) > 20;