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

Thoughts? Anyone?

On Sat, Oct 19, 2024 at 1:11 PM David G. Johnston <
david(dot)g(dot)johnston(at)gmail(dot)com> wrote:

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