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
>From b27c3f95bb8da5a8e71cfb3a438a998ff9852cf2 Mon Sep 17 00:00:00 2001 From: Nathan Bossart <nat...@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
>From 98364f6360a1b48e772c4d1dc878030a7613dfff Mon Sep 17 00:00:00 2001 From: Nathan Bossart <nat...@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
>From a73402882f3f635cd9f7ed771dc41e8a2e1e2a7f Mon Sep 17 00:00:00 2001 From: Nathan Bossart <nat...@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
