Move un-parenthesized syntax docs to "compatibility" for few SQL commands
Hi,
I find the inclusion of the un-parenthesized syntax for VACUUM, ANALYZE,
and EXPLAIN in the docs makes it harder to understand the preferred,
parenthesized syntax (see [1]https://www.postgresql.org/docs/devel/sql-analyze.html as an example).
Over in [2]/messages/by-id/3024596.1681940741@sss.pgh.pa.us, it was suggested that moving the un-parenthesized syntax to
the "Compatibility" section of their respective docs pages would be
okay. Patch attached.
I left out CLUSTER since that syntax change is so new.
- Melanie
[1]: https://www.postgresql.org/docs/devel/sql-analyze.html
[2]: /messages/by-id/3024596.1681940741@sss.pgh.pa.us
Attachments:
v1-0001-Doc-Move-un-parenthesized-syntax-to-compatibility.patchtext/x-patch; charset=US-ASCII; name=v1-0001-Doc-Move-un-parenthesized-syntax-to-compatibility.patchDownload
From adef275c702833c6a4441d347ab8303403576fb2 Mon Sep 17 00:00:00 2001
From: Melanie Plageman <melanieplageman@gmail.com>
Date: Fri, 21 Apr 2023 18:11:06 -0400
Subject: [PATCH v1] Doc: Move un-parenthesized syntax to compatibility for few
SQL commands
Move documentation of the un-parenthesized syntax for VACUUM, ANALYZE,
and EXPLAIN to the "Compatibility" section of their documentation to
improve readability of the preferred, parenthesized syntax.
Discussion: https://postgr.es/m/3024596.1681940741%40sss.pgh.pa.us
---
doc/src/sgml/ref/analyze.sgml | 9 ++++++++-
doc/src/sgml/ref/explain.sgml | 9 ++++++++-
doc/src/sgml/ref/vacuum.sgml | 9 ++++++++-
3 files changed, 24 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index 20c6f9939f..08d6902276 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -22,7 +22,6 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
-ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
@@ -346,6 +345,14 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
<para>
There is no <command>ANALYZE</command> statement in the SQL standard.
</para>
+
+ <para>
+ The following syntax was used before <productname>PostgreSQL</productname>
+ version 11.0 and is still supported:
+ <synopsis>
+ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
+ </synopsis>
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml
index 410490951b..748bbf1eeb 100644
--- a/doc/src/sgml/ref/explain.sgml
+++ b/doc/src/sgml/ref/explain.sgml
@@ -32,7 +32,6 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
EXPLAIN [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] <replaceable class="parameter">statement</replaceable>
-EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replaceable>
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
@@ -529,6 +528,14 @@ EXPLAIN (GENERIC_PLAN)
<para>
There is no <command>EXPLAIN</command> statement defined in the SQL standard.
</para>
+
+ <para>
+ The following syntax was used before <productname>PostgreSQL</productname>
+ version 9.0 and is still supported:
+ <synopsis>
+ EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replaceable>
+ </synopsis>
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 57bc4c23ec..5dc43d480d 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -22,7 +22,6 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
-VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
@@ -532,6 +531,14 @@ VACUUM (VERBOSE, ANALYZE) onek;
<para>
There is no <command>VACUUM</command> statement in the SQL standard.
</para>
+
+ <para>
+ The following syntax was used before <productname>PostgreSQL</productname>
+ version 9.0 and is still supported:
+ <synopsis>
+ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
+ </synopsis>
+ </para>
</refsect1>
<refsect1>
--
2.37.2
On Fri, Apr 21, 2023 at 06:29:16PM -0400, Melanie Plageman wrote:
Over in [2], it was suggested that moving the un-parenthesized syntax to
the "Compatibility" section of their respective docs pages would be
okay. Patch attached.
I think that's reasonable.
I left out CLUSTER since that syntax change is so new.
I think it'd be okay to move this one, too. The parenthesized syntax has
been available since v14, and I suspect CLUSTER isn't terribly widely used,
anyway. (Side note: it looks like "CLUSTER (VERBOSE)" doesn't work, which
seems weird to me.)
Most of these commands have an existing note about the deprecated syntax.
Could those be removed with this change?
--
Nathan Bossart
Amazon Web Services: https://aws.amazon.com
On Fri, Apr 21, 2023 at 6:55 PM Nathan Bossart <nathandbossart@gmail.com> wrote:
On Fri, Apr 21, 2023 at 06:29:16PM -0400, Melanie Plageman wrote:
Over in [2], it was suggested that moving the un-parenthesized syntax to
the "Compatibility" section of their respective docs pages would be
okay. Patch attached.I think that's reasonable.
I left out CLUSTER since that syntax change is so new.
I think it'd be okay to move this one, too. The parenthesized syntax has
been available since v14, and I suspect CLUSTER isn't terribly widely used,
anyway. (Side note: it looks like "CLUSTER (VERBOSE)" doesn't work, which
seems weird to me.)
Attached v2 includes changes for CLUSTER syntax docs. I wasn't quite
sure that we can move down CLUSTER [VERBOSE] syntax to the compatibility
section since CLUSTER (VERBOSE) doesn't work. This seems like it should
work (VACUUM and ANALYZE do). I put extra "[ ]" around the main CLUSTER
syntax but I don't know that this is actually the same as documenting
that CLUSTER VERBOSE does work but CLUSTER (VERBOSE) doesn't.
Most of these commands have an existing note about the deprecated syntax.
Could those be removed with this change?
Ah, yes. Good catch! I have removed these.
- Melanie
Attachments:
v2-0001-Doc-Move-un-parenthesized-syntax-to-compatibility.patchtext/x-patch; charset=US-ASCII; name=v2-0001-Doc-Move-un-parenthesized-syntax-to-compatibility.patchDownload
From 3fd4631c160f8c0b2817d9b3704ff80939cacea5 Mon Sep 17 00:00:00 2001
From: Melanie Plageman <melanieplageman@gmail.com>
Date: Fri, 21 Apr 2023 18:11:06 -0400
Subject: [PATCH v2] Doc: Move un-parenthesized syntax to compatibility for few
SQL commands
Move documentation of the un-parenthesized syntax for VACUUM, ANALYZE,
EXPLAIN, and CLUSTER to the "Compatibility" section of their
documentation to improve readability of the preferred, parenthesized
syntax.
Discussion: https://postgr.es/m/flat/CAAKRu_bc5uHieG1976kGqJKxyWtyQt9yvktjsVX%2Bi7NOigDjOA%40mail.gmail.com
---
doc/src/sgml/ref/analyze.sgml | 16 ++++++++--------
doc/src/sgml/ref/cluster.sgml | 25 ++++++++++++++++---------
doc/src/sgml/ref/explain.sgml | 17 ++++++++---------
doc/src/sgml/ref/vacuum.sgml | 18 ++++++++----------
4 files changed, 40 insertions(+), 36 deletions(-)
diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index 20c6f9939f..a3cde13b9a 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -22,7 +22,6 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
-ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
@@ -56,13 +55,6 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
It is further possible to give a list of column names for a table,
in which case only the statistics for those columns are collected.
</para>
-
- <para>
- When the option list is surrounded by parentheses, the options can be
- written in any order. The parenthesized syntax was added in
- <productname>PostgreSQL</productname> 11; the unparenthesized syntax
- is deprecated.
- </para>
</refsect1>
<refsect1>
@@ -346,6 +338,14 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
<para>
There is no <command>ANALYZE</command> statement in the SQL standard.
</para>
+
+ <para>
+ The following syntax was used before <productname>PostgreSQL</productname>
+ version 11.0 and is still supported:
+ <synopsis>
+ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
+ </synopsis>
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index 29f0f1fd90..5bbe1ae2f5 100644
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -21,9 +21,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
-CLUSTER [VERBOSE] <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ]
-CLUSTER ( <replaceable class="parameter">option</replaceable> [, ...] ) <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ]
-CLUSTER [VERBOSE]
+CLUSTER [ ( <replaceable class="parameter">option</replaceable> [, ...] ) <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
@@ -252,12 +250,21 @@ CLUSTER;
</para>
<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.
+ The following syntaxes are supported for compatibility:
+ </para>
+
+ <para>
+ Compatible with pre-8.3 <productname>PostgreSQL</productname> versions:
+ <synopsis>
+ CLUSTER <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table_name</replaceable>
+ </synopsis>
+
+ Compatible with pre-14 <productname>PostgreSQL</productname> versions:
+ <synopsis>
+ CLUSTER [VERBOSE] <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ]
+ CLUSTER [VERBOSE]
+ </synopsis>
+
</para>
</refsect1>
diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml
index 410490951b..96f5cadc6b 100644
--- a/doc/src/sgml/ref/explain.sgml
+++ b/doc/src/sgml/ref/explain.sgml
@@ -32,7 +32,6 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
EXPLAIN [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] <replaceable class="parameter">statement</replaceable>
-EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replaceable>
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
@@ -106,14 +105,6 @@ ROLLBACK;
</programlisting>
</para>
</important>
-
- <para>
- Only the <literal>ANALYZE</literal> and <literal>VERBOSE</literal> options
- can be specified, and only in that order, without surrounding the option
- list in parentheses. Prior to <productname>PostgreSQL</productname> 9.0,
- the unparenthesized syntax was the only one supported. It is expected that
- all new options will be supported only in the parenthesized syntax.
- </para>
</refsect1>
<refsect1>
@@ -529,6 +520,14 @@ EXPLAIN (GENERIC_PLAN)
<para>
There is no <command>EXPLAIN</command> statement defined in the SQL standard.
</para>
+
+ <para>
+ The following syntax was used before <productname>PostgreSQL</productname>
+ version 9.0 and is still supported:
+ <synopsis>
+ EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replaceable>
+ </synopsis>
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 57bc4c23ec..19a12cdeb0 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -22,7 +22,6 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
-VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
@@ -90,15 +89,6 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet
much slower and requires an <literal>ACCESS EXCLUSIVE</literal> lock on
each table while it is being processed.
</para>
-
- <para>
- When the option list is surrounded by parentheses, the options can be
- written in any order. Without parentheses, options must be specified
- in exactly the order shown above.
- The parenthesized syntax was added in
- <productname>PostgreSQL</productname> 9.0; the unparenthesized
- syntax is deprecated.
- </para>
</refsect1>
<refsect1>
@@ -532,6 +522,14 @@ VACUUM (VERBOSE, ANALYZE) onek;
<para>
There is no <command>VACUUM</command> statement in the SQL standard.
</para>
+
+ <para>
+ The following syntax was used before <productname>PostgreSQL</productname>
+ version 9.0 and is still supported:
+ <synopsis>
+ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
+ </synopsis>
+ </para>
</refsect1>
<refsect1>
--
2.37.2
On Fri, Apr 21, 2023 at 07:29:59PM -0400, Melanie Plageman wrote:
Attached v2 includes changes for CLUSTER syntax docs. I wasn't quite
sure that we can move down CLUSTER [VERBOSE] syntax to the compatibility
section since CLUSTER (VERBOSE) doesn't work. This seems like it should
work (VACUUM and ANALYZE do). I put extra "[ ]" around the main CLUSTER
syntax but I don't know that this is actually the same as documenting
that CLUSTER VERBOSE does work but CLUSTER (VERBOSE) doesn't.
AFAICT there isn't a strong reason to disallow CLUSTER (VERBOSE). The
following short patch seems to do the trick:
diff --git a/src/backend/parser/gram.y b/src/backend/parser/gram.y
index acf6cf4866..215c4ba39c 100644
--- a/src/backend/parser/gram.y
+++ b/src/backend/parser/gram.y
@@ -11603,6 +11603,15 @@ ClusterStmt:
n->params = $3;
$$ = (Node *) n;
}
+ | CLUSTER '(' utility_option_list ')'
+ {
+ ClusterStmt *n = makeNode(ClusterStmt);
+
+ n->relation = NULL;
+ n->indexname = NULL;
+ n->params = $3;
+ $$ = (Node *) n;
+ }
| CLUSTER opt_verbose
{
ClusterStmt *n = makeNode(ClusterStmt);Most of these commands have an existing note about the deprecated syntax.
Could those be removed with this change?Ah, yes. Good catch! I have removed these.
Thanks. I'll take a closer look at the patch soon.
--
Nathan Bossart
Amazon Web Services: https://aws.amazon.com
I've attached two patches. 0001 adds a parenthesized CLUSTER syntax that
doesn't require a table name. 0002 is your patch with a couple of small
adjustments.
On Fri, Apr 21, 2023 at 07:29:59PM -0400, Melanie Plageman wrote:
Attached v2 includes changes for CLUSTER syntax docs. I wasn't quite
sure that we can move down CLUSTER [VERBOSE] syntax to the compatibility
section since CLUSTER (VERBOSE) doesn't work. This seems like it should
work (VACUUM and ANALYZE do). I put extra "[ ]" around the main CLUSTER
syntax but I don't know that this is actually the same as documenting
that CLUSTER VERBOSE does work but CLUSTER (VERBOSE) doesn't.
I'm not sure about moving CLUSTER [VERBOSE] to the compatibility section,
either. At the very least, I don't think what I have in 0002 is accurate.
It claims that syntax was used before v14, but it's still the only way to
do a "verbose" CLUSTER without a table name in v15 and v16, too. Perhaps
we should break it apart, or maybe we can just say it was used before v17.
WDYT?
--
Nathan Bossart
Amazon Web Services: https://aws.amazon.com
Attachments:
v3-0001-Support-parenthesized-syntax-for-CLUSTER-without-.patchtext/x-diff; charset=us-asciiDownload
From 48fff177a8f0096c99c77b4e1368cc73f7e86585 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nbossart@postgresql.org>
Date: Fri, 21 Apr 2023 20:16:25 -0700
Subject: [PATCH v3 1/2] Support parenthesized syntax for CLUSTER without a
table name.
b5913f6 added a parenthesized syntax for CLUSTER, but it requires
specifying a table name. This is unlike commands such as VACUUM
and ANALYZE, which do not require specifying a table in the
parenthesized syntax. This change resolves this inconsistency.
The documentation for the CLUSTER syntax has also been consolidated
in anticipation of a follow-up change that will move the
unparenthesized syntax to the "Compatibility" section.
Author: Nathan Bossart
Reviewed-by: ???
Discussion: https://postgr.es/m/CAAKRu_bc5uHieG1976kGqJKxyWtyQt9yvktjsVX%2Bi7NOigDjOA%40mail.gmail.com
---
doc/src/sgml/ref/cluster.sgml | 5 ++---
src/backend/parser/gram.y | 21 ++++++++++++++-------
2 files changed, 16 insertions(+), 10 deletions(-)
diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index 29f0f1fd90..0776d01e60 100644
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -21,9 +21,8 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
-CLUSTER [VERBOSE] <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ]
-CLUSTER ( <replaceable class="parameter">option</replaceable> [, ...] ) <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ]
-CLUSTER [VERBOSE]
+CLUSTER [VERBOSE] [ <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
+CLUSTER [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
diff --git a/src/backend/parser/gram.y b/src/backend/parser/gram.y
index acf6cf4866..9a8ffed595 100644
--- a/src/backend/parser/gram.y
+++ b/src/backend/parser/gram.y
@@ -11574,9 +11574,8 @@ CreateConversionStmt:
/*****************************************************************************
*
* QUERY:
- * CLUSTER [VERBOSE] <qualified_name> [ USING <index_name> ]
- * CLUSTER [ (options) ] <qualified_name> [ USING <index_name> ]
- * CLUSTER [VERBOSE]
+ * CLUSTER [VERBOSE] [ <qualified_name> [ USING <index_name> ] ]
+ * CLUSTER [ (options) ] [ <qualified_name> [ USING <index_name> ] ]
* CLUSTER [VERBOSE] <index_name> ON <qualified_name> (for pre-8.3)
*
*****************************************************************************/
@@ -11593,7 +11592,17 @@ ClusterStmt:
n->params = lappend(n->params, makeDefElem("verbose", NULL, @2));
$$ = (Node *) n;
}
+ | CLUSTER opt_verbose
+ {
+ ClusterStmt *n = makeNode(ClusterStmt);
+ n->relation = NULL;
+ n->indexname = NULL;
+ n->params = NIL;
+ if ($2)
+ n->params = lappend(n->params, makeDefElem("verbose", NULL, @2));
+ $$ = (Node *) n;
+ }
| CLUSTER '(' utility_option_list ')' qualified_name cluster_index_specification
{
ClusterStmt *n = makeNode(ClusterStmt);
@@ -11603,15 +11612,13 @@ ClusterStmt:
n->params = $3;
$$ = (Node *) n;
}
- | CLUSTER opt_verbose
+ | CLUSTER '(' utility_option_list ')'
{
ClusterStmt *n = makeNode(ClusterStmt);
n->relation = NULL;
n->indexname = NULL;
- n->params = NIL;
- if ($2)
- n->params = lappend(n->params, makeDefElem("verbose", NULL, @2));
+ n->params = $3;
$$ = (Node *) n;
}
/* kept for pre-8.3 compatibility */
--
2.25.1
v3-0002-Doc-move-unparenthesized-syntax-for-a-few-command.patchtext/x-diff; charset=us-asciiDownload
From 4d53b9e7379931361ca680d9d79bd55c083deb53 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nbossart@postgresql.org>
Date: Fri, 21 Apr 2023 20:39:10 -0700
Subject: [PATCH v3 2/2] Doc: move unparenthesized syntax for a few commands.
Move documentation of the unparenthesized syntax for VACUUM,
ANALYZE, EXPLAIN, and CLUSTER to the "Compatibility" section of
their documentation to improve readability of the preferred,
parenthesized syntax.
Author: Melanie Plageman
Discussion: https://postgr.es/m/CAAKRu_bc5uHieG1976kGqJKxyWtyQt9yvktjsVX%2Bi7NOigDjOA%40mail.gmail.com
---
doc/src/sgml/ref/analyze.sgml | 16 ++++++++--------
doc/src/sgml/ref/cluster.sgml | 14 ++++++++++----
doc/src/sgml/ref/explain.sgml | 19 ++++++++++---------
doc/src/sgml/ref/vacuum.sgml | 20 ++++++++++----------
4 files changed, 38 insertions(+), 31 deletions(-)
diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index 20c6f9939f..ea42ec30bd 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -22,7 +22,6 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
-ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
@@ -56,13 +55,6 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
It is further possible to give a list of column names for a table,
in which case only the statistics for those columns are collected.
</para>
-
- <para>
- When the option list is surrounded by parentheses, the options can be
- written in any order. The parenthesized syntax was added in
- <productname>PostgreSQL</productname> 11; the unparenthesized syntax
- is deprecated.
- </para>
</refsect1>
<refsect1>
@@ -346,6 +338,14 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
<para>
There is no <command>ANALYZE</command> statement in the SQL standard.
</para>
+
+ <para>
+ The following syntax was used before <productname>PostgreSQL</productname>
+ version 11 and is still supported:
+<synopsis>
+ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
+</synopsis>
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index 0776d01e60..230e12abcf 100644
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -21,7 +21,6 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
-CLUSTER [VERBOSE] [ <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
CLUSTER [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
@@ -251,12 +250,19 @@ CLUSTER;
</para>
<para>
- The syntax
+ The following syntax was used before <productname>PostgreSQL</productname>
+ 14 and is still supported:
+<synopsis>
+CLUSTER [VERBOSE] [ <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
+</synopsis>
+ </para>
+
+ <para>
+ The following syntax was used before <productname>PostgreSQL</productname>
+ 8.3 and is still supported:
<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>
diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml
index 410490951b..ae493c86d6 100644
--- a/doc/src/sgml/ref/explain.sgml
+++ b/doc/src/sgml/ref/explain.sgml
@@ -32,7 +32,6 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
EXPLAIN [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] <replaceable class="parameter">statement</replaceable>
-EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replaceable>
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
@@ -106,14 +105,6 @@ ROLLBACK;
</programlisting>
</para>
</important>
-
- <para>
- Only the <literal>ANALYZE</literal> and <literal>VERBOSE</literal> options
- can be specified, and only in that order, without surrounding the option
- list in parentheses. Prior to <productname>PostgreSQL</productname> 9.0,
- the unparenthesized syntax was the only one supported. It is expected that
- all new options will be supported only in the parenthesized syntax.
- </para>
</refsect1>
<refsect1>
@@ -529,6 +520,16 @@ EXPLAIN (GENERIC_PLAN)
<para>
There is no <command>EXPLAIN</command> statement defined in the SQL standard.
</para>
+
+ <para>
+ The following syntax was used before <productname>PostgreSQL</productname>
+ version 9.0 and is still supported:
+<synopsis>
+EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replaceable>
+</synopsis>
+ Note that in this syntax, the options must be specified in exactly the order
+ shown.
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 57bc4c23ec..5dc2a6639c 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -22,7 +22,6 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
-VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
@@ -90,15 +89,6 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet
much slower and requires an <literal>ACCESS EXCLUSIVE</literal> lock on
each table while it is being processed.
</para>
-
- <para>
- When the option list is surrounded by parentheses, the options can be
- written in any order. Without parentheses, options must be specified
- in exactly the order shown above.
- The parenthesized syntax was added in
- <productname>PostgreSQL</productname> 9.0; the unparenthesized
- syntax is deprecated.
- </para>
</refsect1>
<refsect1>
@@ -532,6 +522,16 @@ VACUUM (VERBOSE, ANALYZE) onek;
<para>
There is no <command>VACUUM</command> statement in the SQL standard.
</para>
+
+ <para>
+ The following syntax was used before <productname>PostgreSQL</productname>
+ version 9.0 and is still supported:
+<synopsis>
+VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
+</synopsis>
+ Note that in this syntax, the options must be specified in exactly the order
+ shown.
+ </para>
</refsect1>
<refsect1>
--
2.25.1
On Fri, Apr 21, 2023 at 09:44:51PM -0700, Nathan Bossart wrote:
I've attached two patches. 0001 adds a parenthesized CLUSTER syntax that
doesn't require a table name. 0002 is your patch with a couple of small
adjustments.On Fri, Apr 21, 2023 at 07:29:59PM -0400, Melanie Plageman wrote:
Attached v2 includes changes for CLUSTER syntax docs. I wasn't quite
sure that we can move down CLUSTER [VERBOSE] syntax to the compatibility
section since CLUSTER (VERBOSE) doesn't work. This seems like it should
work (VACUUM and ANALYZE do). I put extra "[ ]" around the main CLUSTER
syntax but I don't know that this is actually the same as documenting
that CLUSTER VERBOSE does work but CLUSTER (VERBOSE) doesn't.I'm not sure about moving CLUSTER [VERBOSE] to the compatibility section,
either. At the very least, I don't think what I have in 0002 is accurate.
It claims that syntax was used before v14, but it's still the only way to
do a "verbose" CLUSTER without a table name in v15 and v16, too. Perhaps
we should break it apart, or maybe we can just say it was used before v17.
WDYT?
If you are planning to wait and commit the change to support CLUSTER
(VERBOSE) until July, then you can consolidate the two and say before
v17. If you plan to commit it before then (making it available in v16),
I would move CLUSTER [VERBOSE] down to Compatibility and say that both
of the un-parenthesized syntaxes were used before v16. Since all of the
syntaxes still work, I think it is probably more confusing to split them
apart so granularly. The parenthesized syntax was effectively not
"feature complete" without your patch to support CLUSTER (VERBOSE).
Also, isn't this:
CLUSTER [VERBOSE] [ <qualified_name> [ USING <index_name> ] ]
inclusive of this:
CLUSTER [VERBOSE]
So, it would have been correct for them to be consolidated in the
existing documentation?
From 48fff177a8f0096c99c77b4e1368cc73f7e86585 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nbossart@postgresql.org>
Date: Fri, 21 Apr 2023 20:16:25 -0700
Subject: [PATCH v3 1/2] Support parenthesized syntax for CLUSTER without a
table name.b5913f6 added a parenthesized syntax for CLUSTER, but it requires
specifying a table name. This is unlike commands such as VACUUM
and ANALYZE, which do not require specifying a table in the
parenthesized syntax. This change resolves this inconsistency.The documentation for the CLUSTER syntax has also been consolidated
in anticipation of a follow-up change that will move the
unparenthesized syntax to the "Compatibility" section.
I suppose we should decide if unparenthesized is a word or if we are
sticking with the hyphen.
doc/src/sgml/ref/cluster.sgml | 5 ++---
src/backend/parser/gram.y | 21 ++++++++++++++-------
2 files changed, 16 insertions(+), 10 deletions(-)--- a/src/backend/parser/gram.y +++ b/src/backend/parser/gram.y
...
@@ -11593,7 +11592,17 @@ ClusterStmt: n->params = lappend(n->params, makeDefElem("verbose", NULL, @2)); $$ = (Node *) n; } + | CLUSTER opt_verbose + { + ClusterStmt *n = makeNode(ClusterStmt);+ n->relation = NULL; + n->indexname = NULL; + n->params = NIL; + if ($2) + n->params = lappend(n->params, makeDefElem("verbose", NULL, @2)); + $$ = (Node *) n; + }
Maybe it is worth moving the un-parenthesized options all to the end and
specifying what version they were needed for.
| CLUSTER '(' utility_option_list ')' qualified_name cluster_index_specification { ClusterStmt *n = makeNode(ClusterStmt); @@ -11603,15 +11612,13 @@ ClusterStmt: n->params = $3; $$ = (Node *) n; } - | CLUSTER opt_verbose + | CLUSTER '(' utility_option_list ')'
It is too bad we can't do this the way VACUUM and ANALYZE do -- but
since qualified_name is required if USING is included, I suppose we
can't.
diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml index 20c6f9939f..ea42ec30bd 100644 --- a/doc/src/sgml/ref/analyze.sgml +++ b/doc/src/sgml/ref/analyze.sgml @@ -22,7 +22,6 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ] -ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
...
@@ -346,6 +338,14 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea <para> There is no <command>ANALYZE</command> statement in the SQL standard. </para> + + <para> + The following syntax was used before <productname>PostgreSQL</productname> + version 11 and is still supported:
Good call on specifying that the order matters.
+<synopsis> +ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ] +</synopsis> + </para>
- Melanie
On Sat, Apr 22, 2023 at 10:38:58AM -0400, Melanie Plageman wrote:
If you are planning to wait and commit the change to support CLUSTER
(VERBOSE) until July, then you can consolidate the two and say before
v17. If you plan to commit it before then (making it available in v16),
I would move CLUSTER [VERBOSE] down to Compatibility and say that both
of the un-parenthesized syntaxes were used before v16. Since all of the
syntaxes still work, I think it is probably more confusing to split them
apart so granularly. The parenthesized syntax was effectively not
"feature complete" without your patch to support CLUSTER (VERBOSE).
I think this can wait for v17, but if there's a strong argument for doing
some of this sooner, we can reevaluate.
Also, isn't this:
CLUSTER [VERBOSE] [ <qualified_name> [ USING <index_name> ] ]
inclusive of this:
CLUSTER [VERBOSE]
So, it would have been correct for them to be consolidated in the
existing documentation?
Yes. This appears to go pretty far back. I traced it to 8bc717c (2002).
It looks like the VACUUM syntaxes have been consolidated since 37d2f76
(1998). So AFAICT this small inconsistency has been around for a while.
The documentation for the CLUSTER syntax has also been consolidated
in anticipation of a follow-up change that will move the
unparenthesized syntax to the "Compatibility" section.I suppose we should decide if unparenthesized is a word or if we are
sticking with the hyphen.
The existing uses in the docs all omit the hypen, but I see it both ways in
some web searches. Other than keeping the Postgres docs consistent, I
don't have a terribly ѕtrong opinion here.
+ | CLUSTER opt_verbose + { + ClusterStmt *n = makeNode(ClusterStmt);+ n->relation = NULL; + n->indexname = NULL; + n->params = NIL; + if ($2) + n->params = lappend(n->params, makeDefElem("verbose", NULL, @2)); + $$ = (Node *) n; + }Maybe it is worth moving the un-parenthesized options all to the end and
specifying what version they were needed for.
Good idea.
| CLUSTER '(' utility_option_list ')' qualified_name cluster_index_specification { ClusterStmt *n = makeNode(ClusterStmt); @@ -11603,15 +11612,13 @@ ClusterStmt: n->params = $3; $$ = (Node *) n; } - | CLUSTER opt_verbose + | CLUSTER '(' utility_option_list ')'It is too bad we can't do this the way VACUUM and ANALYZE do -- but
since qualified_name is required if USING is included, I suppose we
can't.
It might be possible to extract the name and index part to a separate
optional rule.
--
Nathan Bossart
Amazon Web Services: https://aws.amazon.com
On Mon, Apr 24, 2023 at 09:52:21AM -0700, Nathan Bossart wrote:
I think this can wait for v17, but if there's a strong argument for doing
some of this sooner, we can reevaluate.
FWIW, I agree to hold on this stuff for v17~ once it opens for
business. There is no urgency here.
--
Michael
On Tue, Apr 25, 2023 at 03:18:44PM +0900, Michael Paquier wrote:
On Mon, Apr 24, 2023 at 09:52:21AM -0700, Nathan Bossart wrote:
I think this can wait for v17, but if there's a strong argument for doing
some of this sooner, we can reevaluate.FWIW, I agree to hold on this stuff for v17~ once it opens for
business. There is no urgency here.
There's still some time before we'll be able to commit any of these, but
here is an attempt at addressing all the feedback thus far.
--
Nathan Bossart
Amazon Web Services: https://aws.amazon.com
Attachments:
v4-0001-Rearrange-CLUSTER-rules-in-gram.y.patchtext/x-diff; charset=us-asciiDownload
From b27c3f95bb8da5a8e71cfb3a438a998ff9852cf2 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Mon, 15 May 2023 12:02:09 -0700
Subject: [PATCH v4 1/3] Rearrange CLUSTER rules in gram.y.
This change moves the unparenthesized syntaxes for CLUSTER to the
end of the ClusterStmt rules in preparation for a follow-up commit
that will move these syntaxes to the "Compatibility" section of the
CLUSTER documentation. The documentation for the unparenthesized
syntaxes has also been consolidated.
Suggested-by: Melanie Plageman
Discussion https://postgr.es/m/CAAKRu_bc5uHieG1976kGqJKxyWtyQt9yvktjsVX%2Bi7NOigDjOA%40mail.gmail.com
---
doc/src/sgml/ref/cluster.sgml | 3 +--
src/backend/parser/gram.y | 27 +++++++++++++--------------
2 files changed, 14 insertions(+), 16 deletions(-)
diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index 29f0f1fd90..35b8deaec1 100644
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -21,9 +21,8 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
-CLUSTER [VERBOSE] <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ]
CLUSTER ( <replaceable class="parameter">option</replaceable> [, ...] ) <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ]
-CLUSTER [VERBOSE]
+CLUSTER [VERBOSE] [ replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
diff --git a/src/backend/parser/gram.y b/src/backend/parser/gram.y
index d6426f3b8e..a0b741ea72 100644
--- a/src/backend/parser/gram.y
+++ b/src/backend/parser/gram.y
@@ -11574,33 +11574,32 @@ CreateConversionStmt:
/*****************************************************************************
*
* QUERY:
- * CLUSTER [VERBOSE] <qualified_name> [ USING <index_name> ]
- * CLUSTER [ (options) ] <qualified_name> [ USING <index_name> ]
- * CLUSTER [VERBOSE]
+ * CLUSTER (options) <qualified_name> [ USING <index_name> ]
+ * CLUSTER [VERBOSE] [ <qualified_name> [ USING <index_name> ] ]
* CLUSTER [VERBOSE] <index_name> ON <qualified_name> (for pre-8.3)
*
*****************************************************************************/
ClusterStmt:
- CLUSTER opt_verbose qualified_name cluster_index_specification
+ CLUSTER '(' utility_option_list ')' qualified_name cluster_index_specification
{
ClusterStmt *n = makeNode(ClusterStmt);
- n->relation = $3;
- n->indexname = $4;
- n->params = NIL;
- if ($2)
- n->params = lappend(n->params, makeDefElem("verbose", NULL, @2));
+ n->relation = $5;
+ n->indexname = $6;
+ n->params = $3;
$$ = (Node *) n;
}
-
- | CLUSTER '(' utility_option_list ')' qualified_name cluster_index_specification
+ /* unparenthesized VERBOSE kept for pre-14 compatibility */
+ | CLUSTER opt_verbose qualified_name cluster_index_specification
{
ClusterStmt *n = makeNode(ClusterStmt);
- n->relation = $5;
- n->indexname = $6;
- n->params = $3;
+ n->relation = $3;
+ n->indexname = $4;
+ n->params = NIL;
+ if ($2)
+ n->params = lappend(n->params, makeDefElem("verbose", NULL, @2));
$$ = (Node *) n;
}
| CLUSTER opt_verbose
--
2.25.1
v4-0002-Support-parenthesized-syntax-for-CLUSTER-without-.patchtext/x-diff; charset=us-asciiDownload
From 98364f6360a1b48e772c4d1dc878030a7613dfff Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Mon, 15 May 2023 12:13:12 -0700
Subject: [PATCH v4 2/3] Support parenthesized syntax for CLUSTER without a
table name.
b5913f6120 added a parenthesized syntax for CLUSTER, but it
requires specifying a table name. This is unlike commands such as
VACUUM and ANALYZE, which do not require specifying a table in the
parenthesized syntax. This change resolves this inconsistency.
This is preparatory work for a follow-up commit that will move the
unparenthesized syntax to the "Compatibility" section of the
CLUSTER documentation.
Reviewed-by: Melanie Plageman
Discussion: https://postgr.es/m/CAAKRu_bc5uHieG1976kGqJKxyWtyQt9yvktjsVX%2Bi7NOigDjOA%40mail.gmail.com
---
doc/src/sgml/ref/cluster.sgml | 2 +-
src/backend/parser/gram.y | 12 +++++++++++-
2 files changed, 12 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index 35b8deaec1..33aab6a4ab 100644
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -21,7 +21,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
-CLUSTER ( <replaceable class="parameter">option</replaceable> [, ...] ) <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ]
+CLUSTER ( <replaceable class="parameter">option</replaceable> [, ...] ) [ <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
CLUSTER [VERBOSE] [ replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
diff --git a/src/backend/parser/gram.y b/src/backend/parser/gram.y
index a0b741ea72..d41ae1ab0e 100644
--- a/src/backend/parser/gram.y
+++ b/src/backend/parser/gram.y
@@ -11574,7 +11574,7 @@ CreateConversionStmt:
/*****************************************************************************
*
* QUERY:
- * CLUSTER (options) <qualified_name> [ USING <index_name> ]
+ * CLUSTER (options) [ <qualified_name> [ USING <index_name> ] ]
* CLUSTER [VERBOSE] [ <qualified_name> [ USING <index_name> ] ]
* CLUSTER [VERBOSE] <index_name> ON <qualified_name> (for pre-8.3)
*
@@ -11590,6 +11590,15 @@ ClusterStmt:
n->params = $3;
$$ = (Node *) n;
}
+ | CLUSTER '(' utility_option_list ')'
+ {
+ ClusterStmt *n = makeNode(ClusterStmt);
+
+ n->relation = NULL;
+ n->indexname = NULL;
+ n->params = $3;
+ $$ = (Node *) n;
+ }
/* unparenthesized VERBOSE kept for pre-14 compatibility */
| CLUSTER opt_verbose qualified_name cluster_index_specification
{
@@ -11602,6 +11611,7 @@ ClusterStmt:
n->params = lappend(n->params, makeDefElem("verbose", NULL, @2));
$$ = (Node *) n;
}
+ /* unparenthesized VERBOSE kept for pre-17 compatibility */
| CLUSTER opt_verbose
{
ClusterStmt *n = makeNode(ClusterStmt);
--
2.25.1
v4-0003-Doc-move-unparenthesized-syntax-for-a-few-command.patchtext/x-diff; charset=us-asciiDownload
From a73402882f3f635cd9f7ed771dc41e8a2e1e2a7f Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Mon, 15 May 2023 10:45:50 -0700
Subject: [PATCH v4 3/3] Doc: move unparenthesized syntax for a few commands.
Move documentation of the unparenthesized syntax for VACUUM,
ANALYZE, EXPLAIN, and CLUSTER to the "Compatibility" section of
their documentation to improve readability of the preferred,
parenthesized syntax.
Author: Melanie Plageman
Discussion: https://postgr.es/m/CAAKRu_bc5uHieG1976kGqJKxyWtyQt9yvktjsVX%2Bi7NOigDjOA%40mail.gmail.com
---
doc/src/sgml/ref/analyze.sgml | 16 ++++++++--------
doc/src/sgml/ref/cluster.sgml | 16 +++++++++++-----
doc/src/sgml/ref/explain.sgml | 19 ++++++++++---------
doc/src/sgml/ref/vacuum.sgml | 20 ++++++++++----------
4 files changed, 39 insertions(+), 32 deletions(-)
diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index 20c6f9939f..ea42ec30bd 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -22,7 +22,6 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
-ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
@@ -56,13 +55,6 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
It is further possible to give a list of column names for a table,
in which case only the statistics for those columns are collected.
</para>
-
- <para>
- When the option list is surrounded by parentheses, the options can be
- written in any order. The parenthesized syntax was added in
- <productname>PostgreSQL</productname> 11; the unparenthesized syntax
- is deprecated.
- </para>
</refsect1>
<refsect1>
@@ -346,6 +338,14 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
<para>
There is no <command>ANALYZE</command> statement in the SQL standard.
</para>
+
+ <para>
+ The following syntax was used before <productname>PostgreSQL</productname>
+ version 11 and is still supported:
+<synopsis>
+ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
+</synopsis>
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index 33aab6a4ab..c6eb9ef267 100644
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -21,8 +21,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
-CLUSTER ( <replaceable class="parameter">option</replaceable> [, ...] ) [ <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
-CLUSTER [VERBOSE] [ replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
+CLUSTER [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
@@ -251,12 +250,19 @@ CLUSTER;
</para>
<para>
- The syntax
+ The following syntax was used before <productname>PostgreSQL</productname>
+ 17 and is still supported:
+<synopsis>
+CLUSTER [ VERBOSE ] [ <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
+</synopsis>
+ </para>
+
+ <para>
+ The following syntax was used before <productname>PostgreSQL</productname>
+ 8.3 and is still supported:
<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>
diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml
index 410490951b..ae493c86d6 100644
--- a/doc/src/sgml/ref/explain.sgml
+++ b/doc/src/sgml/ref/explain.sgml
@@ -32,7 +32,6 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
EXPLAIN [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] <replaceable class="parameter">statement</replaceable>
-EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replaceable>
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
@@ -106,14 +105,6 @@ ROLLBACK;
</programlisting>
</para>
</important>
-
- <para>
- Only the <literal>ANALYZE</literal> and <literal>VERBOSE</literal> options
- can be specified, and only in that order, without surrounding the option
- list in parentheses. Prior to <productname>PostgreSQL</productname> 9.0,
- the unparenthesized syntax was the only one supported. It is expected that
- all new options will be supported only in the parenthesized syntax.
- </para>
</refsect1>
<refsect1>
@@ -529,6 +520,16 @@ EXPLAIN (GENERIC_PLAN)
<para>
There is no <command>EXPLAIN</command> statement defined in the SQL standard.
</para>
+
+ <para>
+ The following syntax was used before <productname>PostgreSQL</productname>
+ version 9.0 and is still supported:
+<synopsis>
+EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replaceable>
+</synopsis>
+ Note that in this syntax, the options must be specified in exactly the order
+ shown.
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 57bc4c23ec..5dc2a6639c 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -22,7 +22,6 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
-VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
@@ -90,15 +89,6 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet
much slower and requires an <literal>ACCESS EXCLUSIVE</literal> lock on
each table while it is being processed.
</para>
-
- <para>
- When the option list is surrounded by parentheses, the options can be
- written in any order. Without parentheses, options must be specified
- in exactly the order shown above.
- The parenthesized syntax was added in
- <productname>PostgreSQL</productname> 9.0; the unparenthesized
- syntax is deprecated.
- </para>
</refsect1>
<refsect1>
@@ -532,6 +522,16 @@ VACUUM (VERBOSE, ANALYZE) onek;
<para>
There is no <command>VACUUM</command> statement in the SQL standard.
</para>
+
+ <para>
+ The following syntax was used before <productname>PostgreSQL</productname>
+ version 9.0 and is still supported:
+<synopsis>
+VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
+</synopsis>
+ Note that in this syntax, the options must be specified in exactly the order
+ shown.
+ </para>
</refsect1>
<refsect1>
--
2.25.1
On Mon, May 15, 2023 at 12:36:51PM -0700, Nathan Bossart wrote:
There's still some time before we'll be able to commit any of these, but
here is an attempt at addressing all the feedback thus far.
- The parenthesized syntax was added in
- <productname>PostgreSQL</productname> 9.0; the unparenthesized
- syntax is deprecated.
[...]
+ | CLUSTER '(' utility_option_list ')'
+ {
+ ClusterStmt *n = makeNode(ClusterStmt);
+
+ n->relation = NULL;
+ n->indexname = NULL;
+ n->params = $3;
+ $$ = (Node *) n;
+ }Hmm. This is older than the oldest version we have to support for
pg_upgrade and co. Would it be worth switching clusterdb to use the
parenthesized grammar, adding on the way a test for this new grammar
flavor without a table in the TAP tests (too costly for the main
regression test suite)?
--
Michael
On Tue, May 16, 2023 at 03:28:17PM +0900, Michael Paquier wrote:
Hmm. This is older than the oldest version we have to support for
pg_upgrade and co. Would it be worth switching clusterdb to use the
parenthesized grammar, adding on the way a test for this new grammar
flavor without a table in the TAP tests (too costly for the main
regression test suite)?
Since all currently-supported versions require a table name for the
parenthesized syntax, this would cause v17's clusterdb to fail on older
servers when no table name is specified. That seems like a deal-breaker to
me.
--
Nathan Bossart
Amazon Web Services: https://aws.amazon.com
On Mon, May 15, 2023 at 12:36:51PM -0700, Nathan Bossart wrote:
On Tue, Apr 25, 2023 at 03:18:44PM +0900, Michael Paquier wrote:
FWIW, I agree to hold on this stuff for v17~ once it opens for
business. There is no urgency here.There's still some time before we'll be able to commit any of these, but
here is an attempt at addressing all the feedback thus far.
I think these patches are in decent shape, so I'd like to commit them soon,
but I will wait at least a couple more weeks in case anyone has additional
feedback.
--
Nathan Bossart
Amazon Web Services: https://aws.amazon.com
On Fri, Jun 30, 2023 at 11:25:57AM -0700, Nathan Bossart wrote:
I think these patches are in decent shape, so I'd like to commit them soon,
but I will wait at least a couple more weeks in case anyone has additional
feedback.
Committed.
--
Nathan Bossart
Amazon Web Services: https://aws.amazon.com