Re: Move un-parenthesized syntax docs to "compatibility" for few SQL commands

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