Support syntax "CLUSTER table USING index", which is more logical.

Holger Schurig

doc/src/sgml/ref/cluster.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.40 2007/02/01 00:28:18 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/cluster.sgml,v 1.41 2007/04/08 00:26:33 momjian Exp $
 PostgreSQL documentation
 -->
 
@@ -20,8 +20,7 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-CLUSTER <replaceable class="PARAMETER">indexname</replaceable> ON <replaceable class="PARAMETER">tablename</replaceable>
-CLUSTER <replaceable class="PARAMETER">tablename</replaceable>
+CLUSTER <replaceable class="PARAMETER">tablename</replaceable> [ USING <replaceable class="PARAMETER">indexname</replaceable> ]
 CLUSTER
 </synopsis>
  </refsynopsisdiv>
@@ -77,19 +76,19 @@ CLUSTER
 
   <variablelist>
    <varlistentry>
-    <term><replaceable class="PARAMETER">indexname</replaceable></term>
+    <term><replaceable class="PARAMETER">tablename</replaceable></term>
     <listitem>
      <para>
-      The name of an index.
+      The name (possibly schema-qualified) of a table.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-    <term><replaceable class="PARAMETER">tablename</replaceable></term>
+    <term><replaceable class="PARAMETER">indexname</replaceable></term>
     <listitem>
      <para>
-      The name (possibly schema-qualified) of a table.
+      The name of an index.
      </para>
     </listitem>
    </varlistentry>
@@ -172,9 +171,9 @@ CREATE TABLE <replaceable class="parameter">newtable</replaceable> AS
 
   <para>
    Cluster the table <literal>employees</literal> on the basis of
-   its index <literal>emp_ind</literal>:
+   its index <literal>employees_ind</literal>:
 <programlisting>
-CLUSTER emp_ind ON emp;
+CLUSTER employees USING employees_ind;
 </programlisting>
   </para>
 
@@ -182,7 +181,7 @@ CLUSTER emp_ind ON emp;
    Cluster the <literal>employees</literal> table using the same
    index that was used before:
 <programlisting>
-CLUSTER emp;
+CLUSTER employees;
 </programlisting>
   </para>
 
@@ -198,7 +197,12 @@ CLUSTER;
   <title>Compatibility</title>
 
   <para>
-   There is no <command>CLUSTER</command> statement in the SQL standard.
+   The syntax:
+<synopsis>
+CLUSTER <replaceable class="PARAMETER">indexname</replaceable> ON <replaceable class="PARAMETER">tablename</replaceable>
+</synopsis>
+  is also supported for compatibility with pre-8.3 <productname>PostgreSQL</> installations.
+  There is no <command>CLUSTER</command> statement in the SQL standard.
   </para>
  </refsect1>
 

src/backend/parser/gram.y

@@ -11,7 +11,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/backend/parser/gram.y,v 2.586 2007/04/02 22:20:53 momjian Exp $
+ *	  $PostgreSQL: pgsql/src/backend/parser/gram.y,v 2.587 2007/04/08 00:26:34 momjian Exp $
  *
  * HISTORY
  *	  AUTHOR			DATE			MAJOR EVENT
@@ -209,7 +209,7 @@ static Node *makeXmlExpr(XmlExprOp op, char *name, List *named_args, List *args)
 
 %type <str>		relation_name copy_file_name
 				database_name access_method_clause access_method attr_name
-				index_name name file_name
+				index_name name file_name cluster_index_specification
 
 %type <list>	func_name handler_name qual_Op qual_all_Op subquery_Op
 				opt_class opt_validator
@@ -5084,7 +5084,7 @@ opt_check_option:
 /*****************************************************************************
  *
  *		QUERY:
- *				load "filename"
+ *				LOAD "filename"
  *
  *****************************************************************************/
 
@@ -5346,25 +5346,18 @@ CreateConversionStmt:
 /*****************************************************************************
  *
  *		QUERY:
- *				cluster <index_name> on <qualified_name>
- *				cluster <qualified_name>
- *				cluster
+ *				CLUSTER <qualified_name> [ USING <index_name> ]
+ *				CLUSTER
+ *				CLUSTER <index_name> ON <qualified_name> (for pre-8.3)
  *
  *****************************************************************************/
 
 ClusterStmt:
-			CLUSTER index_name ON qualified_name
-				{
-				   ClusterStmt *n = makeNode(ClusterStmt);
-				   n->relation = $4;
-				   n->indexname = $2;
-				   $$ = (Node*)n;
-				}
-			| CLUSTER qualified_name
+			CLUSTER qualified_name cluster_index_specification
 				{
 			       ClusterStmt *n = makeNode(ClusterStmt);
 				   n->relation = $2;
-				   n->indexname = NULL;
+				   n->indexname = $3;
 				   $$ = (Node*)n;
 				}
 			| CLUSTER
@@ -5374,13 +5367,27 @@ ClusterStmt:
 				   n->indexname = NULL;
 				   $$ = (Node*)n;
 				}
+			/* kept for pre-8.3 compatibility */
+			| CLUSTER index_name ON qualified_name
+				{
+				   ClusterStmt *n = makeNode(ClusterStmt);
+				   n->relation = $4;
+				   n->indexname = $2;
+				   $$ = (Node*)n;
+				}
+		;
+
+cluster_index_specification:
+			USING index_name		{ $$ = $2; }
+			| /*EMPTY*/				{ $$ = NULL; }
 		;
 
+
 /*****************************************************************************
  *
  *		QUERY:
- *				vacuum
- *				analyze
+ *				VACUUM
+ *				ANALYZE
  *
  *****************************************************************************/
 

src/bin/psql/tab-complete.c

@@ -3,7 +3,7 @@
  *
  * Copyright (c) 2000-2007, PostgreSQL Global Development Group
  *
- * $PostgreSQL: pgsql/src/bin/psql/tab-complete.c,v 1.160 2007/03/26 16:58:40 tgl Exp $
+ * $PostgreSQL: pgsql/src/bin/psql/tab-complete.c,v 1.161 2007/04/08 00:26:34 momjian Exp $
  */
 
 /*----------------------------------------------------------------------
@@ -822,11 +822,9 @@ psql_completion(char *text, int start, int end)
 
 		COMPLETE_WITH_LIST(list_COLUMNALTER);
 	}
-	else if (pg_strcasecmp(prev3_wd, "TABLE") == 0 &&
-			 pg_strcasecmp(prev_wd, "CLUSTER") == 0)
+	else if (pg_strcasecmp(prev3_wd, "TABLE") == 0)
 		COMPLETE_WITH_CONST("ON");
 	else if (pg_strcasecmp(prev4_wd, "TABLE") == 0 &&
-			 pg_strcasecmp(prev2_wd, "CLUSTER") == 0 &&
 			 pg_strcasecmp(prev_wd, "ON") == 0)
 	{
 		completion_info_charp = prev3_wd;
@@ -929,24 +927,25 @@ psql_completion(char *text, int start, int end)
 
 	/*
 	 * If the previous word is CLUSTER and not without produce list of
-	 * indexes.
+	 * tables
 	 */
 	else if (pg_strcasecmp(prev_wd, "CLUSTER") == 0 &&
 			 pg_strcasecmp(prev2_wd, "WITHOUT") != 0)
-		COMPLETE_WITH_SCHEMA_QUERY(Query_for_list_of_indexes, NULL);
-	/* If we have CLUSTER <sth>, then add "ON" */
+		COMPLETE_WITH_SCHEMA_QUERY(Query_for_list_of_tables, NULL);
+	/* If we have CLUSTER <sth>, then add "USING" */
 	else if (pg_strcasecmp(prev2_wd, "CLUSTER") == 0 &&
-			 pg_strcasecmp(prev_wd, "ON") != 0)
-		COMPLETE_WITH_CONST("ON");
+			 pg_strcasecmp(prev_wd, "ON") != 0) {
+		COMPLETE_WITH_CONST("USING");
+	}
 
 	/*
-	 * If we have CLUSTER <sth> ON, then add the correct tablename as well.
+	 * If we have CLUSTER <sth> ORDER BY, then add the index as well.
 	 */
 	else if (pg_strcasecmp(prev3_wd, "CLUSTER") == 0 &&
-			 pg_strcasecmp(prev_wd, "ON") == 0)
+			 pg_strcasecmp(prev_wd, "USING") == 0)
 	{
 		completion_info_charp = prev2_wd;
-		COMPLETE_WITH_QUERY(Query_for_table_owning_index);
+		COMPLETE_WITH_QUERY(Query_for_index_of_table);
 	}
 
 /* COMMENT */

src/test/regress/expected/cluster.out

@@ -329,7 +329,7 @@ INSERT INTO clstr_3 VALUES (1);
 CLUSTER clstr_2;
 ERROR:  there is no previously clustered index for table "clstr_2"
 CLUSTER clstr_1_pkey ON clstr_1;
-CLUSTER clstr_2_pkey ON clstr_2;
+CLUSTER clstr_2 USING clstr_2_pkey;
 SELECT * FROM clstr_1 UNION ALL
   SELECT * FROM clstr_2 UNION ALL
   SELECT * FROM clstr_3;

src/test/regress/sql/cluster.sql

@@ -122,7 +122,7 @@ INSERT INTO clstr_3 VALUES (1);
 CLUSTER clstr_2;
 
 CLUSTER clstr_1_pkey ON clstr_1;
-CLUSTER clstr_2_pkey ON clstr_2;
+CLUSTER clstr_2 USING clstr_2_pkey;
 SELECT * FROM clstr_1 UNION ALL
   SELECT * FROM clstr_2 UNION ALL
   SELECT * FROM clstr_3;