Date: Sat, 6 Oct 2018 08:42:49 -0500
From: Justin Pryzby <pryzby@telsasoft.com>
To: pgsql-hackers@postgresql.org
Subject: fine tune v11 release notes
Message-ID: <20181006134249.GD871@telsasoft.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: Mutt/1.5.23 (2014-03-12)
Precedence: bulk

Find below various fixes to release notes for v11, for discussion purposes.

Note: I changed these:
 "B-tree indexes can now be built in parallel with" 
 "Allow btree indexes to be built in parallel"
..since they could be construed to mean building multiple indexes
simultaneously (perhaps like what's done by pg_restore --jobs or pg_repack).

Conversely, in create_index.sgml, change pre-existing phase "in parallel" to
"simultaneously", since "parallel" is now used to refer to parallel build of a
(single) index.

I think this needs to be rewritten, maybe in a separate commit, but I'm having
trouble writing something less impenetrable:
doc/src/sgml/ref/alter_index.sgml
     <term><literal>ATTACH PARTITION</literal></term>
     <listitem>
      <para>
       Causes the named index to become attached to the altered index.
       The named index must be on a partition of the table containing the
       index being altered, and have an equivalent definition.  An attached


Finally: should there be an entry for this?
	fb466d7b Fully enforce uniqueness of constraint names.  (Tom Lane)
	"Previously, multiple constraints could be created with same name.  A new
	unique index on pg_constraint now avoids that situation."

That was never intended to be allowed..but could still be a pg_upgrade hazard,
which would mean disruptive downtime scheduled and executed, but failure late
in pg_upgrade due to unique violation.  Maybe it'd be worth adding a check
early in pg_upgrade to detect that and exit(1) before stopping the old cluster.
I'm drawing a comparison with inconsistent nullability across inheritence
heirarchy, as discussed at [0].  That affected pg_upgrades at several of our
customers (in our case, not due to adding primary keys).  The last 25% of this
thread is what's relevant.  It looks like that check was never implemented
though.

[0] https://www.postgresql.org/message-id/flat/CACQjQLoMsE%2B1pyLe98pi0KvPG2jQQ94LWJ%2BPTiLgVRK4B%3Di_jg%40mail.gmail.com#015ff524738be6cb9a2bd6875c87094a


diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index 3c1223b..7bd1da3 100644
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -612,10 +612,10 @@ Indexes:
 
    <para>
     Regular index builds permit other regular index builds on the
-    same table to occur in parallel, but only one concurrent index build
-    can occur on a table at a time.  In both cases, no other types of schema
-    modification on the table are allowed meanwhile.  Another difference
-    is that a regular <command>CREATE INDEX</command> command can be performed within
+    same table to occur simultaneously, but only one concurrent index build
+    can occur on a table at a time.  In either case, schema modification of the
+    table is not allowed while the index is being built.  Another difference is
+    that a regular <command>CREATE INDEX</command> command can be performed within
     a transaction block, but <command>CREATE INDEX CONCURRENTLY</command> cannot.
    </para>
   </refsect2>
@@ -650,7 +650,7 @@ Indexes:
    ordering. For example, we might want to sort a complex-number data
    type either by absolute value or by real part. We could do this by
    defining two operator classes for the data type and then selecting
-   the proper class when making an index.  More information about
+   the proper class when creating an index.  More information about
    operator classes is in <xref linkend="indexes-opclass"/> and in <xref
    linkend="xindex"/>.
   </para>
@@ -673,7 +673,8 @@ Indexes:
    valid, once all partitions acquire the index.)  Note, however, that
    any partition that is created in the future using
    <command>CREATE TABLE ... PARTITION OF</command> will automatically
-   contain the index regardless of whether this option was specified.
+   contain the index regardless of whether <literal>ONLY</literal> was
+   specified.
   </para>
 
   <para>
diff --git a/doc/src/sgml/release-11.sgml b/doc/src/sgml/release-11.sgml
index ca42f28..a945502 100644
--- a/doc/src/sgml/release-11.sgml
+++ b/doc/src/sgml/release-11.sgml
@@ -32,25 +32,25 @@
        <listitem>
         <para>
          <command>UPDATE</command> statements that change a partition key
-         now move affected rows to the appropriate partitions
+         now cause affected rows to be moved to the appropriate partitions
         </para>
        </listitem>
        <listitem>
         <para>
          Improved <command>SELECT</command> performance from enhanced partition
-         elimination strategies during query processing and execution
+         elimination strategies during query planning and execution
         </para>
        </listitem>
        <listitem>
         <para>
-         Support for <literal>PRIMARY KEY</literal>, <literal>FOREIGN
-         KEY</literal>, indexes, and triggers on partitioned tables
+         Added support on partitioned tables for <literal>PRIMARY
+         KEY</literal>, <literal>FOREIGN KEY</literal>, indexes, and triggers
         </para>
        </listitem>
        <listitem>
         <para>
-         Having a "default" partition for storing data that does not match any
-         of the remaining partitions
+	 Allow creation of a "default" partition for storing rows which are
+         excluded by bounds of all other partitions.
         </para>
        </listitem>
       </itemizedlist>
@@ -63,7 +63,7 @@
       <itemizedlist>
        <listitem>
         <para>
-         B-tree indexes can now be built in parallel with
+         A B-tree index can now be built in parallel with
          <command>CREATE INDEX</command>
         </para>
        </listitem>
@@ -118,9 +118,9 @@
 
     <listitem>
      <para>
-      Many other useful performance improvements, including making
-      <command>ALTER TABLE .. ADD COLUMN</command> with a
-      non-null column default faster
+      Many other useful performance improvements, including the ability to avoid
+      a table rewrite when using <command>ALTER TABLE .. ADD COLUMN</command>
+      with a non-null column default.
      </para>
     </listitem>
 
@@ -163,7 +163,7 @@
        </para>
 
        <para>
-        Previously database attributes like
+        Previously, database attributes like
         <command>GRANT</command>/<command>REVOKE</command> permissions and
         <command>ALTER DATABASE SET</command> and <command>ALTER ROLE IN
         DATABASE SET</command> variable settings were only dumped by <link
@@ -192,7 +192,7 @@
        <para>
         A restore of <application>pg_dumpall</application> will now create
         databases with their original locale and encoding, and will fail if
-        the creation fails.  Previously <command>CREATE DATABASE</command>
+        the creation fails.  Previously, <command>CREATE DATABASE</command>
         would be dumped without such specifications if the database locale
         and encoding matched the old cluster's defaults.
        </para>
@@ -317,7 +317,7 @@
        </para>
 
        <para>
-        Previously _bytes_ were skipped.
+        Previously, <emphasis>bytes</emphasis> were skipped.
        </para>
       </listitem>
 
@@ -353,7 +353,7 @@
        <para>
         Per the SQL standard, relative paths start from the document node of
         the XML input document, not the root node as these functions
-        formerly did it.
+        previously did.
        </para>
       </listitem>
 
@@ -450,7 +450,7 @@
        </para>
 
        <para>
-        Previously index options names like ("FillFactor" = 50) were
+        Previously, index options names like ("FillFactor" = 50) were
         automatically lower-cased.  This quoted capitalization will now
         generate an error.
        </para>
@@ -519,7 +519,8 @@
 -->
 
        <para>
-        Allow faster partition elimination during query processing (Amit
+        Allow faster partition elimination during query planning (Amit
+???
         Langote, David Rowley, Dilip Kumar)
        </para>
 
@@ -539,7 +540,7 @@
        </para>
 
        <para>
-        Previously partition elimination could only happen at planning
+        Previously, partition elimination could only happen at planning
         time, meaning many joins and prepared queries could not use
         partition elimination.
        </para>
@@ -591,8 +592,7 @@
 
        <para>
         Allow <literal>UNIQUE</literal> indexes on partitioned tables if
-        the partition key guarantees uniqueness (&Aacute;lvaro Herrera,
-        Amit Langote)
+        the partition key is included in the index (&Aacute;lvaro Herrera, Amit Langote)
        </para>
       </listitem>
 
@@ -602,15 +602,18 @@
 -->
 
        <para>
-        Allow indexes on a partitioned table to be automatically created
-        in any child partitions (&Aacute;lvaro Herrera)
+        Support indexes on partitioned tables (&Aacute;lvaro Herrera)
+       </para>
+
+       <para>
+	This is not a global index, but rather a mechanism to create indexes on
+	on each partition of a partitioned table.  
        </para>
 
        <para>
         The new command <link linkend="sql-alterindex"><command>ALTER
-        INDEX ATTACH PARTITION</command></link> allows indexes to be
-        attached to partitions.  This does not behave as a global index
-        since the contents are private to each index.
+	INDEX ATTACH PARTITION</command></link> allows an index on a partition
+	to be inherited by the index on its partitioned tables.
        </para>
       </listitem>
 
@@ -653,7 +656,7 @@
 
        <para>
         Creation of a trigger on partitioned tables automatically creates
-        triggers on all partition tables, and on newly-created ones.
+        triggers on all existing and future partitions.
         This also allows deferred unique constraints on partitioned tables.
        </para>
       </listitem>
@@ -666,9 +669,8 @@
 -->
 
        <para>
-        Allow equality joins between partitioned tables with identically
-        partitioned child tables to join the child tables directly
-        (Ashutosh Bapat)
+        Allow partitioned tables to be joined directly for equality joins with
+        identically partitioned child tables.  (Ashutosh Bapat)
        </para>
 
        <para>
@@ -685,8 +687,8 @@
 -->
 
        <para>
-        Perform aggregation on each partition, and then merge the results
-        (Jeevan Chalke, Ashutosh Bapat, Robert Haas)
+        Allow first performing aggregate functions on each partition and then
+        merging the results.  (Jeevan Chalke, Ashutosh Bapat, Robert Haas)
        </para>
 
        <para>
@@ -725,7 +727,7 @@
 -->
 
        <para>
-        Allow btree indexes to be built in parallel (Peter Geoghegan,
+        Allow parallel building of a btree index (Peter Geoghegan,
         Rushabh Lathia, Heikki Linnakangas)
        </para>
       </listitem>
@@ -763,7 +765,7 @@ same commits as above
 -->
 
        <para>
-        Allow partition scans to more efficiently use parallel workers
+        Allow partition scans to use parallel workers
         (Amit Khandekar, Robert Haas, Amul Sul)
        </para>
       </listitem>
@@ -867,7 +869,7 @@ same commits as above
        <para>
         Allow indexes to <link
         linkend="sql-createindex"><literal>INCLUDE</literal></link> columns
-        that are not part of the unique constraint but are available
+        that are not part of the indexed columns but are available
         for index-only scans (Anastasia Lubennikova, Alexander Korotkov,
         Teodor Sigaev)
        </para>
@@ -886,8 +888,8 @@ same commits as above
 
        <para>
         Remember the highest btree index page to optimize future
-        monotonically increasing index additions (Pavan Deolasee, Peter
-        Geoghegan)
+        insertions of values for the case that those values are increasing
+        monotonically (Pavan Deolasee, Peter Geoghegan)
        </para>
       </listitem>
 
@@ -901,7 +903,7 @@ same commits as above
        </para>
 
        <para>
-        Previously for each hash index entry, we need to refind the scan
+        Previously, for each hash index entry, we needed to refind the scan
         position within the page.  This cuts down on lock/unlock traffic.
        </para>
       </listitem>
@@ -1004,12 +1006,12 @@ same commits as above
        </para>
 
        <para>
-        Previously most-common-values (<acronym>MCV</acronym>) were
-        chosen based on their significance compared to all column
+        Previously, the most-common-values (<acronym>MCV</acronym>) were
+        chosen based on their frequency compared to all column
         values.  Now, <acronym>MCV</acronym> are chosen based on their
         significance compared to the non-<acronym>MCV</acronym> values.
-        This improves the statistics for uniform (fewer) and non-uniform
-        (more) distributions.
+        This allows improved estimates for both uniform and non-uniform
+        distributions.
        </para>
       </listitem>
 
@@ -1024,7 +1026,7 @@ same commits as above
        </para>
 
        <para>
-        Previously such cases used the same selectivity as &gt; and
+        Previously, such cases used the same selectivity as &gt; and
         &lt;, respectively.  This change is particularly useful for
         <literal>BETWEEN</literal> with small ranges.
        </para>
@@ -1051,8 +1053,8 @@ same commits as above
 -->
 
        <para>
-        Improve row count optimizer estimates for <literal>EXISTS</literal>
-        and <literal>NOT EXISTS</literal> queries (Tom Lane)
+        Improve row count estimates for <literal>EXISTS</literal> and
+        <literal>NOT EXISTS</literal> queries (Tom Lane)
        </para>
       </listitem>
 
@@ -1095,8 +1097,7 @@ same commits as above
 
        <para>
         This feature requires <application>LLVM</application> to be
-        available, and it is not currently enabled by default, even in
-        builds that support it.
+        available, and it is currently disabled by default.
        </para>
       </listitem>
 
@@ -1172,7 +1173,7 @@ same commits as above
        </para>
 
        <para>
-        Previously only non-join <command>UPDATE</command>s and
+        Previously, only non-join <command>UPDATE</command>s and
         <command>DELETE</command>s were pushed.
        </para>
 
@@ -1351,7 +1352,7 @@ same commits as above
         <literal>pg_execute_server_program</literal>.  These roles now also
         control who can use <command>COPY</command> and extension <link
         linkend="file-fdw"><application>file_fdw</application></link>.
-        Previously only superusers could use these functions, and that
+        Previously, only superusers could use these functions, and that
         is still the default behavior.
        </para>
       </listitem>
@@ -1390,8 +1391,7 @@ same commits as above
        </para>
 
        <para>
-        Previously, superusers were exclusively granted access to these
-        functions.
+        Previously, only superusers were granted access to these functions.
        </para>
 
        <para>
@@ -1415,7 +1415,7 @@ same commits as above
        <para>
         <productname>PostgreSQL</productname> only allows superusers to
         access <application>postgres_fdw</application> tables without
-        passwords, e.g. via <literal>peer</literal>.  Previously the
+        passwords, e.g. via <literal>peer</literal>.  Previously, the
         session owner had to be a superuser to allow such access;  now
         the view owner is checked instead.
        </para>
@@ -1489,11 +1489,11 @@ same commits as above
 
        <para>
         Allow server options related to memory and file sizes to be
-        specified as number of bytes (Beena Emerson)
+        specified in units of bytes (Beena Emerson)
        </para>
 
        <para>
-        The new unit is "B".  This is in addition to "kB", "MB", "GB"
+        The new unit suffix is "B".  This is in addition to "kB", "MB", "GB"
         and "TB".
        </para>
 
@@ -1519,7 +1519,7 @@ same commits as above
        </para>
 
        <para>
-        Previously the 16MB default could only be changed at compile time.
+        Previously, the 16MB default could only be changed at compile time.
        </para>
       </listitem>
 
@@ -1529,13 +1529,12 @@ same commits as above
 -->
 
        <para>
-        No longer retain <acronym>WAL</acronym> that spans two checkpoints
+        Retain <acronym>WAL</acronym> for a single checkpoint, only.
         (Simon Riggs)
        </para>
 
        <para>
-        The retention of <acronym>WAL</acronym> records for only one
-        checkpoint is required.
+        Previously, <acronym>WAL</acronym> was retained for two checkpoints.
        </para>
       </listitem>
 
@@ -1610,7 +1609,7 @@ same commits as above
 -->
 
        <para>
-        Allow heap pages checksums to be checked during streaming base
+        Allow checksums of heap pages to be verified during streaming base
         backup (Michael Banck)
        </para>
       </listitem>
@@ -1626,7 +1625,8 @@ same commits as above
        </para>
 
        <para>
-        This allows efficient advancement replication slots when the
+        This allows efficient advancing of replication slots when the
+????
         contents do not need to be consumed.  This is performed by
         <function>pg_replication_slot_advance()</function>.
        </para>
@@ -1706,9 +1706,8 @@ same commits as above
 -->
 
        <para>
-        Allow <command>ALTER TABLE</command> to add a column with
-        a non-null default without a table rewrite (Andrew Dunstan,
-        Serge Rielau)
+        Allow <command>ALTER TABLE</command> to avoid a table rewrite when
+        adding a column with a non-null default (Andrew Dunstan, Serge Rielau)
        </para>
       </listitem>
 
@@ -1752,6 +1751,7 @@ same commits as above
        </para>
 
        <para>
+DOES THIS NEED TO BE IN "COMPATIBILITY NOTES"?
         Also, if any table mentioned in <command>VACUUM</command> uses
         a column list, then the <command>ANALYZE</command> keyword must be
         supplied; previously, <command>ANALYZE</command> was implied in
@@ -1894,7 +1894,7 @@ same commits as above
        <para>
         Allow <function>to_char()</function> and
         <function>to_timestamp()</function> to specify the time zone's
-        hours and minutes from <acronym>UTC</acronym> (Nikita Glukhov,
+        offset from <acronym>UTC</acronym> in hours and minutes (Nikita Glukhov,
         Andrew Dunstan)
        </para>
 
@@ -1970,7 +1970,7 @@ same commits as above
         PROCEDURE</command></link> command and invoked via <link
         linkend="sql-call"><command>CALL</command></link>.  The new
         <command>ALTER</command>/<command>DROP ROUTINE</command> commands
-        allows altering/dropping of procedures, functions, and aggregates.
+        allow altering/dropping of procedures, functions, and aggregates.
        </para>
       </listitem>
 
@@ -2019,7 +2019,7 @@ same commits as above
        </para>
 
        <para>
-        Previously such circumstances generated errors.
+        Previously, such circumstances generated errors.
        </para>
       </listitem>
 
@@ -2188,7 +2188,7 @@ same commits as above
        </para>
 
        <para>
-        Previously partition information would not be displayed for a
+        Previously, partition information would not be displayed for a
         partitioned table if it had no partitions.  Also indicate which
         partitions are themselves partitioned.
        </para>
@@ -2270,7 +2270,7 @@ same commits as above
        </para>
 
        <para>
-        Previously tab completion queries could fail.
+        Previously, tab completion queries could fail.
        </para>
 
       </listitem>
@@ -2789,9 +2789,9 @@ same commits as above
 -->
 
        <para>
-        Make the computation of system column
+        Make the computation of
         <structname>pg_class</structname>.<structfield>reltuples</structfield>
-        consistent (Tomas Vondra)
+        by VACUUM consistent with computation by ANALYZE (Tomas Vondra)
        </para>
       </listitem>
 
@@ -2951,7 +2951,7 @@ same commits as above
        </para>
 
        <para>
-        Previously only superusers could call adminpack functions;
+        Previously, only superusers could call adminpack functions;
         now role permissions are checked.
        </para>
       </listitem>