Re: [doc] remove reference to pg_dump pre-8.1 switch behaviour - Mailing list pgsql-hackers

On Sun, Nov 29, 2020 at 01:27:48PM -0600, Justin Pryzby wrote:
>          activity of scans already in progress.  This can result in
>          unpredictable changes in the row ordering returned by queries that
>          have no <literal>ORDER BY</literal> clause.  Setting this parameter to
> -        <literal>off</literal> ensures the pre-8.3 behavior in which a sequential
> +        <literal>off</literal> ensures the simple behavior in which a sequential
>          scan always starts from the beginning of the table.  The default
>          is <literal>on</literal>.

Mentioned upthread, but I see no problems in keeping this reference
either.

>     (last subscript varies most rapidly).
>     If the contents of two arrays are equal but the dimensionality is
>     different, the first difference in the dimensionality information
> -   determines the sort order.  (This is a change from versions of
> -   <productname>PostgreSQL</productname> prior to 8.2: older versions would claim
> -   that two arrays with the same contents were equal, even if the
> -   number of dimensions or subscript ranges were different.)
> +   determines the sort order.
>    </para>

OK to remove this one.  That was +1'd three times upthread.  I guess
that it just got missed.

>       <replaceable class="parameter">mode</replaceable> is unused and
> -     ignored as of <productname>PostgreSQL</productname> 8.1; however, for
> +     ignored since <productname>PostgreSQL</productname> 8.1; however, for
>       backward compatibility with earlier releases it is best to
>       set it to <symbol>INV_READ</symbol>, <symbol>INV_WRITE</symbol>,
>       or <symbol>INV_READ</symbol> <literal>|</literal> <symbol>INV_WRITE</symbol>

Don't see a point in changing that.  I don't agree with just removing
the parameter either as that may just break stuff.

>      Data of a particular data type might be transmitted in any of several
> -    different <firstterm>formats</firstterm>.  As of <productname>PostgreSQL</productname> 7.4
> +    different <firstterm>formats</firstterm>.  Currently
>      the only supported formats are <quote>text</quote> and <quote>binary</quote>,
>      but the protocol makes provision for future extensions.  The desired
>      format for any value is specified by a <firstterm>format code</firstterm>.

Don't think there was an agreement on that.

> -  <para>
> -   The syntax
> -<synopsis>
> -CLUSTER <replaceable class="parameter">index_name</replaceable> ON <replaceable
class="parameter">table_name</replaceable>
> -</synopsis>
> -  is also supported for compatibility with pre-8.3 <productname>PostgreSQL</productname>
> -  versions.
> -  </para>
>   </refsect1>
>
>   <refsect1>

Seems to me that this should be kept for now.

> -     Before <productname>PostgreSQL</productname> 8.3, these functions would
> -     silently accept values of several non-string data types as well, due to
> -     the presence of implicit coercions from those data types to
> -     <type>text</type>.  Those coercions have been removed because they frequently
> -     caused surprising behaviors.  However, the string concatenation operator
> -     (<literal>||</literal>) still accepts non-string input, so long as at least one
> -     input is of a string type, as shown in <xref
> -     linkend="functions-string-sql"/>.  For other cases, insert an explicit
> -     coercion to <type>text</type> if you need to duplicate the previous behavior.
> +     The string concatenation operator (<literal>||</literal>) will accept
> +     non-string input, so long as at least one input is of string type, as shown
> +     in <xref linkend="functions-string-sql"/>.  For other cases, inserting an
> +     explicit coercion to <type>text</type> can be used to have non-string input
> +     accepted.
>      </para>
>     </note>

Word-by-word what Stephen has written upthread.  Agreed that this is
an improvement.

> +     Building a <acronym>GIN</acronym> index after all of the data has been
> +     loaded will typically be faster than creating the index and then filling
> +     it.  There may also be cases where, for a sufficiently large update,
> +     dropping the <acronym>GIN</acronym> index, then performing the update,
> +     and then recreating the index will be faster than a routine update,
> +     however, one should review the delayed indexing technique used for
> +     <acronym>GIN</acronym> (see <xref linkend="gin-fast-update"/> for
> +     details) and the options it provides.

We are losing some context with this formulation, particularly for the
case of the insertion of multiple keys.  So I think that it is better
to just remove the Postgres 8.4 bit, and keep the second paragraph
mostly as-is.

> - <para>
> -  As of <productname>PostgreSQL</productname> 9.1, null key values can be
> -  included in the index.  Also, placeholder nulls are included in the index
> -  for indexed items that are null or contain no keys according to
> -  <function>extractValue</function>.  This allows searches that should find empty
> -  items to do so.
> - </para>

Let's keep that, as agreed upthread.

>   <para>
>    Multicolumn <acronym>GIN</acronym> indexes are implemented by building
>    a single B-tree over composite values (column number, key value).  The
> @@ -507,7 +499,7 @@
>     Updating a <acronym>GIN</acronym> index tends to be slow because of the
>     intrinsic nature of inverted indexes: inserting or updating one heap row
>     can cause many inserts into the index (one for each key extracted
> -   from the indexed item). As of <productname>PostgreSQL</productname> 8.4,
> +   from the indexed item).
>     <acronym>GIN</acronym> is capable of postponing much of this work by inserting
>     new tuples into a temporary, unsorted list of pending entries.
>     When the table is vacuumed or autoanalyzed, or when

Agreed to remove this reference to 8.4.

> -   this operation while the server is running. Note that in PostgreSQL 9.1
> -   and earlier you will also need to update the <structname>pg_tablespace</structname>
> -   catalog with the new locations. (If you do not, <literal>pg_dump</literal> will
> -   continue to output the old tablespace locations.)
> +   this operation while the server is running.
>    </para>

I think that this should be kept.  pg_dump is supported with 9.1.

> -  <para>
> -   Previous releases failed to preserve a lock which is upgraded by a later
> -   savepoint.  For example, this code:
> -<programlisting>
> -BEGIN;
> -SELECT * FROM mytable WHERE key = 1 FOR UPDATE;
> -SAVEPOINT s;
> -UPDATE mytable SET ... WHERE key = 1;
> -ROLLBACK TO s;
> -</programlisting>
> -   would fail to preserve the <literal>FOR UPDATE</literal> lock after the
> -   <command>ROLLBACK TO</command>.  This has been fixed in release 9.3.
> -  </para>

Feels a bit early to remove IMO.

> -   <para>
> -    Note that if a <literal>FROM</literal> clause is not specified,
> -    the query cannot reference any database tables. For example, the
> -    following query is invalid:
> -<programlisting>
> -SELECT distributors.* WHERE distributors.name = 'Westward';
> -</programlisting><productname>PostgreSQL</productname> releases prior to
> -    8.1 would accept queries of this form, and add an implicit entry
> -    to the query's <literal>FROM</literal> clause for each table
> -    referenced by the query. This is no longer allowed.
> -   </para>
>    </refsect2>

OK to remove the whole paragraph here.

> -     <para>
> -      The ability to use names to reference SQL function arguments was added
> -      in <productname>PostgreSQL</productname> 9.2.  Functions to be used in
> -      older servers must use the <literal>$<replaceable>n</replaceable></literal> notation.
> -     </para>
> -    </note>
>     </sect2>

I think that's too early to remove.

So this comes down to 5 items, as per the attached.  Thoughts?
--
Michael