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
>From 48fff177a8f0096c99c77b4e1368cc73f7e86585 Mon Sep 17 00:00:00 2001 From: Nathan Bossart <nboss...@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
>From 4d53b9e7379931361ca680d9d79bd55c083deb53 Mon Sep 17 00:00:00 2001 From: Nathan Bossart <nboss...@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
