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

On Fri, Apr 4, 2025 at 5:19 AM Heikki Linnakangas <hlinnaka(at)iki(dot)fi> wrote:

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

People aren't thinking about nullability at all when they read
this, whether the differences between these and regular SQL data types
even dawns on them. But my belief in adding that minor point is that at
some point in the future when someone goes to write:

coalesce(current_setting('prefix.name', true), 'default-value')

they may have read, and stuck in the recesses of their mind, the "non-null
value" bit and go "why am I using coalesce if the value cannot be null?".

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

I accidentally removed the labelling of the set of settings meeting
"two-part parameter name" as "placeholders". There isn't an explanation of
what they are beyond that. There is an explanation of how they are
treated, which I've left unmodified, aside from the counter-productive
commentary about "have no function until the module that defines them is
loaded" since they are enabling functionality every day by people without
the use of extensions.

The fix is to just add back the label:

... will accept a setting for any two-part parameter name, called
placeholders.
When an extension module is loaded, it will add ...

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

If someone claims the following is a bug:
login
current_setting('ctx.name'); // error
set_config('ctx.name', 'whatever');
reset
current_setting('ctx.name'); // empty string
// ^ bug - reset should make that an error again

I will point them right to this section and paragraph. Hopefully they just
read it first; and can translate it to SQL. The pending "NULL Overview"
documentation fills in that final gap in explanation.

People aren't sticking their custom context settings into postgresql.conf;
or if they are, they aren't reporting the aforementioned bug.

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

I had this concern too, then added the obtuse "non-null" wording to
config.sgml to address that in the definitional location.

To keep it closer to the problematic area, we can say:

Returns the current value (which is unable to be the null value) of the

I like this better but would still leave the non-null modifier in
config.sgml as part of the definition of a setting.

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

Thank you.

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

Good catch. I will do that.

My next patch is going to include my take on the disputed items above
unless you change your mind and commit them before I get around to it. As
shown, you or someone else can just omit them again if my reasoning isn't
sufficiently convincing.

David J.