Merge pull request #160 from postgres/master

Sync Fork from Upstream Repo

Author: sthagen

doc/src/sgml/bki.sgml

@@ -669,7 +669,7 @@
      <filename>reformat_dat_file.pl</filename> can be adapted to perform
      many kinds of bulk changes.  Look for its block comments showing where
      one-off code can be inserted.  In the following example, we are going
-     to consolidate two boolean fields in <structname>pg_proc</structname>
+     to consolidate two Boolean fields in <structname>pg_proc</structname>
      into a char field:
 
      <orderedlist>

doc/src/sgml/config.sgml

@@ -3141,7 +3141,7 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        This parameter enables compression of WAL using the specified 
+        This parameter enables compression of WAL using the specified
         compression method.
         When enabled, the <productname>PostgreSQL</productname>
         server compresses full page images written to WAL when
@@ -8434,6 +8434,68 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
       </listitem>
      </varlistentry>
 
+     <varlistentry id="guc-transaction-isolation" xreflabel="transaction_isolation">
+      <term><varname>transaction_isolation</varname> (<type>enum</type>)
+      <indexterm>
+       <primary>transaction isolation level</primary>
+      </indexterm>
+      <indexterm>
+       <primary><varname>transaction_isolation</varname> configuration parameter</primary>
+      </indexterm>
+      </term>
+      <listitem>
+       <para>
+        This parameter reflects the current transaction's isolation level.
+        At the beginning of each transaction, it is set to the current value
+        of <xref linkend="guc-default-transaction-isolation"/>.
+        Any subsequent attempt to change it is equivalent to a <xref
+        linkend="sql-set-transaction"/> command.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="guc-transaction-read-only" xreflabel="transaction_read_only">
+      <term><varname>transaction_read_only</varname> (<type>boolean</type>)
+      <indexterm>
+       <primary>read-only transaction</primary>
+       <secondary>setting default</secondary>
+      </indexterm>
+      <indexterm>
+       <primary><varname>transaction_read_only</varname> configuration parameter</primary>
+      </indexterm>
+      </term>
+      <listitem>
+       <para>
+        This parameter reflects the current transaction's read-only status.
+        At the beginning of each transaction, it is set to the current value
+        of <xref linkend="guc-default-transaction-read-only"/>.
+        Any subsequent attempt to change it is equivalent to a <xref
+        linkend="sql-set-transaction"/> command.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="guc-transaction-deferrable" xreflabel="transaction_deferrable">
+      <term><varname>transaction_deferrable</varname> (<type>boolean</type>)
+      <indexterm>
+       <primary>deferrable transaction</primary>
+       <secondary>setting default</secondary>
+      </indexterm>
+      <indexterm>
+       <primary><varname>transaction_deferrable</varname> configuration parameter</primary>
+      </indexterm>
+      </term>
+      <listitem>
+       <para>
+        This parameter reflects the current transaction's deferrability status.
+        At the beginning of each transaction, it is set to the current value
+        of <xref linkend="guc-default-transaction-deferrable"/>.
+        Any subsequent attempt to change it is equivalent to a <xref
+        linkend="sql-set-transaction"/> command.
+       </para>
+      </listitem>
+     </varlistentry>
+
 
      <varlistentry id="guc-session-replication-role" xreflabel="session_replication_role">
       <term><varname>session_replication_role</varname> (<type>enum</type>)
@@ -8741,7 +8803,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
       </term>
       <listitem>
        <para>
-        Specifies the maximum age (in transactions) that a table's
+        Specifies the maximum age (in multixacts) that a table's
         <structname>pg_class</structname>.<structfield>relminmxid</structfield>
         field can attain before <command>VACUUM</command> takes
         extraordinary measures to avoid system-wide multixact ID
@@ -10913,7 +10975,7 @@ LOG:  CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
         <productname>PostgreSQL</productname> will automatically remove
         temporary files after a backend crash. If disabled, the files will be
         retained and may be used for debugging, for example. Repeated crashes
-        may however result in accumulation of useless files. This parameter 
+        may however result in accumulation of useless files. This parameter
         can only be set in the <filename>postgresql.conf</filename> file or on
         the server command line.
        </para>

doc/src/sgml/fdwhandler.sgml

@@ -461,7 +461,7 @@ AddForeignUpdateTargets(PlannerInfo *root,
      <structfield>vartype</structfield> = <type>RECORD</type>,
      and <literal>wholerow<replaceable>N</replaceable></literal>
      for a whole-row <structname>Var</structname> with
-     <structfield>vartype</structfield> equal to the table's declared rowtype.
+     <structfield>vartype</structfield> equal to the table's declared row type.
      Re-use these names when you can (the planner will combine duplicate
      requests for identical junk columns).  If you need another kind of
      junk column besides these, it might be wise to choose a name prefixed

doc/src/sgml/func.sgml

@@ -988,16 +988,23 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
         <returnvalue>double precision</returnvalue>
        </para>
        <para>
-        Exponentiation (unlike typical mathematical practice, multiple uses of
-        <literal>^</literal> will associate left to right)
+        Exponentiation
        </para>
        <para>
         <literal>2 ^ 3</literal>
         <returnvalue>8</returnvalue>
        </para>
+       <para>
+        Unlike typical mathematical practice, multiple uses of
+        <literal>^</literal> will associate left to right by default:
+       </para>
        <para>
         <literal>2 ^ 3 ^ 3</literal>
         <returnvalue>512</returnvalue>
+       </para>
+       <para>
+        <literal>2 ^ (3 ^ 3)</literal>
+        <returnvalue>134217728</returnvalue>
        </para></entry>
       </row>
 
@@ -19181,6 +19188,29 @@ SELECT NULLIF(value, '(none)') ...
         <returnvalue>{[1,2)}</returnvalue>
        </para></entry>
       </row>
+
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>unnest</primary>
+         <secondary>for multirange</secondary>
+        </indexterm>
+        <function>unnest</function> ( <type>anymultirange</type> )
+        <returnvalue>setof anyrange</returnvalue>
+       </para>
+       <para>
+        Expands a multirange into a set of ranges.
+        The ranges are read out in storage order (ascending).
+       </para>
+       <para>
+        <literal>unnest('{[1,2), [3,4)}'::int4multirange)</literal>
+        <returnvalue></returnvalue>
+<programlisting>
+ [1,2)
+ [3,4)
+</programlisting>
+       </para></entry>
+      </row>
      </tbody>
     </tgroup>
    </table>
@@ -24954,8 +24984,8 @@ SELECT collation for ('foo' COLLATE "de_DE");
         sending a <systemitem>SIGHUP</systemitem> signal to the postmaster
         process, which in turn sends <systemitem>SIGHUP</systemitem> to each
         of its children.) You can use the
-        <link linkend="view-pg-file-settings">pg_file_settings</link> and
-        <link linkend="view-pg-hba-file-rules">pg_hba_file_rules</link> views
+        <link linkend="view-pg-file-settings"><structname>pg_file_settings</structname></link> and
+        <link linkend="view-pg-hba-file-rules"><structname>pg_hba_file_rules</structname></link> views
         to check the configuration files for possible errors, before reloading.
        </para></entry>
       </row>
@@ -26563,6 +26593,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
         be <literal>pg_catalog</literal>, but that is not a requirement; the
         collations could be installed into some other schema as well.  The
         function returns the number of new collation objects it created.
+        Use of this function is restricted to superusers.
        </para></entry>
       </row>
      </tbody>

doc/src/sgml/gist.sgml

@@ -374,8 +374,8 @@ my_consistent(PG_FUNCTION_ARGS)
       <para>
        Depending on which operators you have included in the class, the data
        type of <varname>query</varname> could vary with the operator, since it will
-       be whatever type is on the righthand side of the operator, which might
-       be different from the indexed data type appearing on the lefthand side.
+       be whatever type is on the right-hand side of the operator, which might
+       be different from the indexed data type appearing on the left-hand side.
        (The above code skeleton assumes that only one type is possible; if
        not, fetching the <varname>query</varname> argument value would have to depend
        on the operator.)  It is recommended that the SQL declaration of

doc/src/sgml/indexam.sgml

@@ -310,7 +310,7 @@ aminsert (Relation indexRelation,
   </para>
 
   <para>
-   The <literal>indexUnchanged</literal> boolean value gives a hint
+   The <literal>indexUnchanged</literal> Boolean value gives a hint
    about the nature of the tuple to be indexed.  When it is true,
    the tuple is a duplicate of some existing tuple in the index.  The
    new tuple is a logically unchanged successor MVCC tuple version.  This
@@ -493,7 +493,7 @@ amproperty (Oid index_oid, int attno,
    code, it's better to inspect <parameter>prop</parameter>.
    If the <structfield>amproperty</structfield> method returns <literal>true</literal> then
    it has determined the property test result: it must set <literal>*res</literal>
-   to the boolean value to return, or set <literal>*isnull</literal>
+   to the Boolean value to return, or set <literal>*isnull</literal>
    to <literal>true</literal> to return a NULL.  (Both of the referenced variables
    are initialized to <literal>false</literal> before the call.)
    If the <structfield>amproperty</structfield> method returns <literal>false</literal> then

doc/src/sgml/installation.sgml

@@ -354,31 +354,36 @@ su - postgres
   <title>Getting the Source</title>
 
   <para>
-   The <productname>PostgreSQL</productname> &version; sources can be obtained from the
-   download section of our
-   website: <ulink url="https://www.postgresql.org/download/"></ulink>.  You
-   should get a file named <filename>postgresql-&version;.tar.gz</filename>
-   or <filename>postgresql-&version;.tar.bz2</filename>. After
-   you have obtained the file, unpack it:
+   The version control repository for <productname>PostgreSQL</productname>
+   can be obtained from
+   <ulink url="https://git.postgresql.org/gitweb/?p=postgresql.git;a=summary"></ulink>;
+   this is the recommended way to obtain the
+   <productname>PostgreSQL</productname> source code.
+   You can obtain a clone of the repository by running
 <screen>
-<userinput>gunzip postgresql-&version;.tar.gz</userinput>
-<userinput>tar xf postgresql-&version;.tar</userinput>
+<userinput>git clone https://git.postgresql.org/git/postgresql.git</userinput>
 </screen>
-   (Use <command>bunzip2</command> instead of <command>gunzip</command> if
-   you have the <filename>.bz2</filename> file.  Also, note that most
-   modern versions of <command>tar</command> can unpack compressed archives
-   directly, so you don't really need the
-   separate <command>gunzip</command> or <command>bunzip2</command> step.)
-   This will create a directory
-   <filename>postgresql-&version;</filename> under the current directory
-   with the <productname>PostgreSQL</productname> sources.
-   Change into that directory for the rest
-   of the installation procedure.
+   This will create a directory <filename>postgresql</filename> under the current
+   directory with the <productname>PostgreSQL</productname> sources.
+   Change into that directory for the rest of the installation procedure.
+   See <xref linkend="git"/> for further information.
   </para>
 
   <para>
-   You can also get the source directly from the version control repository, see
-   <xref linkend="sourcerepo"/>.
+   Alternatively, source code for the released versions can be obtained
+   from the download section of our website:
+   <ulink url="https://www.postgresql.org/ftp/source/"></ulink>.
+   Download then
+   <filename>postgresql-<replaceable>version</replaceable>.tar.gz</filename>
+   or <filename>postgresql-<replaceable>version</replaceable>.tar.bz2</filename>
+   you're interested in, then unpack it:
+<screen>
+<userinput>tar xf postgresql-<replaceable>version</replaceable>.tar.bz2</userinput>
+</screen>
+   This will create a directory
+   <filename>postgresql-<replaceable>version</replaceable></filename> under
+   the current directory with the <productname>PostgreSQL</productname> sources.
+   Change into that directory for the rest of the installation procedure.
   </para>
  </sect1>
 

doc/src/sgml/json.sgml

@@ -617,7 +617,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu
   <para>
    <command>UPDATE</command> statements may use subscripting in the
    <literal>SET</literal> clause to modify <type>jsonb</type> values. Subscript
-   paths must be traversible for all affected values insofar as they exist. For
+   paths must be traversable for all affected values insofar as they exist. For
    instance, the path <literal>val['a']['b']['c']</literal> can be traversed all
    the way to <literal>c</literal> if every <literal>val</literal>,
    <literal>val['a']</literal>, and <literal>val['a']['b']</literal> is an

doc/src/sgml/libpq.sgml

@@ -1719,7 +1719,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
         There is no environment variable equivalent to this option, and no
         facility for looking it up in <filename>.pgpass</filename>. It can be
         used in a service file connection definition. Users with
-        more sophisticated uses should consider using openssl engines and
+        more sophisticated uses should consider using <productname>OpenSSL</productname> engines and
         tools like PKCS#11 or USB crypto offload devices.
        </para>
       </listitem>
@@ -5032,7 +5032,7 @@ int PQflush(PGconn *conn);
   <para>
    While the pipeline API was introduced in
    <productname>PostgreSQL</productname> 14, it is a client-side feature
-   which doesn't require special server support, and works on any server
+   which doesn't require special server support and works on any server
    that supports the v3 extended query protocol.
   </para>
 
@@ -5451,8 +5451,8 @@ int PQsendFlushRequest(PGconn *conn);
     are being performed in rapid succession.  There is usually less benefit
     in using pipelined commands when each query takes many multiples of the client/server
     round-trip time to execute.  A 100-statement operation run on a server
-    300ms round-trip-time away would take 30 seconds in network latency alone
-    without pipelining; with pipelining it may spend as little as 0.3s waiting for
+    300 ms round-trip-time away would take 30 seconds in network latency alone
+    without pipelining; with pipelining it may spend as little as 0.3 s waiting for
     results from the server.
    </para>
 
@@ -7109,9 +7109,9 @@ defaultNoticeProcessor(void *arg, const char *message)
   <para>
    Each registered event handler is associated with two pieces of data,
    known to <application>libpq</application> only as opaque <literal>void *</literal>
-   pointers.  There is a <firstterm>passthrough</firstterm> pointer that is provided
+   pointers.  There is a <firstterm>pass-through</firstterm> pointer that is provided
    by the application when the event handler is registered with a
-   <structname>PGconn</structname>.  The passthrough pointer never changes for the
+   <structname>PGconn</structname>.  The pass-through pointer never changes for the
    life of the <structname>PGconn</structname> and all <structname>PGresult</structname>s
    generated from it; so if used, it must point to long-lived data.
    In addition there is an <firstterm>instance data</firstterm> pointer, which starts
@@ -7121,9 +7121,9 @@ defaultNoticeProcessor(void *arg, const char *message)
    <xref linkend="libpq-PQsetInstanceData"/>,
    <xref linkend="libpq-PQresultInstanceData"/> and
    <function>PQsetResultInstanceData</function> functions.  Note that
-   unlike the passthrough pointer, instance data of a <structname>PGconn</structname>
+   unlike the pass-through pointer, instance data of a <structname>PGconn</structname>
    is not automatically inherited by <structname>PGresult</structname>s created from
-   it.  <application>libpq</application> does not know what passthrough
+   it.  <application>libpq</application> does not know what pass-through
    and instance data pointers point to (if anything) and will never attempt
    to free them &mdash; that is the responsibility of the event handler.
   </para>

doc/src/sgml/logicaldecoding.sgml

@@ -1251,7 +1251,7 @@ stream_commit_cb(...);  <-- commit of the streamed transaction
     Similar to spill-to-disk behavior, streaming is triggered when the total
     amount of changes decoded from the WAL (for all in-progress transactions)
     exceeds the limit defined by <varname>logical_decoding_work_mem</varname> setting.
-    At that point, the largest toplevel transaction (measured by the amount of memory
+    At that point, the largest top-level transaction (measured by the amount of memory
     currently used for decoded changes) is selected and streamed.  However, in
     some cases we still have to spill to disk even if streaming is enabled
     because we exceed the memory threshold but still have not decoded the