Merge remote-tracking branch 'remotes/PGSQL/master' of PG 10

This merge includes all commits upto bc2d716ad09fceeb391c755f78c256ddac9d3b9f
of PG 10.

12 files changed, 719 insertions, 467 deletions

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 28cfc6d258..747b3f05c8 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -869,8 +869,8 @@ include_dir 'conf.d'
         Specifies the number of seconds of inactivity after which TCP
         should send a keepalive message to the client.  A value of 0 uses
         the system default.
-        This parameter is supported only on systems that support the
-        <symbol>TCP_KEEPIDLE</> or <symbol>TCP_KEEPALIVE</> symbols, and on
+        This parameter is supported only on systems that support
+        <symbol>TCP_KEEPIDLE</> or an equivalent socket option, and on
         Windows; on other systems, it must be zero.
         In sessions connected via a Unix-domain socket, this parameter is
         ignored and always reads as zero.
@@ -895,9 +895,9 @@ include_dir 'conf.d'
         Specifies the number of seconds after which a TCP keepalive message
         that is not acknowledged by the client should be retransmitted.
         A value of 0 uses the system default.
-        This parameter is supported only on systems that support the
-        <symbol>TCP_KEEPINTVL</> symbol, and on Windows; on other systems, it
-        must be zero.
+        This parameter is supported only on systems that support
+        <symbol>TCP_KEEPINTVL</> or an equivalent socket option, and on
+        Windows; on other systems, it must be zero.
         In sessions connected via a Unix-domain socket, this parameter is
         ignored and always reads as zero.
        </para>
@@ -919,10 +919,11 @@ include_dir 'conf.d'
       <listitem>
        <para>
         Specifies the number of TCP keepalives that can be lost before
-        the server's connection to the client is considered dead.  A value of 0
-        uses the system default.  This parameter is
-        supported only on systems that support the <symbol>TCP_KEEPCNT</>
-        symbol; on other systems, it must be zero.
+        the server's connection to the client is considered dead.
+        A value of 0 uses the system default.
+        This parameter is supported only on systems that support
+        <symbol>TCP_KEEPCNT</> or an equivalent socket option;
+        on other systems, it must be zero.
         In sessions connected via a Unix-domain socket, this parameter is
         ignored and always reads as zero.
        </para>
@@ -3099,7 +3100,19 @@ include_dir 'conf.d'
         (as shown by a state of <literal>streaming</literal> in the
         <link linkend="monitoring-stats-views-table">
         <literal>pg_stat_replication</></link> view).
-        Specifying more than one standby names can allow very high availability.
+        Specifying more than one synchronous standby can allow for very high
+        availability and protection against data loss.
+       </para>
+       <para>
+        The name of a standby server for this purpose is the
+        <varname>application_name</> setting of the standby, as set in the
+        standby's connection information.  In case of a physical replication
+        standby, this should be set in the <varname>primary_conninfo</>
+        setting in <filename>recovery.conf</filename>; the default
+        is <literal>walreceiver</literal>.  For logical replication, this can
+        be set in the connection information of the subscription, and it
+        defaults to the subscription name.  For other replication stream
+        consumers, consult their documentation.
        </para>
        <para>
         This parameter specifies a list of standby servers using
@@ -3161,15 +3174,12 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
         as a synchronous standby.
        </para>
        <para>
-        The name of a standby server for this purpose is the
-        <varname>application_name</> setting of the standby, as set in the
-        <varname>primary_conninfo</> of the standby's WAL receiver.  There is
-        no mechanism to enforce uniqueness. In case of duplicates one of the
-        matching standbys will be considered as higher priority, though
-        exactly which one is indeterminate.
-        The special entry <literal>*</> matches any
-        <varname>application_name</>, including the default application name
-        of <literal>walreceiver</>.
+        The special entry <literal>*</> matches any standby name.
+       </para>
+       <para>
+        There is no mechanism to enforce uniqueness of standby names.  In case
+        of duplicates one of the matching standbys will be considered as
+        higher priority, though exactly which one is indeterminate.
        </para>
        <note>
         <para>
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index d0354108d1..464471a02c 100644
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -1056,6 +1056,18 @@ primary_slot_name = 'node_a_slot'
     require commit waits, including both prepare and commit.
    </para>
 
+   <para>
+    A synchronous standby can be a physical replication standby or a logical
+    replication subscriber.  It can also be any other physical or logical WAL
+    replication stream consumer that knows how to send the appropriate
+    feedback messages.  Besides the built-in physical and logical replication
+    systems, this includes special programs such
+    as <command>pg_receivewal</command> and <command>pg_recvlogical</command>
+    as well as some third-party replication systems and custom programs.
+    Check the respective documentation for details on synchronous replication
+    support.
+   </para>
+
    <sect3 id="synchronous-replication-config">
     <title>Basic Configuration</title>
 
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 62a4303a6b..5258aa998a 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -887,6 +887,43 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
     host will be tried in turn until a connection is successfully established.
    </para>
    </sect3>
+
+   <sect3 id="libpq-multiple-hosts">
+     <title>Specifying Multiple Hosts</title>
+
+     <para>
+       It is possible to specify multiple hosts to connect to, so that they are 
+       tried in the given order. In the Keyword/Value format, the <literal>host</>, 
+       <literal>hostaddr</>, and <literal>port</> options accept a comma-separated
+       list of values. The same number of elements must be given in each option, such
+       that e.g. the first <literal>hostaddr</> corresponds to the first host name,
+       the second <literal>hostaddr</> corresponds to the second host name, and so
+       forth. As an exception, if only one <literal>port</literal> is specified, it
+       applies to all the hosts.
+     </para>
+
+     <para>
+       In the connection URI format, you can list multiple <literal>host:port</> pairs 
+       separated by commas, in the <literal>host</> component of the URI. In either
+       format, a single hostname can also translate to multiple network addresses. A
+       common example of this is a host that has both an IPv4 and an IPv6 address.
+     </para>
+
+     <para>
+       When multiple hosts are specified, or when a single hostname is 
+       translated to multiple addresses,  all the hosts and addresses will be 
+       tried in order, until one succeeds. If none of the hosts can be reached, 
+       the connection fails. If a connection is established successfully, but 
+       authentication fails, the remaining hosts in the list are not tried.
+     </para>
+
+     <para>
+       If a password file is used, you can have different passwords for 
+       different hosts. All the other connection options are the same for every 
+       host, it is not possible to e.g. specify a different username for 
+       different hosts.
+     </para>
+   </sect3>
   </sect2>
 
   <sect2 id="libpq-paramkeywords">
@@ -900,7 +937,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
       <term><literal>host</literal></term>
       <listitem>
        <para>
-        Comma-separated list of host names.<indexterm><primary>host name</></>
+        Name of host to connect to.<indexterm><primary>host name</></>
         If a host name begins with a slash, it specifies Unix-domain
         communication rather than TCP/IP communication; the value is the
         name of the directory in which the socket file is stored.  If
@@ -912,6 +949,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
         when <productname>PostgreSQL</> was built). On machines without
         Unix-domain sockets, the default is to connect to <literal>localhost</>.
        </para>
+       <para>
+        A comma-separated list of host names is also accepted, in which case
+        each host name in the list is tried in order. See
+        <xref linkend="libpq-multiple-hosts"> for details.
+       </para>
       </listitem>
      </varlistentry>
 
@@ -966,6 +1008,11 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
        </para>
 
        <para>
+        A comma-separated list of <literal>hostaddrs</> is also accepted, in
+        which case each host in the list is tried in order. See
+        <xref linkend="libpq-multiple-hosts"> for details.
+       </para>
+       <para>
         Without either a host name or host address,
         <application>libpq</application> will connect using a
         local Unix-domain socket; or on machines without Unix-domain
@@ -981,9 +1028,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
         Port number to connect to at the server host, or socket file
         name extension for Unix-domain
         connections.<indexterm><primary>port</></>
-        If the <literal>host</> parameter included multiple, comma-separated
-        hosts, this parameter may specify a list of ports of equal length,
-        or it may specify a single port number to be used for all hosts.
+        If multiple hosts were given in the <literal>host</literal> or
+        <literal>hostaddr</> parameters, this parameter may specify a list
+        of ports of equal length, or it may specify a single port number to
+        be used for all hosts.
        </para>
       </listitem>
      </varlistentry>
@@ -1125,10 +1173,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
         Controls the number of seconds of inactivity after which TCP should
         send a keepalive message to the server.  A value of zero uses the
         system default. This parameter is ignored for connections made via a
-        Unix-domain socket, or if keepalives are disabled. It is only supported
-        on systems where the <symbol>TCP_KEEPIDLE</> or <symbol>TCP_KEEPALIVE</>
-        socket option is available, and on Windows; on other systems, it has no
-        effect.
+        Unix-domain socket, or if keepalives are disabled.
+        It is only supported on systems where <symbol>TCP_KEEPIDLE</> or
+        an equivalent socket option is available, and on Windows; on other
+        systems, it has no effect.
        </para>
       </listitem>
      </varlistentry>
@@ -1141,9 +1189,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
         that is not acknowledged by the server should be retransmitted.  A
         value of zero uses the system default. This parameter is ignored for
         connections made via a Unix-domain socket, or if keepalives are disabled.
-        It is only supported on systems where the <symbol>TCP_KEEPINTVL</>
-        socket option is available, and on Windows; on other systems, it has no
-        effect.
+        It is only supported on systems where <symbol>TCP_KEEPINTVL</> or
+        an equivalent socket option is available, and on Windows; on other
+        systems, it has no effect.
        </para>
       </listitem>
      </varlistentry>
@@ -1156,8 +1204,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
         client's connection to the server is considered dead.  A value of
         zero uses the system default. This parameter is ignored for
         connections made via a Unix-domain socket, or if keepalives are disabled.
-        It is only supported on systems where the <symbol>TCP_KEEPCNT</>
-        socket option is available; on other systems, it has no effect.
+        It is only supported on systems where <symbol>TCP_KEEPCNT</> or
+        an equivalent socket option is available; on other systems, it has no
+        effect.
        </para>
       </listitem>
      </varlistentry>
@@ -1983,8 +2032,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);
           <listitem>
            <para>
              SSL/TLS version in use. Common values
-             are <literal>"SSLv2"</literal>, <literal>"SSLv3"</literal>,
-             <literal>"TLSv1"</literal>, <literal>"TLSv1.1"</literal>
+             are <literal>"TLSv1"</literal>, <literal>"TLSv1.1"</literal>
              and <literal>"TLSv1.2"</literal>, but an implementation may
              return other strings if some other protocol is used.
            </para>
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index fa8ae536d9..fa0bb56b7b 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -185,6 +185,14 @@
   </para>
 
   <para>
+   A logical replication subscription can be a standby for synchronous
+   replication (see <xref linkend="synchronous-replication">).  The standby
+   name is by default the subscription name.  An alternative name can be
+   specified as <literal>application_name</literal> in the connection
+   information of the subscription.
+  </para>
+
+  <para>
    Subscriptions are dumped by <command>pg_dump</command> if the current user
    is a superuser.  Otherwise a warning is written and subscriptions are
    skipped, because non-superusers cannot read all subscription information
@@ -421,6 +429,13 @@
    and constraints.
   </para>
 
+  <para>
+   The logical replication apply process currently only fires row triggers,
+   not statement triggers.  The initial table synchronization, however, is
+   implemented like a <command>COPY</command> command and thus fires both row
+   and statement triggers for <command>INSERT</command>.
+  </para>
+
   <sect2 id="logical-replication-snapshot">
     <title>Initial Snapshot</title>
     <para>
diff --git a/doc/src/sgml/ref/create_trigger.sgml b/doc/src/sgml/ref/create_trigger.sgml
index d73eec82cf..db1a97000d 100644
--- a/doc/src/sgml/ref/create_trigger.sgml
+++ b/doc/src/sgml/ref/create_trigger.sgml
@@ -464,6 +464,20 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</
   </para>
 
   <para>
+    Modifying a partitioned table or a table with inheritance children fires
+    statement-level triggers directly attached to that table, but not
+    statement-level triggers for its partitions or child tables.  In contrast,
+    row-level triggers are fired for all affected partitions or child tables.
+    If a statement-level trigger has been defined with transition relations
+    named by a <literal>REFERENCING</literal> clause, then before and after
+    images of rows are visible from all affected partitions or child tables.
+    In the case of inheritance children, the row images include only columns
+    that are present in the table that the trigger is attached to.  Currently,
+    row-level triggers with transition relations cannot be defined on
+    partitions or inheritance child tables.
+  </para>
+
+  <para>
    In <productname>PostgreSQL</productname> versions before 7.3, it was
    necessary to declare trigger functions as returning the placeholder
    type <type>opaque</>, rather than <type>trigger</>.  To support loading
diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml
index a6f27ec54d..ca8650ce75 100644
--- a/doc/src/sgml/ref/pg_ctl-ref.sgml
+++ b/doc/src/sgml/ref/pg_ctl-ref.sgml
@@ -430,6 +430,13 @@ PostgreSQL documentation
         <command>pg_ctl</command> returns an exit code based on the
         success of the startup or shutdown.
        </para>
+
+       <para>
+        If the operation does not complete within the timeout (see
+        option <option>-t</option>), then <command>pg_ctl</command> exits with
+        a nonzero exit status.  But note that the operation might continue in
+        the background and eventually succeed.
+       </para>
       </listitem>
      </varlistentry>
 
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 9faa365481..c592edac60 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -68,7 +68,8 @@ PostgreSQL documentation
       <listitem>
       <para>
       Switches to unaligned output mode. (The default output mode is
-      otherwise aligned.)
+      otherwise aligned.)  This is equivalent to <command>\pset format
+      unaligned</command>.
       </para>
       </listitem>
     </varlistentry>
@@ -371,8 +372,8 @@ EOF
       <listitem>
       <para>
       Use <replaceable class="parameter">separator</replaceable> as the
-      record separator for unaligned output. This is equivalent to the
-      <command>\pset recordsep</command> command.
+      record separator for unaligned output. This is equivalent to
+      <command>\pset recordsep</command>.
       </para>
       </listitem>
     </varlistentry>
@@ -415,7 +416,8 @@ EOF
       <listitem>
       <para>
       Turn off printing of column names and result row count footers,
-      etc. This is equivalent to the <command>\t</command> command.
+      etc. This is equivalent to <command>\t</command> or
+      <command>\pset tuples_only</command>.
       </para>
       </listitem>
     </varlistentry>
@@ -427,7 +429,7 @@ EOF
       <para>
       Specifies options to be placed within the
       <acronym>HTML</acronym> <sgmltag>table</sgmltag> tag. See
-      <command>\pset</command> for details.
+      <command>\pset tableattr</command> for details.
       </para>
       </listitem>
     </varlistentry>
@@ -522,8 +524,8 @@ EOF
       <term><option>--expanded</></term>
       <listitem>
       <para>
-      Turn on the expanded table formatting mode. This is equivalent to the
-      <command>\x</command> command.
+      Turn on the expanded table formatting mode. This is equivalent to
+      <command>\x</command> or <command>\pset expanded</command>.
       </para>
       </listitem>
     </varlistentry>
@@ -545,7 +547,8 @@ EOF
       <term><option>--field-separator-zero</option></term>
       <listitem>
       <para>
-      Set the field separator for unaligned output to a zero byte.
+      Set the field separator for unaligned output to a zero byte.  This is
+      equvalent to <command>\pset fieldsep_zero</command>.
       </para>
       </listitem>
     </varlistentry>
@@ -557,6 +560,7 @@ EOF
       <para>
       Set the record separator for unaligned output to a zero byte.  This is
       useful for interfacing, for example, with <literal>xargs -0</literal>.
+      This is equivalent to <command>\pset recordsep_zero</command>.
       </para>
       </listitem>
     </varlistentry>
@@ -1907,9 +1911,8 @@ Tue Oct 26 21:40:57 CEST 1999
         <listitem>
         <para>
         Sets the field separator for unaligned query output. The default
-        is the vertical bar (<literal>|</literal>). See also
-        <command>\pset</command> for a generic way of setting output
-        options.
+        is the vertical bar (<literal>|</literal>). It is equivalent to
+        <command>\pset fieldsep</command>.
         </para>
         </listitem>
       </varlistentry>
@@ -2810,8 +2813,9 @@ lo_import 152801
         <tip>
         <para>
         There are various shortcut commands for <command>\pset</command>. See
-        <command>\a</command>, <command>\C</command>, <command>\H</command>,
-        <command>\t</command>, <command>\T</command>, and <command>\x</command>.
+        <command>\a</command>, <command>\C</command>, <command>\f</command>,
+        <command>\H</command>, <command>\t</command>, <command>\T</command>,
+        and <command>\x</command>.
         </para>
         </tip>
 
diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml
index c89f96a01a..ecc80b67eb 100644
--- a/doc/src/sgml/regress.sgml
+++ b/doc/src/sgml/regress.sgml
@@ -214,7 +214,7 @@ make installcheck-world
   </para>
 
   <para>
-   The TAP tests are only run when PostgreSQL was configured with the
+   The TAP-based tests are run only when PostgreSQL was configured with the
    option <option>--enable-tap-tests</option>.  This is recommended for
    development, but can be omitted if there is no suitable Perl installation.
   </para>
@@ -671,20 +671,19 @@ float8:out:i.86-.*-openbsd=float8-small-is-zero.out
    <title>TAP Tests</title>
 
    <para>
-    The client program tests under <filename>src/bin</filename> use the Perl
-    TAP tools and are run by <command>prove</command>.  You can pass
+    Various tests, particularly the client program tests
+    under <filename>src/bin</filename>, use the Perl TAP tools and are run
+    using the Perl testing program <command>prove</command>.  You can pass
     command-line options to <command>prove</command> by setting
     the <command>make</command> variable <varname>PROVE_FLAGS</>, for example:
 <programlisting>
-make -C src/bin check PROVE_FLAGS='--reverse'
+make -C src/bin check PROVE_FLAGS='--timer'
 </programlisting>
-    The default is <literal>--verbose</literal>.  See the manual page
-    of <command>prove</command> for more information.
+    See the manual page of <command>prove</command> for more information.
    </para>
 
    <para>
-    The tests written in Perl require the Perl
-    module <literal>IPC::Run</literal>.
+    The TAP tests require the Perl module <literal>IPC::Run</literal>.
     This module is available from CPAN or an operating system package.
    </para>
   </sect1>
diff --git a/doc/src/sgml/release-10.sgml b/doc/src/sgml/release-10.sgml
index 8b1b66d874..debaa80099 100644
--- a/doc/src/sgml/release-10.sgml
+++ b/doc/src/sgml/release-10.sgml
@@ -6,7 +6,7 @@
 
   <formalpara>
    <title>Release date:</title>
-   <para>2017-09-XX (CURRENT AS OF 2017-05-14)</para>
+   <para>2017-??-?? (current as of 2017-07-09, commit 3381898f9)</para>
   </formalpara>
 
   <sect2>
@@ -20,7 +20,7 @@
 
    <itemizedlist>
 
-   <listitem><para> </para></listitem>
+   <listitem><para>(to be written)</para></listitem>
    </itemizedlist>
 
    <para>
@@ -49,40 +49,38 @@
     <listitem>
 <!--
 2017-04-03 [ea69a0dea] Expand hash indexes more gradually.
+2017-05-19 [a95410e2e] pg_upgrade: Handle hash index upgrades more smoothly.
 -->
      <para>
-      <application>pg_upgrade</>-ed hash indexes from previous major
-      PostgreSQL versions must be rebuilt.
+      Hash indexes must be rebuilt after <application>pg_upgrade</>-ing
+      from any previous major <productname>PostgreSQL</> version (Mithun
+      Cy, Robert Haas)
      </para>
 
      <para>
-      Major hash storage improvements necessitated this requirement.
-     </para>
-    </listitem>
-
-    <listitem>
-<!--
-2017-03-27 [3371e4d9b] Change default of log_directory to 'log'
--->
-     <para>
-      Change the default <link linkend="guc-log-destination">log
-      directory</> from <filename>pg_log</> to <filename>log</> (Andreas
-      Karlsson)
+      Major hash index improvements necessitated this requirement.
+      <application>pg_upgrade</> will create a script to assist with this.
      </para>
     </listitem>
 
     <listitem>
 <!--
 2016-10-20 [f82ec32ac] Rename "pg_xlog" directory to "pg_wal"
+2017-03-17 [88e66d193] Rename "pg_clog" directory to "pg_xact".
 -->
      <para>
-      Rename <filename>pg_xlog</> to <link
-      linkend="wal"><filename>pg_wal</></> (Michael Paquier)
+      Rename write-ahead log directory <filename>pg_xlog</>
+      to <link linkend="wal"><filename>pg_wal</></>, and rename transaction
+      status directory <filename>pg_clog</> to <filename>pg_xact</>
+      (Michael Paquier)
      </para>
 
      <para>
-      This prevents the write-ahead log directory from being confused as
-      containing server activity logs, and erroneously truncated.
+      Users have occasionally thought that these directories contained only
+      inessential log files, and proceeded to remove write-ahead log files
+      or transaction status files manually, causing irrecoverable data
+      loss.  These name changes are intended to discourage such errors in
+      future.
      </para>
     </listitem>
 
@@ -102,18 +100,10 @@
       For example, <function>pg_switch_xlog()</> becomes
       <function>pg_switch_wal()</>, <application>pg_receivexlog</>
       becomes <application>pg_receivewal</>, and <option>--xlogdir</>
-      becomes <option>--waldir</>.  This might require adjustments for
-      prior-version scripts.
-     </para>
-    </listitem>
-
-    <listitem>
-<!--
-2017-03-17 [88e66d193] Rename "pg_clog" directory to "pg_xact".
--->
-     <para>
-      Rename transaction status directory <filename>pg_clog</> directory
-      to <filename>pg_xact</> (Michael Paquier)
+      becomes <option>--waldir</>.  This is for consistency with the
+      change of the <filename>pg_xlog</> directory name; in general,
+      the <quote>xlog</> terminology is no longer used in any user-facing
+      places.
      </para>
     </listitem>
 
@@ -125,6 +115,10 @@
       Rename <acronym>WAL</>-related functions and views to use <literal>lsn</>
       instead of <literal>location</> (David Rowley)
      </para>
+
+     <para>
+      There was previously an inconsistent mixture of the two terminologies.
+     </para>
     </listitem>
 
     <listitem>
@@ -160,17 +154,17 @@
 2017-01-04 [9a4d51077] Make wal streaming the default mode for pg_basebackup
 -->
      <para>
-      Have <application><xref linkend="app-pgbasebackup"></> stream the
+      Make <application><xref linkend="app-pgbasebackup"></> stream the
       <acronym>WAL</> needed to restore the backup by default (Magnus
       Hagander)
      </para>
 
      <para>
-      This changes the <application>pg_basebackup</>
+      This changes <application>pg_basebackup</>'s
       <option>-X</>/<option>--xlog-method</> default to <literal>stream</>.
-      An option value <literal>none</> has been added to recreate the old
+      An option value <literal>none</> has been added to reproduce the old
       behavior.  The <application>pg_basebackup</> option <option>-x</>
-      has been removed (use <option>-X</> fetch).
+      has been removed (instead, use <literal>-X fetch</>).
      </para>
     </listitem>
 
@@ -180,7 +174,8 @@
 -->
      <para>
       Change how logical replication
-      uses <link linkend="auth-pg-hba-conf"><filename>pg_hba.conf</filename></link>.
+      uses <link linkend="auth-pg-hba-conf"><filename>pg_hba.conf</filename></link>
+      (Peter Eisentraut)
      </para>
 
      <para>
@@ -189,7 +184,7 @@
       of this release, logical replication matches a normal entry with a
       database name or keywords such as <literal>all</literal>.  Physical
       replication continues to use the <literal>replication</literal> keyword.
-      Since built-in logical replication is new in this release as well, this
+      Since built-in logical replication is new in this release, this
       change only affects users of third-party logical replication plugins.
      </para>
     </listitem>
@@ -200,7 +195,7 @@
 -->
     <para>
      Make all <application><xref linkend="app-pg-ctl"></> actions wait
-     by default for completion (Peter Eisentraut)
+     for completion by default (Peter Eisentraut)
     </para>
 
     <para>
@@ -219,14 +214,15 @@
     </para>
 
     <para>
-     The server-side variable <xref linkend="guc-password-encryption">
+     The <xref linkend="guc-password-encryption"> server parameter
      no longer supports <literal>off</> or <literal>plain</>.
-     The <literal>UNENCRYPTED</> option is no longer supported for
+     The <literal>UNENCRYPTED</> option is no longer supported in
      <command>CREATE/ALTER USER ... PASSSWORD</>.  Similarly, the
-     <option>--unencrypted</> has been removed from <command>createuser</>.
-     The default for <option>password_encryption</> is still
-     <literal>md5</>, and users migrating passwords from older systems
-     will have them stored encrypted by default in this release.
+     <option>--unencrypted</> option has been removed
+     from <application>createuser</>.  Unencrypted passwords migrated from
+     older versions will be stored encrypted in this release.  The default
+     setting for <varname>password_encryption</> is still
+     <literal>md5</>.
     </para>
     </listitem>
 
@@ -242,13 +238,13 @@
     </para>
 
     <para>
-     This makes a backwards-incompatible change to the handling of
-     composite types in arrays. Previously, you could return an array of
-     composite types as "[[col1, col2], [col1, col2]]", but now that is
-     interpreted as a two- dimensional array. Composite types in arrays
-     must now be returned as Python tuples, not lists, to resolve the
-     ambiguity. I.e. "[(col1, col2), (col1, col2)]".  See the documentation
-     for more details. CLARIFY
+     This feature requires a backwards-incompatible change to the handling
+     of arrays of composite types in PL/Python.  Previously, you could
+     return an array of composite values by writing, e.g., <literal>[[col1,
+     col2], [col1, col2]]</>; but now that is interpreted as a
+     two-dimensional array.  Composite types in arrays must now be written
+     as Python tuples, not lists, to resolve the ambiguity; that is,
+     write <literal>[(col1, col2), (col1, col2)]</> instead.
     </para>
     </listitem>
 
@@ -257,27 +253,41 @@
 2017-02-27 [817f2a586] Remove PL/Tcl's "module" facility.
 -->
     <para>
-     Remove PL/Tcl's "module" auto-loading facility (Tom Lane)
+     Remove PL/Tcl's <quote>module</> auto-loading facility (Tom Lane)
     </para>
 
     <para>
-     Replaced by new PL/Tcl startup <acronym>GUC</>s.
+     This functionality has been replaced by new server
+     parameters <xref linkend="guc-pltcl-start-proc">
+     and <xref linkend="guc-pltclu-start-proc">, which are easier to use
+     and more similar to features available in other PLs.
     </para>
     </listitem>
 
     <listitem>
 <!--
+2017-03-27 [3371e4d9b] Change default of log_directory to 'log'
+-->
+     <para>
+      Change the default value of the <xref linkend="guc-log-destination">
+      server parameter from <filename>pg_log</> to <filename>log</>
+      (Andreas Karlsson)
+     </para>
+    </listitem>
+
+    <listitem>
+<!--
 2016-12-23 [e13486eba] Remove sql_inheritance GUC.
 -->
     <para>
-     Remove <varname>sql_inheritance</> <acronym>GUC</> (Robert Haas)
+     Remove <varname>sql_inheritance</> server parameter (Robert Haas)
     </para>
 
     <para>
-     Changing this from the default value caused queries referencing
-     parent tables to not include children tables.  The <acronym>SQL</>
+     Changing this setting from the default value caused queries referencing
+     parent tables to not include child tables.  The <acronym>SQL</>
      standard requires such behavior and this has been the default since
-     PostgreSQL 7.1.
+     <productname>PostgreSQL</> 7.1.
     </para>
     </listitem>
 
@@ -286,14 +296,31 @@
 2017-02-15 [51ee6f316] Replace min_parallel_relation_size with two new GUCs.
 -->
     <para>
-     Add <acronym>GUC</>s <xref linkend="guc-min-parallel-table-scan-size">
-     and <xref linkend="guc-min-parallel-index-scan-size"> to control
-     parallel operation (Amit Kapila, Robert Haas)
+     Add <xref linkend="guc-min-parallel-table-scan-size">
+     and <xref linkend="guc-min-parallel-index-scan-size"> server
+     parameters to control parallel queries (Amit Kapila, Robert Haas)
     </para>
 
     <para>
-     This replaces <varname>min_parallel_relation_size</>, which was
-     too generic.
+     These replace <varname>min_parallel_relation_size</>, which was
+     found to be too generic.
+    </para>
+    </listitem>
+
+    <listitem>
+<!--
+2017-06-20 [a69dfe5f4] Don't downcase entries within shared_preload_libraries e
+-->
+    <para>
+     Don't downcase unquoted text
+     within <xref linkend="guc-shared-preload-libraries"> and related
+     server parameters (QL Zhuo)
+    </para>
+
+    <para>
+     These settings are really lists of file names, but they were
+     previously treated as lists of SQL identifiers, which have different
+     parsing rules.
     </para>
     </listitem>
 
@@ -307,8 +334,9 @@
     </para>
 
      <para>
-      Users needing dump support for pre-8.0 servers need to use dump
-      binaries from PostgreSQL 9.6.
+      Users needing to dump from pre-8.0 servers will need to use dump
+      programs from <productname>PostgreSQL</> 9.6 or earlier.  The
+      resulting output should still load successfully into newer servers.
      </para>
     </listitem>
 
@@ -317,13 +345,13 @@
 2017-02-23 [b6aa17e0a] De-support floating-point timestamps.
 -->
      <para>
-      Remove support for floating-point datetimes/timestamps (Tom Lane)
+      Remove support for floating-point timestamps and intervals (Tom Lane)
      </para>
 
      <para>
       This removes configure's <option>--disable-integer-datetimes</>
-      option.  Floating-point datetimes/timestamps have not been the
-      default since PostgreSQL 8.3 and have few advantages.
+      option.  Floating-point timestamps have not been the
+      default since <productname>PostgreSQL</> 8.3 and have few advantages.
      </para>
     </listitem>
 
@@ -336,7 +364,8 @@
      </para>
 
      <para>
-      This protocol hasn't had client support since PostgreSQL 6.3.
+      This protocol hasn't had client support
+      since <productname>PostgreSQL</> 6.3.
      </para>
     </listitem>
 
@@ -345,12 +374,12 @@
 2017-02-13 [7ada2d31f] Remove contrib/tsearch2.
 -->
      <para>
-      Remove contrib/tsearch2 (Robert Haas)
+      Remove <filename>contrib/tsearch2</> module (Robert Haas)
      </para>
 
      <para>
-      This removes compatibility with the contrib version of full text
-      search that shipped in pre-8.3 PostgreSQL versions.
+      This module provided compatibility with the version of full text
+      search that shipped in pre-8.3 <productname>PostgreSQL</> releases.
     </para>
     </listitem>
 
@@ -359,8 +388,14 @@
 2017-03-23 [50c956add] Remove createlang and droplang
 -->
      <para>
-      Remove createlang and droplang command-line applications (Peter
-      Eisentraut)
+      Remove <application>createlang</> and <application>droplang</>
+      command-line applications (Peter Eisentraut)
+     </para>
+
+     <para>
+      These were deprecated since <productname>PostgreSQL</> 9.1.  Instead,
+      use <command>CREATE EXTENSION</> and <command>DROP EXTENSION</>
+      directly.
      </para>
     </listitem>
 
@@ -372,15 +407,10 @@
       Remove support for version-0 function calling conventions (Andres
       Freund)
      </para>
-    </listitem>
 
-    <listitem>
-<!--
-2016-10-11 [2b860f52e] Remove "sco" and "unixware" ports.
--->
      <para>
-      Remove <systemitem class="osname">SCO</> and <systemitem
-      class="osname">Unixware</> ports (Tom Lane)
+      Extensions providing C-coded functions must now conform to version 1
+      calling conventions.  Version 0 has been deprecated since 2001.
      </para>
     </listitem>
 
@@ -393,7 +423,7 @@
 
    <para>
     Below you will find a detailed account of the changes between
-   <productname>PostgreSQL</productname> 10 and the previous major
+    <productname>PostgreSQL</productname> 10 and the previous major
     release.
    </para>
 
@@ -417,8 +447,8 @@
        </para>
 
        <para>
-        Allows B-tree index pages to be checked by separate parallel
-        workers.
+        This change allows B-tree index pages to be searched by separate
+        parallel workers.
        </para>
       </listitem>
 
@@ -481,13 +511,13 @@
 2016-12-05 [2b959d495] Reduce the default for max_worker_processes back to 8.
 -->
        <para>
-        Add <acronym>GUC</> <xref linkend="guc-max-parallel-workers">
+        Add <xref linkend="guc-max-parallel-workers"> server parameter
         to limit the number of worker processes that can be used for
         query parallelism (Julien Rouhaud)
        </para>
 
        <para>
-        This can be set lower than <xref
+        This parameter can be set lower than <xref
         linkend="guc-max-worker-processes"> to reserve worker processes
         for purposes other than parallel queries.
        </para>
@@ -537,7 +567,7 @@
 
        <para>
         Specifically, a new <link linkend="SQL-CREATEINDEX"><command>CREATE
-        INDEX</></> option allows auto-summarizion of the
+        INDEX</></> option allows auto-summarization of the
         previous <acronym>BRIN</> page range when a new page
         range is created.
        </para>
@@ -554,7 +584,7 @@
        </para>
 
        <para>
-        New <acronym>SQL</> function <link
+        The new <acronym>SQL</> function <link
         linkend="functions-admin-index-table"><function>brin_summarize_range()</></>
         updates <acronym>BRIN</> index summarization for a specified
         range and <function>brin_desummarize_range()</> removes it.
@@ -601,8 +631,8 @@
         </para>
 
         <para>
-         This makes hash indexes crash-safe and replicated, and removes
-         the warning message about their use.
+         This makes hash indexes crash-safe and replicatable.
+         The former warning message about their use is removed.
         </para>
        </listitem>
 
@@ -612,7 +642,7 @@
 2017-02-07 [293e24e50] Cache hash index's metapage in rel->rd_amcache.
 -->
         <para>
-         Improve hash bucket split performance by reducing locking
+         Improve hash index bucket split performance by reducing locking
          requirements (Amit Kapila, Mithun Cy)
         </para>
 
@@ -635,7 +665,7 @@
 2017-03-15 [6977b8b7f] Port single-page btree vacuum logic to hash indexes.
 -->
         <para>
-         Allow single-page hash pruning (Ashutosh Sharma)
+         Allow page-at-a-time hash index pruning (Ashutosh Sharma)
         </para>
        </listitem>
 
@@ -653,33 +683,35 @@
 
       <listitem>
 <!--
-2017-03-31 [64d4da511] For foreign keys, check REFERENCES privilege only on the
+2016-09-05 [15bc038f9] Relax transactional restrictions on ALTER TYPE ... ADD V
 -->
        <para>
-        Only check for <literal>REFERENCES</> permission on referenced
-        tables (Tom Lane)
+        Reduce locking required for adding values to enum types (Andrew
+        Dunstan, Tom Lane)
        </para>
 
        <para>
-        Previously <literal>REFERENCES</> permission on the referencing
-        table was also required.
+        Previously it was impossible to run <command>ALTER TYPE ... ADD
+        VALUE</> in a transaction block unless the enum type was created
+        in the same block.  Now, only references to uncommitted enum
+        values from other transactions are prohibited.
        </para>
       </listitem>
 
       <listitem>
 <!--
-2016-09-05 [15bc038f9] Relax transactional restrictions on ALTER TYPE ... ADD V
+2017-03-06 [21d4e2e20] Reduce lock levels for table storage params related to p
+2017-04-05 [68ea2b7f9] Reduce lock level for CREATE STATISTICS
 -->
        <para>
-        Reduce locking required for adding values to enum types (Andrew
-        Dunstan, Tom Lane)
+        Reduce locking required to change table parameters (Simon Riggs,
+        Fabr&iacute;zio Mello)
        </para>
 
        <para>
-        Previously it was impossible to run <command>ALTER TYPE ... ADD
-        VALUE</> in a transaction block unless the enum type was created
-        in the same block.  Now, only references to uncommitted enum
-        values from other transactions is prohibited.
+        For example, changing a table's <xref
+        linkend="guc-effective-io-concurrency"> setting can now be done
+        with a more lightweight lock.
        </para>
       </listitem>
 
@@ -693,7 +725,8 @@
        </para>
 
        <para>
-        The new settings are <xref
+        Lock promotion can now be controlled through two new server
+        parameters, <xref
         linkend="guc-max-pred-locks-per-relation"> and
         <xref linkend="guc-max-pred-locks-per-page">.
        </para>
@@ -712,6 +745,7 @@
 <!--
 2017-03-24 [7b504eb28] Implement multivariate n-distinct coefficients
 2017-04-05 [2686ee1b7] Collect and use multi-column dependency stats
+2017-05-12 [bc085205c] Change CREATE STATISTICS syntax
 -->
       <para>
        Add multi-column optimizer statistics to compute the correlation
@@ -720,22 +754,12 @@
       </para>
 
       <para>
-       New commands are <command><link
-       linkend="SQL-CREATESTATISTICS">CREATE</></>,
-      <command><link linkend="SQL-ALTERSTATISTICS">ALTER</></>, and
-      <command><link linkend="SQL-DROPSTATISTICS">DROP STATISTICS</></>.
-      This is helpful in
-       estimating query memory usage and when combining the statistics
-       from individual columns.
-      </para>
-      </listitem>
-
-      <listitem>
-<!--
-2017-01-15 [0777f7a2e] Fix matching of boolean index columns to sort ordering.
--->
-      <para>
-       Improve planner matching of <type>boolean</type> indexes (Tom Lane)
+       New commands are <link
+       linkend="SQL-CREATESTATISTICS"><command>CREATE STATISTICS</></>,
+       <link linkend="SQL-ALTERSTATISTICS"><command>ALTER STATISTICS</></>, and
+       <link linkend="SQL-DROPSTATISTICS"><command>DROP STATISTICS</></>.
+       This feature is helpful in estimating query memory usage and when
+       combining the statistics from individual columns.
       </para>
       </listitem>
 
@@ -744,13 +768,14 @@
 2017-01-18 [215b43cdc] Improve RLS planning by marking individual quals with se
 -->
       <para>
-       Improve performance of queries referencing row-level security
+       Improve performance of queries affected by row-level security
        restrictions (Tom Lane)
       </para>
 
       <para>
-       The optimizer now has more flexibility in reordering executor
-       behavior.
+       The optimizer now has more knowledge about where it can place RLS
+       filter conditions, allowing better plans to be generated while still
+       enforcing the RLS conditions safely.
       </para>
       </listitem>
 
@@ -768,11 +793,10 @@
 2016-09-02 [9cca11c91] Speed up SUM calculation in numeric aggregates.
 -->
        <para>
-        Speed up <function>SUM()</> calculations (Heikki Linnakangas)
-       </para>
-
-       <para>
-        This uses an optimized numeric accumulator.
+        Speed up aggregate functions that calculate a running sum
+        using <type>numeric</>-type arithmetic, including some variants
+        of <function>SUM()</>, <function>AVG()</>,
+        and <function>STDDEV()</> (Heikki Linnakangas)
        </para>
       </listitem>
 
@@ -781,7 +805,7 @@
 2017-03-13 [aeed17d00] Use radix tree for character encoding conversions.
 -->
        <para>
-        Improve the performance of character encoding conversions by
+        Improve performance of character encoding conversions by
         using radix trees (Kyotaro Horiguchi, Heikki Linnakangas)
        </para>
       </listitem>
@@ -791,7 +815,7 @@
 2017-03-25 [b8d7f053c] Faster expression evaluation and targetlist projection.
 -->
        <para>
-        Reduce the function call overhead during query execution (Andres
+        Reduce expression evaluation overhead during query execution (Andres
         Freund)
        </para>
 
@@ -805,13 +829,15 @@
 2017-03-27 [b5635948a] Support hashed aggregation with grouping sets.
 -->
        <para>
-        Improve the performance of grouping sets (Andrew Gierth)
+        Allow hashed aggregation to be used with grouping sets (Andrew
+        Gierth)
        </para>
       </listitem>
 
       <listitem>
 <!--
 2017-04-07 [9c7f5229a] Optimize joins when the inner relation can be proven uni
+2017-06-03 [23886581b] Fix old corner-case logic error in final_cost_nestloop()
 -->
        <para>
         Use uniqueness guarantees to optimize certain join types (David
@@ -851,6 +877,8 @@
 <!--
 2016-12-20 [1753b1b02] Add pg_sequence system catalog
 2016-11-18 [67dc4ccbb] Add pg_sequences view
+2017-05-15 [f8dc1985f] Fix ALTER SEQUENCE locking
+2017-06-01 [3d79013b9] Make ALTER SEQUENCE, including RESTART, fully transactio
 -->
        <para>
         Create a <link
@@ -859,11 +887,18 @@
        </para>
 
        <para>
-        Sequence metadata includes start, increment, etc,
-        which is now transactional.  Sequence counters are
-        still stored in separate heap relations.  Also add <link
-        linkend="view-pg-sequences"><structname>pg_sequences</></> view
-        to show all sequences.
+        Sequence metadata includes the start, increment, etc, properties.
+        <command>ALTER SEQUENCE</> updates are now fully transactional,
+        implying that the sequence is locked until commit.  Sequences'
+        current values are still stored in individual table files, and
+        the <function>nextval()</> and <function>setval()</> functions
+        remain nontransactional.
+       </para>
+
+       <para>
+        Also
+        add <link linkend="view-pg-sequences"><structname>pg_sequences</></>
+        view to show all sequences.
        </para>
       </listitem>
 
@@ -872,9 +907,9 @@
 2017-03-08 [f9b1a0dd4] Expose explain's SUMMARY option
 -->
        <para>
-        Allow explicit control over <command><link
-        linkend="SQL-EXPLAIN">EXPLAIN</></>'s display of planning and
-        execution time (Ashutosh Bapat)
+        Allow explicit control
+        over <link linkend="SQL-EXPLAIN"><command>EXPLAIN</></>'s display
+        of planning and execution time (Ashutosh Bapat)
        </para>
 
        <para>
@@ -923,13 +958,13 @@
 2016-10-17 [7d3235ba4] By default, set log_line_prefix = '%m [%p] '.
 -->
         <para>
-         Change <xref linkend="guc-log-line-prefix"> default to include
-         current timestamp with milliseconds and the process id (Christoph
-         Berg)
+         Change the default value of <xref linkend="guc-log-line-prefix">
+         to include current timestamp (with milliseconds) and the process ID
+         in each line of postmaster log output (Christoph Berg)
         </para>
 
         <para>
-         The previous default was not to output a prefix.
+         The previous default was an empty prefix.
         </para>
        </listitem>
 
@@ -943,13 +978,11 @@
         </para>
 
         <para>
-         The new functions are <link
-         linkend="functions-admin-genfile-table"><function>pg_ls_logdir()</></>
-         and
-        <link
-        linkend="functions-admin-genfile-table"><function>pg_ls_waldir()</></>
-        and can be
-         executed by non-super users with the proper permissions.
+         The new functions
+         are <link linkend="functions-admin-genfile-table"><function>pg_ls_logdir()</></>
+         and <link linkend="functions-admin-genfile-table"><function>pg_ls_waldir()</></>
+         and can be executed by non-superusers with the proper
+         permissions.
         </para>
        </listitem>
 
@@ -971,12 +1004,13 @@
 2017-03-14 [2b32ac2a5] Include port number when logging successful binding to a
 -->
         <para>
-         Report the address and port number of successful startup socket
-         binding in the server logs (Tom Lane)
+         Report the address and port number of each listening socket
+         in the server log during postmaster startup (Tom Lane)
         </para>
 
         <para>
-         Also, report bind socket failure details in the server logs.
+         Also, when logging failure to bind a listening socket, include
+         the specific address we attempted to bind to.
         </para>
        </listitem>
 
@@ -1001,7 +1035,7 @@
         <para>
          Reduce message verbosity of lower-numbered debug levels
          controlled by
-        <xref linkend="guc-log-min-messages"> (Robert Haas)
+         <xref linkend="guc-log-min-messages"> (Robert Haas)
         </para>
 
         <para>
@@ -1046,30 +1080,18 @@
 
        <listitem>
 <!--
-2017-03-26 [fc70a4b0d] Show more processes in pg_stat_activity.
--->
-        <para>
-         Show auxiliary processes and background workers in
-         <structname>pg_stat_activity</> (Kuntal Ghosh)
-        </para>
-
-        <para>
-         New column <structfield>backend_type</> identifies the process
-         type.
-        </para>
-       </listitem>
-
-       <listitem>
-<!--
 2016-09-12 [fc3d4a44e] Identify walsenders in pg_stat_activity
+2017-03-26 [fc70a4b0d] Show more processes in pg_stat_activity.
 -->
         <para>
-         Display walsender processes in <structname>pg_stat_activity</>
-         (Michael Paquier)
+         Show auxiliary processes, background workers, and walsender
+         processes in <structname>pg_stat_activity</> (Kuntal Ghosh,
+         Michael Paquier)
         </para>
 
         <para>
-         This simplifies monitoring.
+         This simplifies monitoring.  A new
+         column <structfield>backend_type</> identifies the process type.
         </para>
        </listitem>
 
@@ -1078,7 +1100,7 @@
 2017-02-22 [4c728f382] Pass the source text for a parallel query to the workers
 -->
         <para>
-         Allow <structname>pg_stat_activity</> to show the source query
+         Allow <structname>pg_stat_activity</> to show the SQL query
          being executed by parallel workers (Rafia Sabih)
         </para>
        </listitem>
@@ -1091,7 +1113,7 @@
          Rename
          <structname>pg_stat_activity</>.<structfield>wait_event_type</>
          values <literal>LWLockTranche</> and
-        <literal>LWLockNamed</> to <literal>LWLock</> (Robert Haas)
+         <literal>LWLockNamed</> to <literal>LWLock</> (Robert Haas)
         </para>
 
         <para>
@@ -1133,7 +1155,7 @@
 2016-09-28 [babe05bc2] Turn password_encryption GUC into an enum.
 -->
        <para>
-        Change <acronym>GUC</> <xref linkend="guc-password-encryption">
+        Change the <xref linkend="guc-password-encryption"> server parameter
         from <type>boolean</> to <type>enum</> (Michael Paquier)
        </para>
 
@@ -1194,37 +1216,13 @@
 
        <para>
         This allows <acronym>SSL</> to be reconfigured without a server
-        restart by using <command>pg_ctl reload</>, <command>SELECT
+        restart, by using <command>pg_ctl reload</>, <command>SELECT
         pg_reload_conf()</>, or sending a <literal>SIGHUP</> signal.
-        Reload <acronym>SSL</> configuration updates do not work if the
-        <acronym>SSL</> key requires a passphrase.
-       </para>
-      </listitem>
-
-      <listitem>
-<!--
-2016-11-30 [81c52728f] doc: Remove claim about large shared_buffers on Windows
--->
-       <para>
-        Remove documented restriction about using large shared buffers on
-       <systemitem class="osname">Windows</> (Takayuki Tsunakawa)
-       </para>
-      </listitem>
-
-      <listitem>
-<!--
-2017-03-06 [21d4e2e20] Reduce lock levels for table storage params related to p
-2017-04-05 [68ea2b7f9] Reduce lock level for CREATE STATISTICS
--->
-       <para>
-        Reduce locking required to change table parameters (Simon Riggs,
-        Fabr&iacute;zio Mello)
-       </para>
-
-       <para>
-        For example, changing a table's <xref
-        linkend="guc-effective-io-concurrency"> setting can now be done
-        with a more lightweight lock.
+        However, reloading the <acronym>SSL</> configuration does not work
+        if the server's <acronym>SSL</> key requires a passphrase, as there
+        is no way to re-prompt for the passphrase.  The original
+        configuration will apply for the life of the postmaster in that
+        case.
        </para>
       </listitem>
 
@@ -1274,7 +1272,7 @@
 2016-12-22 [6ef2eba3f] Skip checkpoints, archiving on idle systems.
 -->
         <para>
-         Prevent checkpoints and <acronym>WAL</> archiving on
+         Prevent unnecessary checkpoints and <acronym>WAL</> archiving on
          otherwise-idle systems (Michael Paquier)
         </para>
        </listitem>
@@ -1285,7 +1283,7 @@
 2017-03-14 [bb4a39637] hash: Support WAL consistency checking.
 -->
         <para>
-         Add <acronym>GUC</> <xref linkend="guc-wal-consistency-checking">
+         Add <xref linkend="guc-wal-consistency-checking"> server parameter
          to add details to <acronym>WAL</> that can be sanity-checked on
          the standby (Kuntal Ghosh, Robert Haas)
         </para>
@@ -1336,9 +1334,10 @@
       </para>
 
       <para>
-       This allows more fine-grained replication options, including
-       replication between different major versions of PostgreSQL and
-       selective-table replication.
+       Logical replication allows more flexibility than physical
+       replication does, including replication between different major
+       versions of <productname>PostgreSQL</> and selective-table
+       replication.
       </para>
      </listitem>
 
@@ -1367,15 +1366,16 @@
 2017-05-02 [34fc61673] Change hot_standby default value to 'on'
 -->
       <para>
-       Reduce configuration necessary to perform streaming backup and
-       replication (Magnus Hagander, Dang Minh Huong)
+       Reduce configuration changes necessary to perform streaming backup
+       and replication (Magnus Hagander, Dang Minh Huong)
       </para>
 
       <para>
-       Specifically, defaults were changed for <xref
+       Specifically, the defaults were changed for <xref
        linkend="guc-wal-level">, <xref linkend="guc-max-wal-senders">,
        <xref linkend="guc-max-replication-slots">, and <xref
-       linkend="guc-hot-standby">.
+       linkend="guc-hot-standby"> to make them suitable for these usages
+       out-of-the-box.
       </para>
      </listitem>
 
@@ -1417,15 +1417,15 @@
 2016-09-03 [35250b6ad] New recovery target recovery_target_lsn
 -->
       <para>
-       Add specification of a Log Sequence Number (<acronym>LSN</>)
-       stopping point in
-      <link linkend="recovery-config"><filename>recovery.conf</></>
-      (Michael Paquier)
+       Allow specification of the recovery stopping point by Log Sequence
+       Number (<acronym>LSN</>) in
+       <link linkend="recovery-config"><filename>recovery.conf</></>
+       (Michael Paquier)
       </para>
 
       <para>
-       Previously only specification of the stop name, time, timeline,
-       xid, and immediate were supported.
+       Previously the stopping point could only be selected by timestamp or
+       XID.
       </para>
      </listitem>
 
@@ -1506,12 +1506,18 @@
 2016-11-22 [906bfcad7] Improve handling of "UPDATE ... SET (column_list) = row_
 -->
       <para>
-       Allow <literal>ROW</> to supply values to <command>UPDATE ... SET
-       (column_list)</> (Tom Lane)
+       Allow standard row constructor syntax in <literal>UPDATE ... SET
+       (<replaceable>column_list</>) = <replaceable>row_constructor</></literal>
+       (Tom Lane)
       </para>
 
       <para>
-       Also allow row values to be supplied by table.*.
+       The <replaceable>row_constructor</> can now begin with the
+       keyword <literal>ROW</>; previously that had to be omitted.  Also,
+       an occurrence of <literal><replaceable>table_name</>.*</literal>
+       within the <replaceable>row_constructor</> is now expanded into
+       multiple columns, as in other uses
+       of <replaceable>row_constructor</>s.
       </para>
      </listitem>
 
@@ -1520,12 +1526,14 @@
 2016-09-05 [c54159d44] Make locale-dependent regex character classes work for l
 -->
       <para>
-       Fix regular expression locale class handling for bytes greater
-       than <literal>U+7FF</> (Tom Lane)
+       Fix regular expressions' character class handling for large character
+       codes, particularly Unicode characters above <literal>U+7FF</>
+       (Tom Lane)
       </para>
 
       <para>
-       Previously such classes were not recognized.
+       Previously, such characters were never recognized as belonging to
+       locale-dependent character classes such as <literal>[[:alpha:]]</>.
       </para>
      </listitem>
 
@@ -1545,7 +1553,7 @@
       <para>
        Add table <link linkend="SQL-CREATETABLE-PARTITION">partitioning
        syntax</> that automatically creates partition constraints and
-       <command>INSERT</> routing (Amit Langote)
+       handles routing of tuple insertions and updates (Amit Langote)
       </para>
 
       <para>
@@ -1561,11 +1569,12 @@
 -->
       <para>
        Add <link linkend="SQL-CREATETRIGGER"><literal>AFTER</> trigger</>
-       transition table to record changed rows (Kevin Grittner)
+       transition tables to record changed rows (Kevin Grittner)
       </para>
 
       <para>
-       Transition table contents are accessible from server-side languages.
+       Transition tables are accessible from triggers written in
+       server-side languages.
       </para>
      </listitem>
 
@@ -1585,6 +1594,26 @@
       </para>
      </listitem>
 
+      <listitem>
+<!--
+2017-03-31 [64d4da511] For foreign keys, check REFERENCES privilege only on the
+-->
+       <para>
+        When creating a foreign-key constraint, check
+        for <literal>REFERENCES</> permission on only the referenced table
+        (Tom Lane)
+       </para>
+
+       <para>
+        Previously <literal>REFERENCES</> permission on the referencing
+        table was also required.  This appears to have stemmed from a
+        misreading of the SQL standard.  Since creating a foreign key (or
+        any other type of) constraint requires ownership privilege on the
+        constrained table, additionally requiring <literal>REFERENCES</>
+        permission seems rather pointless.
+       </para>
+      </listitem>
+
      <listitem>
 <!--
 2017-03-28 [ab89e465c] Altering default privileges on schemas
@@ -1620,12 +1649,13 @@
 2016-11-10 [279c439c7] Support "COPY view FROM" for views with INSTEAD OF INSER
 -->
       <para>
-       Allow <command>COPY view FROM</> on views with <literal>INSTEAD
+       Allow <literal>COPY <replaceable>view</>
+       FROM <replaceable>source</></> on views with <literal>INSTEAD
        INSERT</> triggers (Haribabu Kommi)
       </para>
 
       <para>
-       The triggers are fed the rows from <command>COPY</>.
+       The triggers are fed the data rows read by <command>COPY</>.
       </para>
      </listitem>
 
@@ -1635,13 +1665,13 @@
 -->
       <para>
        Allow the specification of a function name without arguments in
-       <acronym>DDL</> commands, when unique (Peter Eisentraut)
+       <acronym>DDL</> commands, if it is unique (Peter Eisentraut)
       </para>
 
       <para>
        For example, allow <link linkend="SQL-DROPFUNCTION"><command>DROP
        FUNCTION</></> on a function name without arguments if there
-       is only one function with that name.  This is required by the
+       is only one function with that name.  This behavior is required by the
        <acronym>SQL</> standard.
       </para>
      </listitem>
@@ -1658,25 +1688,15 @@
 
      <listitem>
 <!--
-2017-03-20 [b6fb534f1] Add IF NOT EXISTS for CREATE SERVER and CREATE USER MAPP
--->
-      <para>
-       Add <literal>IF NOT EXISTS</> for <link
-       linkend="SQL-CREATESERVER"><command>CREATE SERVER</></> and
-      <link linkend="SQL-CREATEUSERMAPPING"><command>CREATE USER
-      MAPPING</></> (Anastasia
-       Lubennikova)
-      </para>
-     </listitem>
-
-     <listitem>
-<!--
 2017-02-15 [6d16ecc64] Add CREATE COLLATION IF NOT EXISTS clause
+2017-03-20 [b6fb534f1] Add IF NOT EXISTS for CREATE SERVER and CREATE USER MAPP
 -->
       <para>
-       Add <literal>IF NOT EXISTS</> clause to <link
-       linkend="SQL-CREATECOLLATION"><command>CREATE COLLATION</></>
-       (Peter Eisentraut)
+       Support <literal>IF NOT EXISTS</>
+       in <link linkend="SQL-CREATESERVER"><command>CREATE SERVER</></>,
+       <link linkend="SQL-CREATEUSERMAPPING"><command>CREATE USER MAPPING</></>,
+       and <link linkend="SQL-CREATECOLLATION"><command>CREATE COLLATION</></>
+       (Anastasia Lubennikova, Peter Eisentraut)
       </para>
      </listitem>
 
@@ -1686,7 +1706,7 @@
 2017-03-03 [9eb344faf] Allow vacuums to report oldestxmin
 -->
       <para>
-       Have <link linkend="SQL-VACUUM"><command>VACUUM VERBOSE</></> report
+       Make <link linkend="SQL-VACUUM"><command>VACUUM VERBOSE</></> report
        the number of skipped frozen pages and oldest xmin (Masahiko
        Sawada, Simon Riggs)
       </para>
@@ -1705,11 +1725,6 @@
        Improve speed of <command>VACUUM</>'s removal of trailing empty
        heap pages (Claudio Freire, &Aacute;lvaro Herrera)
       </para>
-
-      <para>
-       This information is also included in <xref
-       linkend="guc-log-autovacuum-min-duration"> output.
-      </para>
      </listitem>
 
     </itemizedlist>
@@ -1731,8 +1746,8 @@
        </para>
 
        <para>
-        This is accessed via <function>ts_headline()</> and
-        <function>to_tsvector()</>.
+        The functions <function>ts_headline()</> and
+        <function>to_tsvector()</> can now be used on these data types.
        </para>
       </listitem>
 
@@ -1741,14 +1756,15 @@
 2017-03-15 [c7a9fa399] Add support for EUI-64 MAC addresses as macaddr8
 -->
       <para>
-       Add support for <acronym>EUI-64</> <acronym>MAC</> addresses as
-       <link linkend="datatype-macaddr8"><type>MACADDR8</></> (Haribabu
-       Kommi)
+       Add support for <acronym>EUI-64</> <acronym>MAC</> addresses, as a
+       new data type <link linkend="datatype-macaddr8"><type>macaddr8</></>
+       (Haribabu Kommi)
       </para>
 
       <para>
-       This complements support for <acronym>EUI-48</> <acronym>MAC</>
-       addresses as <type>macaddr</>.
+       This complements the existing support
+       for <acronym>EUI-48</> <acronym>MAC</> addresses
+       as <type>macaddr</>.
       </para>
      </listitem>
 
@@ -1794,8 +1810,9 @@
       </para>
 
       <para>
-       Previously "anyarray" values were converted to <type>JSON</>
-       strings.
+       Previously columns declared as <type>anyarray</> (particularly those
+       in the <structname>pg_stats</> view) were converted to <type>JSON</>
+       strings rather than arrays.
       </para>
      </listitem>
 
@@ -1825,7 +1842,7 @@
 2016-09-14 [656df624c] Add overflow checks to money type input function
 -->
       <para>
-       More strictly check the <type>money</> type for overflow operations
+       Check for overflow in the <type>money</> type's input function
        (Peter Eisentraut)
       </para>
      </listitem>
@@ -1850,8 +1867,9 @@
       </para>
 
       <para>
-       Similar to <function>regexp_matches()</>, but only returns results
-       from the first match so it is easier use for simple cases.
+       This is similar to <function>regexp_matches()</>, but it only
+       returns results from the first match so it does not need to return a
+       set, making it easier to use for simple cases.
       </para>
      </listitem>
 
@@ -1860,14 +1878,10 @@
 2017-01-18 [d00ca333c] Implement array version of jsonb_delete and operator
 -->
       <para>
-       Add version of jsonb's <link
+       Add a version of <type>jsonb</>'s <link
        linkend="functions-jsonb-op-table">delete operator</> that takes
        an array of keys to delete (Magnus Hagander)
       </para>
-
-      <para>
-       The <type>JSONB</> delete operator also now supports arrays.
-      </para>
      </listitem>
 
      <listitem>
@@ -1875,13 +1889,18 @@
 2017-04-06 [cf35346e8] Make json_populate_record and friends operate recursivel
 -->
       <para>
-       Improve <link
-       linkend="functions-json-processing-table"><function>json_populate_record()</></>
-       and friends operate recursively (Nikita Glukhov)
+       Make <link linkend="functions-json-processing-table"><function>json_populate_record()</></>
+       and related functions process JSON arrays and objects recursively
+       (Nikita Glukhov)
       </para>
 
       <para>
-       CLARIFY
+       With this change, array-type fields in the destination SQL type are
+       properly converted from JSON arrays, and composite-type fields are
+       properly converted from JSON objects.  Previously, such cases would
+       fail because the text representation of the JSON value would be fed
+       to <function>array_in()</> or <function>record_in()</>, and its
+       syntax would not match what those input functions expect.
       </para>
      </listitem>
 
@@ -1892,15 +1911,15 @@
       <para>
        Add function <link
        linkend="functions-txid-snapshot"><function>txid_current_ifassigned()</></>
-       to return <literal>NULL</> if no transaction id has been assigned
-       (Craig Ringer)
+       to return the current transaction ID or <literal>NULL</> if no
+       transaction ID has been assigned (Craig Ringer)
       </para>
 
       <para>
        This is different from <link
        linkend="functions-txid-snapshot"><function>txid_current()</></>,
-       which always returns a transaction id by assigning one if necessary.
-       This can be also run on standby servers.
+       which always returns a transaction ID, assigning one if necessary.
+       Unlike that function, this function can be run on standby servers.
       </para>
      </listitem>
 
@@ -1915,7 +1934,7 @@
       </para>
 
       <para>
-       This is useful for checking after an abrupt disconnection if
+       This is useful for checking after an abrupt disconnection whether
        your previous transaction committed and you just didn't receive
        the acknowledgement.
       </para>
@@ -1938,13 +1957,15 @@
 2016-09-28 [d3cd36a13] Make to_timestamp() and to_date() range-check fields of
 -->
       <para>
-       Have <function>to_timestamp()</> and <function>to_date()</> check
-       input values for validity (Artur Zakirov)
+       Make <function>to_timestamp()</> and <function>to_date()</> reject
+       out-of-range input fields (Artur Zakirov)
       </para>
 
       <para>
-       Previously <function>to_date('2009-06-40','YYYY-MM-DD')</> was
-       accepted and returned '2009-07-10'.  It will now generate an error.
+       For example,
+       previously <literal>to_date('2009-06-40','YYYY-MM-DD')</> was
+       accepted and returned <literal>2009-07-10</>.  It will now generate
+       an error.
       </para>
      </listitem>
 
@@ -1962,12 +1983,13 @@
 2017-03-27 [70ec3f1f8] PL/Python: Add cursor and execute methods to plan object
 -->
       <para>
-       Allow the  PL/Python plan object to call cursor and execute methods
+       Allow PL/Python's <function>cursor()</> and <function>execute()</>
+       functions to be called as methods of their plan-object arguments
        (Peter Eisentraut)
       </para>
 
       <para>
-       This is a more object oriented style.
+       This allows a more object-oriented programming style.
       </para>
      </listitem>
 
@@ -1976,24 +1998,13 @@
 2016-12-13 [55caaaeba] Improve handling of array elements as getdiag_targets an
 -->
       <para>
-       Allow PL/pgSQL's <command>GET DIAGNOSTICS</> to retrieve values
-       into array elements (Tom Lane)
+       Allow PL/pgSQL's <command>GET DIAGNOSTICS</> statement to retrieve
+       values into array elements (Tom Lane)
       </para>
-     </listitem>
 
-     <listitem>
-<!--
-2016-11-08 [1833f1a1c] Simplify code by getting rid of SPI_push, SPI_pop, SPI_r
--->
       <para>
-       Remove <acronym>SPI</> functions <function>SPI_push()</>,
-       <function>SPI_pop()</>, <function>SPI_restore_connection()</>
-       as unnecessary (Tom Lane)
-      </para>
-
-      <para>
-       Their functionality now happens automatically.  Also,
-       <function>SPI_palloc()</> now requires an active connection.
+       Previously, a syntactic restriction prevented the target variable
+       from being an array element.
       </para>
      </listitem>
 
@@ -2033,13 +2044,9 @@
 2017-03-07 [0d2b1f305] Invent start_proc parameters for PL/Tcl.
 -->
        <para>
-        Add <acronym>GUC</>s to allow initialization routines to be called
-        on PL/Tcl startup (Tom Lane)
-       </para>
-
-       <para>
-        The <acronym>GUC</>s are <varname>pltcl.start_proc</> and
-        <varname>pltclu.start_proc</>.
+        Add server parameters <xref linkend="guc-pltcl-start-proc">
+        and <xref linkend="guc-pltclu-start-proc">, to allow initialization
+        functions to be called on PL/Tcl startup (Tom Lane)
        </para>
       </listitem>
 
@@ -2056,15 +2063,17 @@
      <listitem>
 <!--
 2016-11-03 [274bb2b38] libpq: Allow connection strings and URIs to specify mult
+2017-05-19 [5f374fe7a] libpq: Try next host if one of them times out.
 -->
       <para>
-       Allow libpq to connect to <link
-       linkend="libpq-connect-host">multiple specified</> host names
+       Allow specification of <link
+       linkend="libpq-connect-host">multiple host names</> in libpq
+       connection strings and URIs
        (Robert Haas)
       </para>
 
       <para>
-       libpq will connect with the first responsive host name.
+       libpq will connect to the first responsive server in the list.
       </para>
      </listitem>
 
@@ -2073,14 +2082,15 @@
 2016-11-29 [721f7bd3c] libpq: Add target_session_attrs parameter.
 -->
       <para>
-       Allow the libpq connection string to request a <link
-       linkend="libpq-connect-target-session-attrs">read/write host</>
+       Allow libpq connection strings and URIs to request a <link
+       linkend="libpq-connect-target-session-attrs">read/write host</>,
+       that is a master server rather than a standby server
        (Victor Wagner, Mithun Cy)
       </para>
 
       <para>
-       This is useful when multiple libpq host names are
-       specified, and is controlled by libpq connection parameter
+       This is useful when multiple host names are
+       specified.  It is controlled by libpq connection parameter
        <option>target_session_attrs</>.
       </para>
      </listitem>
@@ -2090,7 +2100,7 @@
 2017-01-24 [ba005f193] Allow password file name to be specified as a libpq conn
 -->
       <para>
-       Allow <link linkend="libpq-connect-passfile">password file name</>
+       Allow the <link linkend="libpq-connect-passfile">password file name</>
        to be specified as a libpq connection parameter (Julian Markwort)
       </para>
 
@@ -2107,14 +2117,16 @@
        Add function <link
        linkend="libpq-pqencryptpasswordconn"><function>PQencryptPasswordConn()</></>
        to allow creation of more types of encrypted passwords on the
-       client-side (Michael Paquier, Heikki Linnakangas)
+       client side (Michael Paquier, Heikki Linnakangas)
       </para>
 
       <para>
-       Previously only <literal>MD5</> passwords could be created using <link
+       Previously only <literal>MD5</>-encrypted passwords could be created
+       using <link
        linkend="libpq-pqencryptpassword"><function>PQencryptPassword()</></>.
        This new function can also create <link
-       linkend="auth-pg-hba-conf"><literal>SCRAM-SHA-256</></> passwords.
+       linkend="auth-pg-hba-conf"><literal>SCRAM-SHA-256</></>-encrypted
+       passwords.
       </para>
      </listitem>
 
@@ -2123,12 +2135,13 @@
 2016-08-16 [a7b5573d6] Remove separate version numbering for ecpg preprocessor.
 -->
       <para>
-       ecpg preprocessor version changed from 4.12 to 10 (Tom Lane)
+       Change <application>ecpg</> preprocessor version from 4.12 to 10
+       (Tom Lane)
       </para>
 
       <para>
-       The ecpg version now matches the PostgreSQL distribution version
-       number.
+       Henceforth the <application>ecpg</> version will match
+       the <productname>PostgreSQL</> distribution version number.
       </para>
      </listitem>
 
@@ -2156,8 +2169,9 @@
        </para>
 
        <para>
-        The new syntax uses \if, \elif, \else, and \endif.  This is
-        particularly helpful for scripting.
+        This feature adds <application>psql</>
+        meta-commands <command>\if</>, <command>\elif</>, <command>\else</>,
+        and <command>\endif</>.  This is primarily helpful for scripting.
        </para>
       </listitem>
 
@@ -2166,8 +2180,9 @@
 2017-03-07 [b2678efd4] psql: Add \gx command
 -->
        <para>
-        Add <application>psql</> \gx command to perform \g(execute)
-        in expanded mode (\x) (Christoph Berg)
+        Add <application>psql</> <command>\gx</> meta-command to execute
+        (<command>\g</>) a query in expanded mode (<command>\x</>)
+        (Christoph Berg)
        </para>
       </listitem>
 
@@ -2176,13 +2191,14 @@
 2016-11-03 [a0f357e57] psql: Split up "Modifiers" column in \d and \dD
 -->
        <para>
-        Improve <application>psql</>'s \d (relation) and \dD (domain)
-        commands to specify collation, nullable, and default in separate
-        columns (Peter Eisentraut)
+        Improve <application>psql</>'s <command>\d</> (display relation)
+        and <command>\dD</> (display domain) commands to show collation,
+        nullable, and default properties in separate columns (Peter
+        Eisentraut)
        </para>
 
        <para>
-        Previous they were in a single "Modifiers" column.
+        Previous they were shown in a single <quote>Modifiers</> column.
        </para>
       </listitem>
 
@@ -2191,13 +2207,13 @@
 2017-04-01 [f833c847b] Allow psql variable substitution to occur in backtick co
 -->
        <para>
-        Expand <application>psql</> colon variables when used in
-        backtick-executed contexts (Tom Lane)
+        Expand <application>psql</> variable references in
+        backtick-executed strings (Tom Lane)
        </para>
 
        <para>
-        This is particularly useful for the new <application>psql</>
-        conditional branch support commands.
+        This is particularly useful in the new <application>psql</>
+        conditional branch commands.
        </para>
       </listitem>
 
@@ -2208,17 +2224,23 @@
 2017-02-02 [fd6cd6980] Clean up psql's behavior for a few more control variable
 -->
        <para>
-        Prevent <application>psql</> special variables from being set to
+        Prevent <application>psql</>'s special variables from being set to
         invalid values (Daniel V&eacute;rit&eacute;, Tom Lane)
        </para>
 
        <para>
-        Previously setting <application>psql</> special variables
-        to invalid values produced the default behavior.  \set and
-        \unset of special variables now sets them to "on" and its
-        default value, rather than a zero-length string and undefined.
-        Also have \set always display values for <literal>FETCH_COUNT</>,
-        <literal>HISTSIZE</>, and <literal>IGNOREEOF</>.
+        Previously, setting one of <application>psql</>'s special variables
+        to an invalid value silently resulted in the default behavior.
+        <command>\set</> on a special variable now fails if the proposed
+        new value is invalid.  As a special exception, <command>\set</>
+        with an empty or omitted new value, on a boolean-valued special
+        variable, still has the effect of setting the variable
+        to <literal>on</>; but now it actually acquires that value rather
+        than an empty string.  <command>\unset</> on a special variable now
+        explicitly sets the variable to its default value, which is also
+        the value it acquires at startup.  In sum, a control variable now
+        always has a displayable value that reflects
+        what <application>psql</> is actually doing.
        </para>
       </listitem>
 
@@ -2256,8 +2278,8 @@
 2016-11-09 [41124a91e] pgbench: Allow the transaction log file prefix to be cha
 -->
        <para>
-        Add pgbench option <option>--log-prefix</> to control the log
-        file prefix (Masahiko Sawada)
+        Add <application>pgbench</> option <option>--log-prefix</> to
+        control the log file prefix (Masahiko Sawada)
        </para>
       </listitem>
 
@@ -2266,8 +2288,13 @@
 2017-01-20 [cdc2a7047] Allow backslash line continuations in pgbench's meta com
 -->
        <para>
-        Allow pgbench's meta commands to span multiple lines via a
-        line-terminating backslash (Fabien Coelho)
+        Allow <application>pgbench</>'s meta-commands to span multiple
+        lines (Fabien Coelho)
+       </para>
+
+       <para>
+        A meta-command can now be continued onto the next line by writing
+        backslash-return.
        </para>
       </listitem>
 
@@ -2289,7 +2316,7 @@
       <para>
        Add <link
        linkend="app-pgreceivewal"><application>pg_receivewal</></>
-       option <option>-Z</>/<option>--compress</> to support compression
+       option <option>-Z</>/<option>--compress</> to specify compression
        (Michael Paquier)
       </para>
      </listitem>
@@ -2301,7 +2328,7 @@
       <para>
        Add <link
        linkend="app-pgrecvlogical"><application>pg_recvlogical</></> option
-       (<option>--endpos</>) to specify the ending position (Craig Ringer)
+       <option>--endpos</> to specify the ending position (Craig Ringer)
       </para>
 
       <para>
@@ -2328,7 +2355,8 @@
     </itemizedlist>
 
     <sect4>
-     <title><link linkend="APP-PGDUMP"><application>pg_dump</></>, <link linkend="APP-PG-DUMPALL"><application>pg_dumpall</></>.
+     <title><link linkend="APP-PGDUMP"><application>pg_dump</></>,
+     <link linkend="APP-PG-DUMPALL"><application>pg_dumpall</></>,
      <link linkend="APP-PGRESTORE"><application>pg_restore</></></title>
 
      <itemizedlist>
@@ -2342,7 +2370,7 @@
        </para>
 
        <para>
-        This added a new <option>-N</>/<option>--exclude-schema</> option.
+        This adds a new <option>-N</>/<option>--exclude-schema</> option.
        </para>
       </listitem>
 
@@ -2352,11 +2380,11 @@
 -->
        <para>
         Add <option>--no-blobs</> option to
-       <application>pg_dump</> (Guillaume Lelarge)
+        <application>pg_dump</> (Guillaume Lelarge)
        </para>
 
        <para>
-        This suppresses the dumping of large objects.
+        This suppresses dumping of large objects.
        </para>
       </listitem>
 
@@ -2366,12 +2394,13 @@
 -->
        <para>
         Add <application>pg_dumpall</> option
-        <option>--no-role-passwords</> to dump roles without user passwords
+        <option>--no-role-passwords</> to omit role passwords
         (Robins Tharakan, Simon Riggs)
        </para>
 
        <para>
-        This allows easier dumping for less-privileged users.
+        This allows use of <application>pg_dumpall</> by non-superusers;
+        without this option, it fails due to inability to read passwords.
        </para>
       </listitem>
 
@@ -2380,13 +2409,15 @@
 2017-03-22 [96a7128b7] Sync pg_dump and pg_dumpall output
 -->
        <para>
-        Issue fsync on the output files generated by
+        Issue <function>fsync()</> on the output files generated by
         <application>pg_dump</> and
-       <application>pg_dumpall</> (Michael Paquier)
+        <application>pg_dumpall</> (Michael Paquier)
        </para>
 
        <para>
-        This can be disabled with the <option>--no-sync</> option.
+        This provides more security that the output is safely stored on
+        disk before the program exits.  This can be disabled with
+        the new <option>--no-sync</> option.
        </para>
       </listitem>
 
@@ -2435,15 +2466,22 @@
       <listitem>
 <!--
 2016-09-29 [bc34223bc] pg_basebackup pg_receivexlog: Issue fsync more carefully
-2016-09-29 [6ed2d8584] pg_basebackup: Add - option
 -->
        <para>
-        Improve fsync handling of <application>pg_basebackup</> and
+        Be more careful about fsync'ing in all required places
+        in <application>pg_basebackup</> and
         <application>pg_receivewal</> (Michael Paquier)
        </para>
+      </listitem>
 
+      <listitem>
+<!--
+2016-09-29 [6ed2d8584] pg_basebackup: Add -\-nosync option
+2016-10-19 [5d58c07a4] initdb pg_basebackup: Rename -\-noxxx options to -\-no-x
+-->
        <para>
-        Also add <option>--nosync</> option to disable fsync.
+        Add <application>pg_basebackup</> option <option>--no-sync</> to
+        disable fsync (Michael Paquier)
        </para>
       </listitem>
 
@@ -2455,10 +2493,6 @@
         Improve <application>pg_basebackup</>'s handling of which
         directories to skip (David Steele)
        </para>
-
-       <para>
-        Also improve the documentation of skipped directories.
-       </para>
       </listitem>
 
      </itemizedlist>
@@ -2495,12 +2529,60 @@
 2016-10-19 [caf936b09] pg_ctl: Add long option for -o
 -->
        <para>
-        Add long options flag for <application>pg_ctl</>
-        <literal>options</> (Peter Eisentraut)
+        Add long option for <application>pg_ctl</> server options
+        (<option>--options</>) (Peter Eisentraut)
+       </para>
+      </listitem>
+
+      <listitem>
+<!--
+2017-06-28 [f13ea95f9] Change pg_ctl to detect server-ready by watching status
+-->
+       <para>
+        Make <literal>pg_ctl start --wait</> detect server-ready by
+        watching <filename>postmaster.pid</>, not by attempting connections
+        (Tom Lane)
+       </para>
+
+       <para>
+        The postmaster has been changed to report its ready-for-connections
+        status in <filename>postmaster.pid</>, and <application>pg_ctl</>
+        now examines that file to detect whether startup is complete.
+        This is more efficient and reliable than the old method, and it
+        eliminates postmaster log entries about rejected connection
+        attempts during startup.
+       </para>
+      </listitem>
+
+      <listitem>
+<!--
+2017-06-26 [c61559ec3] Reduce pg_ctl's reaction time when waiting for postmaste
+-->
+       <para>
+        Reduce <application>pg_ctl</>'s reaction time when waiting for
+        postmaster start/stop (Tom Lane)
+       </para>
+
+       <para>
+        <application>pg_ctl</> now probes ten times per second when waiting
+        for a postmaster state change, rather than once per second.
+       </para>
+      </listitem>
+
+      <listitem>
+<!--
+2017-07-05 [1bac5f552] pg_ctl: Make failure to complete operation a nonzero exi
+-->
+       <para>
+        Ensure that <application>pg_ctl</> exits with nonzero status if an
+        operation being waited for does not complete within the timeout
+        (Peter Eisentraut)
        </para>
 
        <para>
-        It is called <option>--options</>.
+        The <literal>start</> and <literal>promote</> operations now return
+        exit status 1, not 0, in such cases.  The <literal>stop</> operation
+        has always done that.
        </para>
       </listitem>
 
@@ -2519,13 +2601,43 @@
 2016-08-15 [ca9112a42] Stamp HEAD as 10devel.
 -->
       <para>
-       New major version numbering (Peter Eisentraut, Tom Lane)
+       Change to two-part release version numbering (Peter Eisentraut, Tom
+       Lane)
       </para>
 
       <para>
+       Release numbers will now have two parts (e.g., <literal>10.1</>)
+       rather than three (e.g., <literal>9.6.3</>).
        Major versions will now increase just the first number, and minor
-       releases will increase just the second number.  A third number
-       will no longer be used in PostgreSQL version numbers.
+       releases will increase just the second number.
+       Release branches will be referred to by single numbers
+       (e.g., <literal>10</> rather than <literal>9.6</>).
+       This change is intended to reduce user confusion about what is a
+       major or minor release of <productname>PostgreSQL</>.
+      </para>
+     </listitem>
+
+     <listitem>
+<!--
+2017-06-21 [8ff6d4ec7] Adjust pgindent script to use pg_bsd_indent 2.0.
+2017-06-21 [e3860ffa4] Initial pgindent run with pg_bsd_indent version 2.0.
+2017-06-21 [c7b8998eb] Phase 2 of pgindent updates.
+2017-06-21 [382ceffdf] Phase 3 of pgindent updates.
+2017-06-21 [81f056c72] Remove entab and associated detritus.
+-->
+      <para>
+       Improve behavior of <application>pgindent</>
+       (Piotr Stefaniak, Tom Lane)
+      </para>
+
+      <para>
+       We have switched to a new version of <application>pg_bsd_indent</>
+       based on recent improvements made by the FreeBSD project.  This
+       fixes numerous small bugs that led to odd C code formatting
+       decisions.  Most notably, lines within parentheses (such as in a
+       multi-line function call) are now uniformly indented to match the
+       opening paren, even if that would result in code extending past the
+       right margin.
       </para>
      </listitem>
 
@@ -2566,6 +2678,32 @@
 
      <listitem>
 <!--
+2016-11-08 [1833f1a1c] Simplify code by getting rid of SPI_push, SPI_pop, SPI_r
+-->
+      <para>
+       Remove <acronym>SPI</> functions <function>SPI_push()</>,
+       <function>SPI_pop()</>, <function>SPI_push_conditional()</>,
+       <function>SPI_pop_conditional()</>,
+       and <function>SPI_restore_connection()</> as unnecessary (Tom Lane)
+      </para>
+
+      <para>
+       Their functionality now happens automatically.  There are now no-op
+       macros by these names so that external modules don't need to be
+       updated immediately, but eventually such calls should be removed.
+      </para>
+
+      <para>
+       A side effect of this change is that <function>SPI_palloc()</> and
+       allied functions now require an active SPI connection; they do not
+       degenerate to simple <function>palloc()</> if there is none.  That
+       previous behavior was not very useful and posed risks of unexpected
+       memory leaks.
+      </para>
+     </listitem>
+
+     <listitem>
+<!--
 2016-12-02 [13e14a78e] Management of free memory pages.
 2016-12-02 [13df76a53] Introduce dynamic shared memory areas.
 2016-12-19 [e13029a5c] Provide a DSA area for all parallel queries.
@@ -2597,7 +2735,7 @@
       </para>
 
       <para>
-       This avoids some limits on SysV semaphore usage.
+       This avoids platform-specific limits on SysV semaphore usage.
       </para>
      </listitem>
 
@@ -2630,30 +2768,41 @@
       </para>
 
       <para>
-      <function>gettimeofday()</> is used if <function>clock_gettime()</>
-      is not available.
+       <function>gettimeofday()</> is still used
+       if <function>clock_gettime()</> is not available.
       </para>
      </listitem>
 
      <listitem>
 <!--
 2016-12-05 [fe0a0b599] Replace PostmasterRandom() with a stronger source, secon
+2017-07-03 [bf723a274] Forbid gen_random_uuid() with -\-disable-strong-random
 -->
       <para>
        Add more robust random number generators to be used for
-       cryptographic secure uses (Magnus Hagander, Michael Paquier,
+       cryptographically secure uses (Magnus Hagander, Michael Paquier,
        Heikki Linnakangas)
       </para>
 
       <para>
-       If no strong random number generator can be found, configure
-       will fail unless the <link linkend="configure">configure</>
-       <option>--disable-strong-random</> is used.  However, with this
-       option, pgcrypto functions requiring a strong random number
+       If no strong random number generator can be found, configure will
+       fail unless the <link linkend="configure">configure</>
+       option <option>--disable-strong-random</> is used.  However, with
+       this option, pgcrypto functions requiring a strong random number
        generator will be disabled.
       </para>
      </listitem>
 
+    <listitem>
+<!--
+2016-10-11 [2b860f52e] Remove "sco" and "unixware" ports.
+-->
+     <para>
+      Remove <systemitem class="osname">SCO</> and <systemitem
+      class="osname">Unixware</> ports (Tom Lane)
+     </para>
+    </listitem>
+
      <listitem>
 <!--
 2016-08-18 [e8306745e] doc: Speed up XSLT builds
@@ -2670,8 +2819,8 @@
 2017-04-06 [510074f9f] Remove use of Jade and DSSSL
 -->
       <para>
-       Use <acronym>XSLT</> to build the PostgreSQL documentation (Peter
-       Eisentraut)
+       Use <acronym>XSLT</> to build the <productname>PostgreSQL</>
+       documentation (Peter Eisentraut)
       </para>
 
       <para>
@@ -2723,7 +2872,7 @@
        This reduces the amount of data that must be passed
        from the foreign data wrapper server, and offloads
        aggregate computation from the requesting server.  The <link
-       linkend="postgres-fdw"><application>postgres_fdw</></> is able to
+       linkend="postgres-fdw"><application>postgres_fdw</></> FDW is able to
        perform this optimization.  There are also improvements in
        pushing down joins involving extensions.
       </para>
@@ -2828,7 +2977,7 @@
       </para>
 
       <para>
-       This allows it be less disruptive when run on production systems.
+       This allows it to be less disruptive when run on production systems.
       </para>
      </listitem>
 
@@ -2837,9 +2986,9 @@
 2017-02-03 [e759854a0] pgstattuple: Add pgstathashindex.
 -->
       <para>
-       Add <function>pgstathashindex()</> function to <link
-       linkend="pgstattuple"><application>pgstattuple</></> to view hash
-       index statistics (Ashutosh Sharma)
+       Add <link linkend="pgstattuple"><application>pgstattuple</></>
+       function <function>pgstathashindex()</> to view hash index
+       statistics (Ashutosh Sharma)
       </para>
      </listitem>
 
@@ -2848,13 +2997,12 @@
 2016-09-29 [fd321a1df] Remove superuser checks in pgstattuple
 -->
       <para>
-       Allow <link linkend="pgstattuple"><application>pgstattuple</></>
-       to use <command>GRANT</> permissions (Stephen Frost)
+       Use <command>GRANT</> permissions to
+       control <application>pgstattuple</> function usage (Stephen Frost)
       </para>
 
       <para>
-       This allows non-superusers to run these functions if permissions
-       allow.
+       This allows DBAs to allow non-superusers to run these functions.
       </para>
      </listitem>
 
@@ -2863,8 +3011,7 @@
 2016-10-28 [d4b5d4cad] pgstattuple: Don't take heavyweight locks when examining
 -->
       <para>
-       Reduce locking when <link
-       linkend="pgstattuple"><application>pgstattuple</></> examines hash
+       Reduce locking when <application>pgstattuple</> examines hash
        indexes (Amit Kapila)
       </para>
      </listitem>
@@ -2874,34 +3021,30 @@
 2017-03-17 [fef2bcdcb] pageinspect: Add page_checksum function
 -->
       <para>
-       Add <function>page_checksum()</> function to <link
-       linkend="pageinspect"><application>pageinspect</></> (Tomas Vondra)
+       Add <link linkend="pageinspect"><application>pageinspect</></>
+       function <function>page_checksum()</> to show a page's checksum
+       (Tomas Vondra)
       </para>
      </listitem>
 
      <listitem>
 <!--
-2017-02-02 [08bf6e529] pageinspect: Support hash indexes.
+2017-04-04 [193f5f9e9] pageinspect: Add bt_page_items function with bytea argum
 -->
       <para>
-       Add hash index support to <link
-       linkend="pageinspect"><application>pageinspect</></> (Jesper
-       Pedersen, Ashutosh Sharma)
+       Add <application>pageinspect</>
+       function <function>bt_page_items()</> to print page items from a
+       page image (Tomas Vondra)
       </para>
      </listitem>
 
      <listitem>
 <!--
-2017-04-04 [193f5f9e9] pageinspect: Add bt_page_items function with bytea argum
+2017-02-02 [08bf6e529] pageinspect: Support hash indexes.
 -->
       <para>
-       Add <link linkend="pageinspect"><application>pageinspect</></>
-       function <function>bt_page_items()</> to print page items from a
-       page image (Tomas Vondra)
-      </para>
-
-      <para>
-       Previously only block numbers were supported.
+       Add hash index support to <application>pageinspect</> (Jesper
+       Pedersen, Ashutosh Sharma)
       </para>
      </listitem>
 
diff --git a/doc/src/sgml/sourcerepo.sgml b/doc/src/sgml/sourcerepo.sgml
index 59b996edc9..26e203af87 100644
--- a/doc/src/sgml/sourcerepo.sgml
+++ b/doc/src/sgml/sourcerepo.sgml
@@ -20,9 +20,9 @@
    Note that building <productname>PostgreSQL</productname> from the source
    repository requires reasonably up-to-date versions of <application>bison</>,
    <application>flex</>, and <application>Perl</>. These tools are not needed
-   to build from a distribution tarball since the files they are used to build
-   are included in the tarball.  Other tool requirements are the same as shown
-   in <xref linkend="installation">.
+   to build from a distribution tarball, because the files that these tools
+   are used to build are included in the tarball.  Other tool requirements
+   are the same as shown in <xref linkend="install-requirements">.
   </para>
 
  <sect1 id="git">
diff --git a/doc/src/sgml/sslinfo.sgml b/doc/src/sgml/sslinfo.sgml
index a4ce7e8d2c..7bda33efa3 100644
--- a/doc/src/sgml/sslinfo.sgml
+++ b/doc/src/sgml/sslinfo.sgml
@@ -47,8 +47,8 @@
     </term>
     <listitem>
     <para>
-     Returns the name of the protocol used for the SSL connection (e.g. SSLv2,
-     SSLv3, or TLSv1).
+     Returns the name of the protocol used for the SSL connection (e.g. TLSv1.0
+     TLSv1.1, or TLSv1.2).
     </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index a156693ec8..aed2cf8bca 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -630,7 +630,7 @@ can be used to examine the information stored in free space maps.
 Each heap relation has a Visibility Map
 (VM) to keep track of which pages contain only tuples that are known to be
 visible to all active transactions; it also keeps track of which pages contain
-only unfrozen tuples.  It's stored
+only frozen tuples.  It's stored
 alongside the main relation data in a separate relation fork, named after the
 filenode number of the relation, plus a <literal>_vm</> suffix. For example,
 if the filenode of a relation is 12345, the VM is stored in a file called