brin-autosummarize-docs.patch

diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index caf1ea4cef..5af53dee0f 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -16,9 +16,13 @@
   <acronym>BRIN</acronym> is designed for handling very large tables
   in which certain columns have some natural correlation with their
   physical location within the table.
+ </para>
+ <para>
   A <firstterm>block range</firstterm> is a group of pages that are physically
   adjacent in the table; for each block range, some summary info is stored
   by the index.
+ </para>
+ <para>
   For example, a table storing a store's sale orders might have
   a date column on which each order was placed, and most of the time
   the entries for earlier orders will appear earlier in the table as well;
@@ -31,6 +35,8 @@
   index scans, and will return all tuples in all pages within each range if
   the summary info stored by the index is <firstterm>consistent</firstterm> with the
   query conditions.
+ </para>
+ <para>
   The query executor is in charge of rechecking these tuples and discarding
   those that do not match the query conditions &mdash; in other words, these
   indexes are lossy.
@@ -69,35 +75,88 @@
    As new pages are filled with data, page ranges that are already
    summarized will cause the summary information to be updated with data
    from the new tuples.
+  </para>
+  <para>
    When a new page is created that does not fall within the last
    summarized range, that range does not automatically acquire a summary
    tuple; those tuples remain unsummarized until a summarization run is
    invoked later, creating initial summaries.
-   This process can be invoked manually using the
-   <function>brin_summarize_range(regclass, bigint)</function> or
-   <function>brin_summarize_new_values(regclass)</function> functions;
-   automatically when <command>VACUUM</command> processes the table;
-   or by automatic summarization executed by autovacuum, as insertions
-   occur.  (This last trigger is disabled by default and can be enabled
-   with the <literal>autosummarize</literal> parameter.)
-   Conversely, a range can be de-summarized using the
-   <function>brin_desummarize_range(regclass, bigint)</function> function,
-   which is useful when the index tuple is no longer a very good
-   representation because the existing values have changed.
   </para>
+  <para>
+   This summarization process can happen automatically or be invoked
+   manually. Manually it is done by calling the following
+   functions (see <xref linkend="functions-admin-index"/> for more):
+
+   <itemizedlist>
+    <listitem>
+     <simpara>
+       <function>brin_summarize_range(regclass, bigint)</function>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <function>brin_summarize_new_values(regclass)</function>
+     </simpara>
+    </listitem>
+   </itemizedlist>
+  </para>
+  <para>
+   Automatically, the process can happen under two circunstances:
+  </para>
+
+  <variablelist>
+   <varlistentry>
+   <term>VACUUM</term>
+    <listitem>
+     <para>
+      When <xref linkend="sql-vacuum"/> is run manually, it processes the table
+      and summarization is performed.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+   <term>autovacuum</term>
+    <listitem>
+     <para>
+      The <literal>autovacuum</literal> process can perform automatic
+      summarization but that is NOT the default behavior, which is controlled by
+      the <xref linkend="index-reloption-autosummarize"/> parameter, by
+      default set to <literal>off</literal>.
+     </para>
+     <para>
+      In order for the <literal>autovacuum</literal> process to execute
+      automatic summarization as insertions occur, the index must have
+      been created with (or altered to have) the
+      <xref linkend="index-reloption-autosummarize"/> parameter set to
+      <literal>on</literal>. See <xref linkend="sql-createindex"/>,
+      <xref linkend="sql-alterindex"/> and <xref linkend="autovacuum"/>
+      for details.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
 
   <para>
    When autosummarization is enabled, each time a page range is filled a
-   request is sent to autovacuum for it to execute a targeted summarization
-   for that range, to be fulfilled at the end of the next worker run on the
-   same database.  If the request queue is full, the request is not recorded
-   and a message is sent to the server log:
+   request is sent to <literal>autovacuum</literal> for it to execute a targeted
+   summarization for that range, to be fulfilled at the end of the next
+   autovacuum worker run on the same database. If the request queue is full, the
+   request is not recorded and a message is sent to the server log:
 <screen>
 LOG:  request for BRIN range summarization for index "brin_wi_idx" page 128 was not recorded
 </screen>
    When this happens, the range will be summarized normally during the next
    regular vacuum of the table.
   </para>
+
+  <para>
+   Conversely, a range can be de-summarized using the
+   <function>brin_desummarize_range(regclass, bigint)</function> function,
+   which is useful when the index tuple is no longer a very good
+   representation because the existing values have changed.
+   See <xref linkend="functions-admin-index"/> for details.
+  </para>
+
  </sect2>
 </sect1>
 
diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index 9ffcdc629e..83b5e82dfb 100644
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -579,7 +579,10 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
     <listitem>
     <para>
      Defines whether a summarization run is invoked for the previous page
-     range whenever an insertion is detected on the next one.
+     range whenever an insertion is detected on the next one. This also
+     controls whether the <literal>autovacuum</literal> process will execute
+     summarizations. The default is <literal>off</literal> (see
+     <xref linkend="brin-operation"/>).
     </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/release-15.sgml b/doc/src/sgml/release-15.sgml
index 47ac329e79..6da3f89d08 100644
--- a/doc/src/sgml/release-15.sgml
+++ b/doc/src/sgml/release-15.sgml
@@ -63,11 +63,13 @@ Author: Noah Misch <noah@leadboat.com>
       permissions on the <literal>public</literal> schema has not
       been changed.  Databases restored from previous Postgres releases
       will be restored with their current permissions.  Users wishing
-      to have the former permissions will need to grant
+      to have the old permissions on new objects will need to grant
       <literal>CREATE</literal> permission for <literal>PUBLIC</literal>
       on the <literal>public</literal> schema; this change can be made
       on <literal>template1</literal> to cause all new databases
-      to have these permissions.
+      to have these permissions.  <literal>template1</literal>
+      permissions for <application>pg_dumpall</application> and
+      <application>pg_upgrade</application>?
      </para>
     </listitem>
 
@@ -83,7 +85,7 @@ Author: Noah Misch <noah@leadboat.com>
      </para>
 
      <para>
-      Previously it was the literal user name of the bootstrap superuser.
+      Previously it was the literal user name of the database owner.
       Databases restored from previous Postgres releases will be restored
       with their current owner specification.
      </para>