Date: Tue, 24 Oct 2023 13:07:28 -0400
From: Bruce Momjian <bruce@momjian.us>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: "Jonathan S. Katz" <jkatz@postgresql.org>,
	"David G. Johnston" <david.g.johnston@gmail.com>, splarv@ya.ru,
	pgsql-docs@lists.postgresql.org
Subject: Re: 'value' has special behaviour in alter system
Message-ID: <ZTf50EnaCrfbyWaV@momjian.us>
References: <167105927893.1897.13227723035830709578@wrigleys.postgresql.org>
 <CAKFQuwbefvj25vYz-0KJ-62oCg8-BxAd3PButBZTJ-7PzUcGbQ@mail.gmail.com>
 <f601ac59-16f9-0b75-2831-e212bae7fda5@postgresql.org>
 <3417417.1671124227@sss.pgh.pa.us>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="yW6ZNzmRtM0KKyrR"
Content-Disposition: inline
In-Reply-To: <3417417.1671124227@sss.pgh.pa.us>
Archived-At: 
 <https://www.postgresql.org/message-id/ZTf50EnaCrfbyWaV%40momjian.us>
Precedence: bulk


--yW6ZNzmRtM0KKyrR
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Thu, Dec 15, 2022 at 12:10:27PM -0500, Tom Lane wrote:
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
> > On 12/15/22 10:50 AM, David G. Johnston wrote:
> >> I suggest changing it to:
> >> SET configuration_parameter { TO | = } { value [, ...] | DEFAULT }
> 
> > +1 in general. I would also suggest we add an example in the Examples 
> > section to show what the output is when you add single-quotes.
> 
> I think the core problem here is that the syntax diagram and discussion
> don't clearly discuss the behavior for list values.  David's version of
> the syntax diagram looks fine, but not sure about the text.  There likely
> needs to be some explicit acknowledgement of the fact that some GUCs
> act differently than others (cf GUC_LIST_INPUT and GUC_LIST_QUOTE flags).
> 
> +1 for examples, for sure.

Finally getting back to this, there is a lot going on and Tom is right
that the inconsistent use of GUC_LIST_QUOTE adds a lot of confusion. 
Here are the list settings, and which ones add double-quotes to
non-alphanumeric quoted values:

	GUC_LIST_QUOTE (adds quotes)
	temp_tablespaces
	session_preload_libraries
	shared_preload_libraries
	local_preload_libraries
	search_path
	unix_socket_directories

	NO GUC_LIST_QUOTE (does not add quotes)
	DateStyle
	createrole_self_grant
	log_destination
	listen_addresses
	synchronous_standby_names
	wal_consistency_checking
	debug_io_direct

and this leads to different quoting behaviors depending on which
category of list you are using.  First, let's look at alphanumeric
values, which are treated the same by list types with different
GUC_LIST_QUOTE statuses:

	ALTER SYSTEM SET shared_preload_libraries TO a, b, c;
	.conf	shared_preload_libraries = 'a, b, c'

	ALTER SYSTEM SET listen_addresses TO a, b, c;
	.conf	listen_addresses = 'a, b, c'

Even with quotes, the output is the same:

	ALTER SYSTEM SET shared_preload_libraries TO a, 'b', c;
	.conf	shared_preload_libraries = 'a, b, c'
	
	ALTER SYSTEM SET shared_preload_libraries TO a, "b", c;
	.conf	shared_preload_libraries = 'a, b, c'

	ALTER SYSTEM SET listen_addresses TO a, 'b', c;
	.conf	listen_addresses = 'a, b, c'

	ALTER SYSTEM SET listen_addresses TO a, "b", c;
	.conf	listen_addresses = 'a, b, c'

With non-alphanumeric (spaces), there is a difference:

	ALTER SYSTEM SET shared_preload_libraries TO a, 'b x', c;
	.conf	shared_preload_libraries = 'a, "b x", c'
	
	ALTER SYSTEM SET listen_addresses TO a, 'b x', c;
	.conf	listen_addresses = 'a, b x, c'

For listen_addresses to get the quoting behavior of
shared_preload_libraries, I have to use double-quotes inside single
quotes:

	ALTER SYSTEM SET listen_addresses TO 'a, "b x", c';
	.conf	listen_addresses = 'a, "b x", c'

Do we want to retain this difference in list processing?

I have developed the attached patch to document this.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Only you can decide what is important to you.

--yW6ZNzmRtM0KKyrR
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="alter_system.diff"

diff --git a/doc/src/sgml/ref/alter_system.sgml b/doc/src/sgml/ref/alter_system.sgml
index 6f8bd39eaf..14def69419 100644
--- a/doc/src/sgml/ref/alter_system.sgml
+++ b/doc/src/sgml/ref/alter_system.sgml
@@ -21,7 +21,7 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-ALTER SYSTEM SET <replaceable class="parameter">configuration_parameter</replaceable> { TO | = } { <replaceable class="parameter">value</replaceable> | '<replaceable class="parameter">value</replaceable>' | DEFAULT }
+ALTER SYSTEM SET <replaceable class="parameter">configuration_parameter</replaceable> { TO | = } { <replaceable class="parameter">value</replaceable> [, ...] | DEFAULT }
 
 ALTER SYSTEM RESET <replaceable class="parameter">configuration_parameter</replaceable>
 ALTER SYSTEM RESET ALL
@@ -83,9 +83,18 @@ ALTER SYSTEM RESET ALL
       New value of the parameter.  Values can be specified as string
       constants, identifiers, numbers, or comma-separated lists of
       these, as appropriate for the particular parameter.
+      Values with non-alphanumeric characters must be quoted.
       <literal>DEFAULT</literal> can be written to specify removing the
       parameter and its value from <filename>postgresql.auto.conf</filename>.
      </para>
+
+     <para>
+      Parameters that accept lists of strings can specify multiple values
+      separated by commas.  For some list-accepting parameters, quoted
+      values will produce double-quoted output to preserve whitespace and
+      commas; for others, double-quotes must be used inside single-quoted
+      strings to get this effect.
+     </para>
     </listitem>
    </varlistentry>
   </variablelist>

--yW6ZNzmRtM0KKyrR--