From: Michael Paquier <michael@paquier.xyz>
To: Justin Pryzby <pryzby@telsasoft.com>
Cc: Heikki Linnakangas <hlinnaka@iki.fi>
Cc: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Stephen Frost <sfrost@snowman.net>
Cc: Ian Lawrence Barwick <barwick@gmail.com>
Cc: pgsql-hackers <pgsql-hackers@postgresql.org>
Subject: Re: [doc] remove reference to pg_dump pre-8.1 switch behaviour
Date: Mon, 30 Nov 2020 15:58:18 +0900
Message-ID: <X8SYCnbcLTXUQrc7@paquier.xyz> (raw)
In-Reply-To: <20201129192748.GP24052@telsasoft.com>
References: <CAB8KJ=h-XALik4M7gv-pX48=+SPWexfaYwa+yTnPwD3DxceXrg@mail.gmail.com>
<e4934710-73cb-6eef-fd35-6fcfd05f381b@iki.fi>
<20201023134611.GG16415@tamriel.snowman.net>
<145522.1603461363@sss.pgh.pa.us>
<20201023141211.GH16415@tamriel.snowman.net>
<147812.1603464663@sss.pgh.pa.us>
<fd93f1c5-7818-a02c-01e5-1075ac0d4def@iki.fi>
<20201025215650.GN9241@telsasoft.com>
<ca583d26-6bcf-6081-dc72-f1fcf867e974@iki.fi>
<20201129192748.GP24052@telsasoft.com>
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
Attachments:doc-past-refs.patch (text/x-diff, 4.0K) downloaddiff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgmlindex 507bc1a668..1ea88a8c67 100644--- a/doc/src/sgml/func.sgml+++ b/doc/src/sgml/func.sgml@@ -2309,15 +2309,11 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<note>
<para>
- 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>
@@ -17368,10 +17364,7 @@ SELECT NULLIF(value, '(none)') ...
(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>
<table id="array-operators-table">
diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgmlindex 67754f52f6..691a73b9c9 100644--- a/doc/src/sgml/gin.sgml+++ b/doc/src/sgml/gin.sgml@@ -507,7 +507,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
@@ -576,10 +576,10 @@
</para>
<para>
- As of <productname>PostgreSQL</productname> 8.4, this advice is less- necessary since delayed indexing is used (see <xref- linkend="gin-fast-update"/> for details). But for very large updates- it may still be best to drop and recreate the index.+ Note that the delayed indexing technique used for <acronym>GIN</acronym>+ (see <xref linkend="gin-fast-update"/> for details) makes this advice+ less necessary, but for very large updates it may still be best to+ drop and recreate the index.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgmlindex 472b7cae81..6757033e09 100644--- a/doc/src/sgml/ref/select.sgml+++ b/doc/src/sgml/ref/select.sgml@@ -1934,18 +1934,6 @@ SELECT 2+2;
by introducing a dummy one-row table from which to do the
<command>SELECT</command>.
</para>
-- <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>
<refsect2>
signature.asc (application/pgp-signature, 832B) download
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: michael@paquier.xyz, pryzby@telsasoft.com, hlinnaka@iki.fi, tgl@sss.pgh.pa.us, sfrost@snowman.net, barwick@gmail.com
Subject: Re: [doc] remove reference to pg_dump pre-8.1 switch behaviour
In-Reply-To: <X8SYCnbcLTXUQrc7@paquier.xyz>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox