Improve documentation regarding custom settings, placeholders, and the administrative functions - Mailing list pgsql-hackers

Hey!

Motivated by recent user complaints regarding our documentation of behavior in this area I propose the following to shore things up a bit.

There may be other places that need this coverage but it seems the most likely place our users are going to experience this behavior is in using set_config and current_setting.

Mostly I'm pointing out the fact that one can never take the null value to be the actual value of a setting.  In terms of current_setting this then establishes the fact that the null value it may return is an error-handling alternative only and not something to be relied upon as being an actual value of the setting.

The change to custom options and set_config point expands on the "placeholder" concept already Introduced and just documents that set_config can and will create such placeholders implicitly.

Also, in realizing that the null value is not technically a valid input for new_value in set_config, a paragraph is added to explain how the null value gets interpreted.

I sorta get not wanting to encourage the use of custom options but saying "have no function" just doesn't make sense.  The certainly exist, and as data they don't have any function on their own anyway.  The surrounding discussion regarding extensions gets the same point across sufficiently without stating that an external loadable module is required when it is not.

David J.

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 934ef5e469..4478d0aa91 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -23,7 +23,7 @@
 
     <para>
      All parameter names are case-insensitive. Every parameter takes a
-     value of one of five types: boolean, string, integer, floating point,
+     non-null value of one of five types: boolean, string, integer, floating point,
      or enumerated (enum).  The type determines the syntax for setting the
      parameter:
     </para>
@@ -11350,14 +11350,20 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
     <para>
      Because custom options may need to be set in processes that have not
      loaded the relevant extension module, <productname>PostgreSQL</productname>
-     will accept a setting for any two-part parameter name.  Such variables
-     are treated as placeholders and have no function until the module that
-     defines them is loaded. When an extension module is loaded, it will add
+     will accept a setting for any two-part parameter name.
+     When an extension module is loaded, it will add
      its variable definitions and convert any placeholder values according to
      those definitions.  If there are any unrecognized placeholders
      that begin with its extension name, warnings are issued and those
      placeholders are removed.
     </para>
+
+    <para>
+     If a placeholder is created in a session it will exist for the
+     lifetime of the session unless removed by an extension.
+     Placeholders have a string data type with a reset value of the empty string.
+    </para>
+
    </sect1>
 
    <sect1 id="runtime-config-developer">
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index ad663c94d7..605bf533ee 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -28157,7 +28157,7 @@ acl      | {postgres=arwdDxtm/postgres,foo=r/postgres}
         <returnvalue>text</returnvalue>
        </para>
        <para>
-        Returns the current value of the
+        Returns the current non-null value of the
         setting <parameter>setting_name</parameter>.  If there is no such
         setting, <function>current_setting</function> throws an error
         unless <parameter>missing_ok</parameter> is supplied and
@@ -28191,6 +28191,17 @@ acl      | {postgres=arwdDxtm/postgres,foo=r/postgres}
         use <literal>false</literal> instead. This function corresponds to
         the SQL command <xref linkend="sql-set"/>.
        </para>
+       <para>
+        <function>set_config</function> accepts the NULL value for
+        <parameter>new_value</parameter>, but as settings cannot be null this input
+        is interpreted as a request to set the setting to its default value.
+       </para>
+       <para>
+        If <parameter>setting_name</parameter> does not already exist
+        <function>set_config</function> throws an error unless the identifier is a valid
+        <link linkend="runtime-config-custom">custom option</link> name, in which it
+        creates a placeholder with the empty string as its old value.
+       </para>
        <para>
         <literal>set_config('log_statement_stats', 'off', false)</literal>
         <returnvalue>off</returnvalue>