Thread

[PATCH v7 06/16] Provide examples of listing all settings

Karl O. Pinc <kop@karlpinc.com> — 2023-09-25T20:36:23Z

This commit is problematic in that it does something that is not done
elsewhere in the documentation, it provides example SELECTs as a
stand-in for a regular tabular documentation element.  It is almost
something that should go in its own appendix, but I don't think that
is warranted.  Likewise, I think that having another tabular
documentation element that must be maintained and kept up-to-date is
also not appropriate.

It is useful to have tabular overviews of all available system
settings, as is having an overview of the setting values of your
particular cluster.  This commit is an attempt in that direction.
---
 doc/src/sgml/config.sgml | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 97f9838bfb..0af4e6dcae 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -11,6 +11,43 @@
   <para>
    There are many configuration parameters that affect the behavior of
    the database system.
+   A single master list of all parameters and their characteristics is not
+   provided in this document.
+   Use the <link linkend="bookindex">index</link> (or web search) to find
+   configuration parameter documentation by name.
+  </para>
+
+  <indexterm>
+    <primary>pg_settings</primary>
+    <secondary>example queries</secondary>
+  </indexterm>
+
+  <indexterm>
+    <primary>configuration</primary>
+    <secondary>query the current settings</secondary>
+  </indexterm>
+
+  <para>
+   The <link linkend="view-pg-settings">pg_settings</link>
+   <link linkend="tutorial-views">view</link> into
+   the <link linkend="catalogs">system catalogs</link> provides summaries of
+   all, or selected, configuration parameters, e.g:
+  </para>
+
+<programlisting>
+-- Describe all configuration parameters.
+SELECT name, short_desc FROM pg_settings ORDER BY name;
+
+-- Show the current configuration of the connected cluster, database,
+-- and session.
+SELECT name, setting, unit FROM pg_settings ORDER BY name;
+
+-- Show the means available to change the setting; whether the setting is
+-- per-cluster, per-database, per-session, etc.
+SELECT name, context FROM pg_settings ORDER BY name;
+</programlisting>
+  
+  <para>
    The first section of this chapter describes how to interact with
    configuration parameters.
    Subsequent sections discuss each parameter in detail.
-- 
2.30.2


--MP_/VSGM3xNEmY7iJyL2wuWRCjV
Content-Type: text/x-patch
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename=v7-0007-Cleanup-summary-of-role-powers.patch