Thread: Improve documentation regarding custom settings, placeholders, and the administrative functions

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>

On Oct 20, 2024 at 04:12 +0800, David G. Johnston <david.g.johnston@gmail.com>, wrote:

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.

-        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

Hi,

current_setting() could return NULL when missing_ok is passed, so is it right to say: Returns the current non-null value of the setting <parameter>setting_name</parameter>?
As the doc is for function of current_setting(), and it could return NULL actually.

On Feb 6, 2025 at 10:49 +0800, David G. Johnston <david.g.johnston@gmail.com>, wrote:

Yes, and when it does it is doing so in lieu of an error, and thus it is not returning the value of the setting.  It does not mean the value taken on by the named parameter is NULL, which is not possible. i.e., SHOW will never produce NULL.

Hi,

OK, LGTM.

On 19/10/2024 23:11, David G. Johnston wrote:
> 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>

Feels a bit obtuse to be honest. Who would've thought that they can be
NULL? They're not regular SQL datatypes, after all.

> @@ -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>

-1, this completely removes the explanation of what a placeholder
variable is, but the term placeholder is still used in the text that
follows.

> +
> +    <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>

Placeholders can be created in postgresql.conf too, so this emphasis on
"created in a session" feels a bit off.

> 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

Feels a bit cavalier to mention the "non-null" like this. I understand
that you wanted to make it clear that when current_setting() returns
NULL, it means that the setting did not exist and you used
missing_ok=true. But to deduce that, you still need to know that the
value cannot be NULL. Otherwise you're left wondering what the function
would return for NULL values, since this only describes what it returns
for non-null values.

> @@ -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>

+1 on this part. Committed this paragraph so that we can make some
incremental progress.

> +       <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>

I was sold on this at first, but then I realized that the SET
documentation doesn't mention placeholder variables either. I think it
would be better to document them for SET, there's more room for
discussion there than in this table. The set_config() documentation
already mentions that it corresponds to the SET command.