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>