From 4bfb79ff6b1fd400b3dbc761921472173675a968 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Wed, 12 Jun 2019 22:48:04 -0400
Subject: [PATCH] docs: PG 12 relnotes, update btree items

Reported-by: Peter Geoghegan

Discussion: https://postgr.es/m/CAH2-Wzn-aH4ToZEWR05ELSSp7bO_JMn=sMPfUhNruwVmCXKh-w@mail.gmail.com
---
 doc/src/sgml/release-12.sgml | 77 +++++++++++++++++++++++-------------
 1 file changed, 50 insertions(+), 27 deletions(-)

diff --git a/doc/src/sgml/release-12.sgml b/doc/src/sgml/release-12.sgml
index 4a6c989f3f0..fcc49ffcf9a 100644
--- a/doc/src/sgml/release-12.sgml
+++ b/doc/src/sgml/release-12.sgml
@@ -606,22 +606,64 @@ Author: Tom Lane <tgl@sss.pgh.pa.us>
 
       <listitem>
 <!--
-Author: Alexander Korotkov <akorotkov@postgresql.org>
-2018-07-28 [d2086b08b] Reduce path length for locking leaf B-tree pages during 
+Author: Peter Geoghegan <pg@bowt.ie>
+2019-03-20 [dd299df81] Make heap TID a tiebreaker nbtree index column.
+Author: Peter Geoghegan <pg@bowt.ie>
+2019-03-20 [fab250243] Consider secondary factors during nbtree splits.
 Author: Peter Geoghegan <pg@bowt.ie>
 2019-03-25 [f21668f32] Add "split after new tuple" nbtree optimization.
 -->
 
        <para>
-        Improve speed of btree index insertions (Peter Geoghegan,
-        Alexander Korotkov)
+        Improve performance and space utilization of btree indexes with
+        many duplicates (Peter Geoghegan, Heikki Linnakangas)
        </para>
 
        <para>
-        The new code improves the space-efficiency of page splits,
-        reduces locking overhead, and gives better performance for
-        <command>UPDATE</command>s and <command>DELETE</command>s on
-        indexes with many duplicates.
+        Previously, duplicate index entries were stored unordered within
+        their duplicate groups.  This caused overhead during index
+        inserts, wasted space due to excessive page splits, and reduced
+        <command>VACUUM</command>'s ability to recycle entire pages.
+        Duplicate index entries are now sorted in heap-storage order.
+       </para>
+
+       <para>
+        Indexes <application>pg_upgraded</application> from previous
+        releases will not have these benefits.
+       </para>
+      </listitem>
+
+      <listitem>
+<!--
+see commits above
+-->
+
+       <para>
+        Allow multi-column btree indexes to be smaller (Peter Geoghegan,
+        Heikki Linnakangas)
+       </para>
+
+       <para>
+        Internal pages and min/max leaf page indicators now only store
+        index keys until the change key, rather than all indexed keys.
+        This also improves the locality of index access.
+       </para>
+
+       <para>
+        Indexes <application>pg_upgraded</application> from previous
+        releases will not have these benefits.
+       </para>
+      </listitem>
+
+      <listitem>
+<!--
+Author: Alexander Korotkov <akorotkov@postgresql.org>
+2018-07-28 [d2086b08b] Reduce path length for locking leaf B-tree pages during 
+-->
+
+       <para>
+        Improve speed of btree index insertions by reducing locking
+        overhead (Alexander Korotkov)
        </para>
       </listitem>
 
@@ -680,25 +722,6 @@ Author: Tom Lane <tgl@sss.pgh.pa.us>
 
       <listitem>
 <!--
-Author: Peter Geoghegan <pg@bowt.ie>
-2019-03-20 [dd299df81] Make heap TID a tiebreaker nbtree index column.
-Author: Peter Geoghegan <pg@bowt.ie>
-2019-03-20 [fab250243] Consider secondary factors during nbtree splits.
--->
-
-       <para>
-        Have new btree indexes sort duplicate index entries in heap-storage
-        order (Peter Geoghegan, Heikki Linnakangas)
-       </para>
-
-       <para>
-        Indexes <application>pg_upgraded</application> from previous
-        releases will not have this ordering.
-       </para>
-      </listitem>
-
-      <listitem>
-<!--
 Author: Heikki Linnakangas <heikki.linnakangas@iki.fi>
 2019-03-05 [fe280694d] Scan GiST indexes in physical order during VACUUM.
 -->