Re: [PATCH] Stop ALTER SYSTEM from making bad assumptions

Stephen Frost <sfrost@snowman.net> writes:
> * Tom Lane (tgl@sss.pgh.pa.us) wrote:
>> Perhaps we could put some of these details into the Notes section of the
>> ALTER SYSTEM ref page.  But I wonder how much of this is needed at all.

> I'd be alright with that too, but I'd be just as fine with even a README
> or something that we feel other hackers and external tool developers
> would be likely to find.  I agree that all of this isn't something that
> your run-of-the-mill DBA needs to know, but they are things that I'm
> sure external tool authors will care about (including myself, David S,
> probably the other backup/restore tool maintainers, and at least the
> author of pg_conftool, presumably).

In hopes of moving this along, I've pushed Ian's last code change,
as there seems to be no real argument about that anymore.

As for the doc changes, how about the attached revision of what
I wrote previously?  It gives some passing mention to what ALTER
SYSTEM will do, without belaboring it or going into things that
are really implementation details.

As an example of the sort of implementation detail that I *don't*
want to document, I invite you to experiment with the difference
between
    ALTER SYSTEM SET TimeZone = 'America/New_York';
    ALTER SYSTEM SET "TimeZone" = 'America/New_York';

            regards, tom lane

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index cdc30fa..e99482d 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -153,6 +153,8 @@ shared_buffers = 128MB
      identifiers or numbers must be single-quoted.  To embed a single
      quote in a parameter value, write either two quotes (preferred)
      or backslash-quote.
+     If the file contains multiple entries for the same parameter,
+     all but the last one are ignored.
     </para>

     <para>
@@ -185,18 +187,29 @@ shared_buffers = 128MB
      In addition to <filename>postgresql.conf</filename>,
      a <productname>PostgreSQL</productname> data directory contains a file
      <filename>postgresql.auto.conf</filename><indexterm><primary>postgresql.auto.conf</primary></indexterm>,
-     which has the same format as <filename>postgresql.conf</filename> but should
-     never be edited manually.  This file holds settings provided through
-     the <xref linkend="sql-altersystem"/> command.  This file is automatically
-     read whenever <filename>postgresql.conf</filename> is, and its settings take
-     effect in the same way.  Settings in <filename>postgresql.auto.conf</filename>
-     override those in <filename>postgresql.conf</filename>.
+     which has the same format as <filename>postgresql.conf</filename> but
+     is intended to be edited automatically not manually.  This file holds
+     settings provided through the <xref linkend="sql-altersystem"/> command.
+     This file is read whenever <filename>postgresql.conf</filename> is,
+     and its settings take effect in the same way.  Settings
+     in <filename>postgresql.auto.conf</filename> override those
+     in <filename>postgresql.conf</filename>.
+    </para>
+
+    <para>
+     External tools may also
+     modify <filename>postgresql.auto.conf</filename>.  It is not
+     recommended to do this while the server is running, since a
+     concurrent <command>ALTER SYSTEM</command> command could overwrite
+     such changes.  Such tools might simply append new settings to the end,
+     or they might choose to remove duplicate settings and/or comments
+     (as <command>ALTER SYSTEM</command> will).
     </para>

     <para>
      The system view
      <link linkend="view-pg-file-settings"><structname>pg_file_settings</structname></link>
-     can be helpful for pre-testing changes to the configuration file, or for
+     can be helpful for pre-testing changes to the configuration files, or for
      diagnosing problems if a <systemitem>SIGHUP</systemitem> signal did not have the
      desired effects.
     </para>