pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feed'value' has special behaviour in alter system
8+ messages / 5 participants
[nested] [flat]
* 'value' has special behaviour in alter system
@ 2022-12-14 23:07 PG Doc comments form <noreply@postgresql.org>
2022-12-15 15:50 ` Re: 'value' has special behaviour in alter system David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 8+ messages in thread
From: PG Doc comments form @ 2022-12-14 23:07 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: splarv@ya.ru
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/15/sql-altersystem.html
Description:
Documentation say
ALTER SYSTEM SET configuration_parameter { TO | = } { value | 'value' |
DEFAULT }
The variant 'value' has special, not obvious behaviour and must be
documented.
For instance
ALTER SYSTEM SET shared_preload_libraries TO a, b, c;
Lead to
shared_preload_libraries = 'a, b, c'
in the postgresql.auto.conf and working fine. (If a, b, c are correct
libraries.) But
ALTER SYSTEM SET shared_preload_libraries TO 'a, b, c';
Lead to
shared_preload_libraries = '"a, b, c"'
in the postgresql.auto.conf and postgresql will not even start. Without any
errors in the postgresql log files. :) In the system log will be "file not
found".
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: 'value' has special behaviour in alter system
2022-12-14 23:07 'value' has special behaviour in alter system PG Doc comments form <noreply@postgresql.org>
@ 2022-12-15 15:50 ` David G. Johnston <david.g.johnston@gmail.com>
2022-12-15 16:50 ` Re: 'value' has special behaviour in alter system Jonathan S. Katz <jkatz@postgresql.org>
0 siblings, 1 reply; 8+ messages in thread
From: David G. Johnston @ 2022-12-15 15:50 UTC (permalink / raw)
To: splarv@ya.ru; pgsql-docs@lists.postgresql.org
On Thu, Dec 15, 2022 at 4:45 AM PG Doc comments form <noreply@postgresql.org>
wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/15/sql-altersystem.html
> Description:
>
> Documentation say
> ALTER SYSTEM SET configuration_parameter { TO | = } { value | 'value' |
> DEFAULT }
>
> The variant 'value' has special, not obvious behaviour and must be
> documented.
>
>
This syntax representation and accompanying text annoys me too. It is
logical behavior and described accurately, but I think readability could be
improved.
I suggest changing it to:
SET configuration_parameter { TO | = } { value [, ...] | DEFAULT }
Values can be specified as unquoted alphanumeric+underscore sequences. If
the value contains any non-alphanumeric (plus underscore) characters it
should be enclosed in quotes (single or double, it does not matter). For
settings that accept multiple values, separate each value to be supplied
with a comma (and optional whitespace).
This concern is not limited to this page though, and should be applied
elsewhere as is applicable.
I haven't tried to exhaustively enumerate when quoting is required, and
probably the quoting rules should be centralized and the description
simplified to:
The rules for when individual values must be quoted is described in
Chapter 20.1.1. For settings that accept multiple values, separate each
value with a comma and optional whitespace.
That chapter does indeed already explain for each type of value when
quoting is required.
David J.
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: 'value' has special behaviour in alter system
2022-12-14 23:07 'value' has special behaviour in alter system PG Doc comments form <noreply@postgresql.org>
2022-12-15 15:50 ` Re: 'value' has special behaviour in alter system David G. Johnston <david.g.johnston@gmail.com>
@ 2022-12-15 16:50 ` Jonathan S. Katz <jkatz@postgresql.org>
2022-12-15 17:10 ` Re: 'value' has special behaviour in alter system Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 8+ messages in thread
From: Jonathan S. Katz @ 2022-12-15 16:50 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; splarv@ya.ru; pgsql-docs@lists.postgresql.org
On 12/15/22 10:50 AM, David G. Johnston wrote:
> On Thu, Dec 15, 2022 at 4:45 AM PG Doc comments form
> <noreply@postgresql.org <mailto:noreply@postgresql.org>> wrote:
>
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/15/sql-altersystem.html
> <https://www.postgresql.org/docs/15/sql-altersystem.html;
> Description:
>
> Documentation say
> ALTER SYSTEM SET configuration_parameter { TO | = } { value | 'value' |
> DEFAULT }
>
> The variant 'value' has special, not obvious behaviour and must be
> documented.
>
>
> This syntax representation and accompanying text annoys me too. It is
> logical behavior and described accurately, but I think readability could
> be improved.
>
> I suggest changing it to:
>
> SET configuration_parameter { TO | = } { value [, ...] | DEFAULT }
>
> Values can be specified as unquoted alphanumeric+underscore sequences.
> If the value contains any non-alphanumeric (plus underscore) characters
> it should be enclosed in quotes (single or double, it does not matter).
> For settings that accept multiple values, separate each value to be
> supplied with a comma (and optional whitespace).
+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.
Jonathan
Attachments:
[application/pgp-signature] OpenPGP_signature (839B, ../../f601ac59-16f9-0b75-2831-e212bae7fda5@postgresql.org/2-OpenPGP_signature)
download
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: 'value' has special behaviour in alter system
2022-12-14 23:07 'value' has special behaviour in alter system PG Doc comments form <noreply@postgresql.org>
2022-12-15 15:50 ` Re: 'value' has special behaviour in alter system David G. Johnston <david.g.johnston@gmail.com>
2022-12-15 16:50 ` Re: 'value' has special behaviour in alter system Jonathan S. Katz <jkatz@postgresql.org>
@ 2022-12-15 17:10 ` Tom Lane <tgl@sss.pgh.pa.us>
2023-10-24 17:07 ` Re: 'value' has special behaviour in alter system Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 8+ messages in thread
From: Tom Lane @ 2022-12-15 17:10 UTC (permalink / raw)
To: Jonathan S. Katz <jkatz@postgresql.org>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; splarv@ya.ru; pgsql-docs@lists.postgresql.org
"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.
regards, tom lane
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: 'value' has special behaviour in alter system
2022-12-14 23:07 'value' has special behaviour in alter system PG Doc comments form <noreply@postgresql.org>
2022-12-15 15:50 ` Re: 'value' has special behaviour in alter system David G. Johnston <david.g.johnston@gmail.com>
2022-12-15 16:50 ` Re: 'value' has special behaviour in alter system Jonathan S. Katz <jkatz@postgresql.org>
2022-12-15 17:10 ` Re: 'value' has special behaviour in alter system Tom Lane <tgl@sss.pgh.pa.us>
@ 2023-10-24 17:07 ` Bruce Momjian <bruce@momjian.us>
2023-10-24 18:05 ` Re: 'value' has special behaviour in alter system Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 8+ messages in thread
From: Bruce Momjian @ 2023-10-24 17:07 UTC (permalink / raw)
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
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.
Attachments:
[text/x-diff] alter_system.diff (1.6K, ../../ZTf50EnaCrfbyWaV@momjian.us/2-alter_system.diff)
download | inline 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>
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: 'value' has special behaviour in alter system
2022-12-14 23:07 'value' has special behaviour in alter system PG Doc comments form <noreply@postgresql.org>
2022-12-15 15:50 ` Re: 'value' has special behaviour in alter system David G. Johnston <david.g.johnston@gmail.com>
2022-12-15 16:50 ` Re: 'value' has special behaviour in alter system Jonathan S. Katz <jkatz@postgresql.org>
2022-12-15 17:10 ` Re: 'value' has special behaviour in alter system Tom Lane <tgl@sss.pgh.pa.us>
2023-10-24 17:07 ` Re: 'value' has special behaviour in alter system Bruce Momjian <bruce@momjian.us>
@ 2023-10-24 18:05 ` Tom Lane <tgl@sss.pgh.pa.us>
2023-10-24 18:36 ` Re: 'value' has special behaviour in alter system Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 8+ messages in thread
From: Tom Lane @ 2023-10-24 18:05 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Jonathan S. Katz <jkatz@postgresql.org>; David G. Johnston <david.g.johnston@gmail.com>; splarv@ya.ru; pgsql-docs@lists.postgresql.org
Bruce Momjian <bruce@momjian.us> writes:
> I have developed the attached patch to document this.
This seems a little imprecise:
+ Values with non-alphanumeric characters must be quoted.
I think accurate is more like "Values that are neither a number
nor a valid identifier must be quoted."
Also, that para already mentions that the input can be a
comma-separated list when appropriate, so your add-on para seems
partially repetitive. I think you could just drop the first
sentence of it.
regards, tom lane
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: 'value' has special behaviour in alter system
2022-12-14 23:07 'value' has special behaviour in alter system PG Doc comments form <noreply@postgresql.org>
2022-12-15 15:50 ` Re: 'value' has special behaviour in alter system David G. Johnston <david.g.johnston@gmail.com>
2022-12-15 16:50 ` Re: 'value' has special behaviour in alter system Jonathan S. Katz <jkatz@postgresql.org>
2022-12-15 17:10 ` Re: 'value' has special behaviour in alter system Tom Lane <tgl@sss.pgh.pa.us>
2023-10-24 17:07 ` Re: 'value' has special behaviour in alter system Bruce Momjian <bruce@momjian.us>
2023-10-24 18:05 ` Re: 'value' has special behaviour in alter system Tom Lane <tgl@sss.pgh.pa.us>
@ 2023-10-24 18:36 ` Bruce Momjian <bruce@momjian.us>
2023-10-31 14:21 ` Re: 'value' has special behaviour in alter system Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 8+ messages in thread
From: Bruce Momjian @ 2023-10-24 18:36 UTC (permalink / raw)
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
On Tue, Oct 24, 2023 at 02:05:53PM -0400, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > I have developed the attached patch to document this.
>
> This seems a little imprecise:
>
> + Values with non-alphanumeric characters must be quoted.
>
> I think accurate is more like "Values that are neither a number
> nor a valid identifier must be quoted."
>
> Also, that para already mentions that the input can be a
> comma-separated list when appropriate, so your add-on para seems
> partially repetitive. I think you could just drop the first
> sentence of it.
Agreed, updated patch attached.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.
Attachments:
[text/x-diff] alter_system.diff (1.5K, ../../ZTgOnpx_FQx-aF5g@momjian.us/2-alter_system.diff)
download | inline diff:
diff --git a/doc/src/sgml/ref/alter_system.sgml b/doc/src/sgml/ref/alter_system.sgml
index 6f8bd39eaf..bea5714ba1 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,17 @@ 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 that are neither numbers nor valid identifiers 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>
+ 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>
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: 'value' has special behaviour in alter system
2022-12-14 23:07 'value' has special behaviour in alter system PG Doc comments form <noreply@postgresql.org>
2022-12-15 15:50 ` Re: 'value' has special behaviour in alter system David G. Johnston <david.g.johnston@gmail.com>
2022-12-15 16:50 ` Re: 'value' has special behaviour in alter system Jonathan S. Katz <jkatz@postgresql.org>
2022-12-15 17:10 ` Re: 'value' has special behaviour in alter system Tom Lane <tgl@sss.pgh.pa.us>
2023-10-24 17:07 ` Re: 'value' has special behaviour in alter system Bruce Momjian <bruce@momjian.us>
2023-10-24 18:05 ` Re: 'value' has special behaviour in alter system Tom Lane <tgl@sss.pgh.pa.us>
2023-10-24 18:36 ` Re: 'value' has special behaviour in alter system Bruce Momjian <bruce@momjian.us>
@ 2023-10-31 14:21 ` Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 8+ messages in thread
From: Bruce Momjian @ 2023-10-31 14:21 UTC (permalink / raw)
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
On Tue, Oct 24, 2023 at 02:36:14PM -0400, Bruce Momjian wrote:
> On Tue, Oct 24, 2023 at 02:05:53PM -0400, Tom Lane wrote:
> > Bruce Momjian <bruce@momjian.us> writes:
> > > I have developed the attached patch to document this.
> >
> > This seems a little imprecise:
> >
> > + Values with non-alphanumeric characters must be quoted.
> >
> > I think accurate is more like "Values that are neither a number
> > nor a valid identifier must be quoted."
> >
> > Also, that para already mentions that the input can be a
> > comma-separated list when appropriate, so your add-on para seems
> > partially repetitive. I think you could just drop the first
> > sentence of it.
>
> Agreed, updated patch attached.
Patch applied to all supported versions.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.
^ permalink raw reply [nested|flat] 8+ messages in thread
end of thread, other threads:[~2023-10-31 14:21 UTC | newest]
Thread overview: 8+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2022-12-14 23:07 'value' has special behaviour in alter system PG Doc comments form <noreply@postgresql.org>
2022-12-15 15:50 ` David G. Johnston <david.g.johnston@gmail.com>
2022-12-15 16:50 ` Jonathan S. Katz <jkatz@postgresql.org>
2022-12-15 17:10 ` Tom Lane <tgl@sss.pgh.pa.us>
2023-10-24 17:07 ` Bruce Momjian <bruce@momjian.us>
2023-10-24 18:05 ` Tom Lane <tgl@sss.pgh.pa.us>
2023-10-24 18:36 ` Bruce Momjian <bruce@momjian.us>
2023-10-31 14:21 ` Bruce Momjian <bruce@momjian.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox