Horton

v1-0001-doc-clarify-and-complete-ALTER-TABLE-syntax-in-re.patch

application/octet-stream

Download
Filename: v1-0001-doc-clarify-and-complete-ALTER-TABLE-syntax-in-re.patch
Type: application/octet-stream
Part: 0
Message: DOC: fixes multiple errors in alter table doc

Patch

Same data as JSON: GET /api/v1/attachments/:id/patch the parsed metadata as JSON — format, series position, per-file stats; never the diff bytes. API reference →
Format: format-patch
Series: patch v1-0001
Subject: doc: clarify and complete ALTER TABLE syntax in reference
File+−
doc/src/sgml/ref/alter_table.sgml 26 15 
From ac2dea06882535671165e38aaa384171396fbe88 Mon Sep 17 00:00:00 2001
From: "Chao Li (Evan)" <lic@highgo.com>
Date: Thu, 18 Dec 2025 15:18:22 +0800
Subject: [PATCH v1] doc: clarify and complete ALTER TABLE syntax in reference
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The ALTER TABLE syntax synopsis and command descriptions were incomplete
and inconsistent with the actual grammar.

Update the syntax summary to list missing ALTER TABLE variants, including
column-level sequence operations, rename actions, schema changes, and
partition management commands. Adjust individual command descriptions
to consistently show the full ALTER [ COLUMN ] column_name … forms,
matching the grammar and improving readability.

This is a documentation-only change; no behavior is altered.

Author: Chao Li <lic@highgo.com>
---
 doc/src/sgml/ref/alter_table.sgml | 41 ++++++++++++++++++++-----------
 1 file changed, 26 insertions(+), 15 deletions(-)

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 9abd8037f28..c329cb201de 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -57,6 +57,8 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable>
     ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> ADD GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( <replaceable>sequence_options</replaceable> ) ]
     ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> { SET GENERATED { ALWAYS | BY DEFAULT } | SET <replaceable>sequence_option</replaceable> | RESTART [ [ WITH ] <replaceable class="parameter">restart</replaceable> ] } [...]
     ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> DROP IDENTITY [ IF EXISTS ]
+    ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> SET <replaceable>sequence_option</replaceable>
+    ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> RESTART
     ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> SET STATISTICS { <replaceable class="parameter">integer</replaceable> | DEFAULT }
     ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> SET ( <replaceable class="parameter">attribute_option</replaceable> = <replaceable class="parameter">value</replaceable> [, ... ] )
     ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> RESET ( <replaceable class="parameter">attribute_option</replaceable> [, ... ] )
@@ -94,6 +96,15 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable>
     NOT OF
     OWNER TO { <replaceable class="parameter">new_owner</replaceable> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
     REPLICA IDENTITY { DEFAULT | USING INDEX <replaceable class="parameter">index_name</replaceable> | FULL | NOTHING }
+    RENAME TO <replaceable class="parameter">new_table_name</replaceable>
+    RENAME COLUMN <replaceable class="parameter">old_column_name</replaceable> TO <replaceable class="parameter">new_column_name</replaceable>
+    RENAME CONSTRAINT <replaceable class="parameter">old_constraint_name</replaceable> TO <replaceable class="parameter">new_constraint_name</replaceable>
+    RENAME INDEX <replaceable class="parameter">old_index_name</replaceable> TO <replaceable class="parameter">new_index_name</replaceable>
+    SET SCHEMA <replaceable class="parameter">new_schema_name</replaceable>
+    ATTACH PARTITION <replaceable class="parameter">partition_name</replaceable> { FOR VALUES <replaceable>partition_bound_spec</replaceable> | DEFAULT }
+    DETACH PARTITION <replaceable class="parameter">partition_name</replaceable> [ CONCURRENTLY | FINALIZE ]
+    MERGE PARTITIONS (<replaceable class="parameter">partition_name1</replaceable>, <replaceable class="parameter">partition_name2</replaceable> [, ...]) INTO <replaceable class="parameter">partition_name</replaceable>
+    SPLIT PARTITION <replaceable class="parameter">partition_name</replaceable> INTO ( PARTITION <replaceable class="parameter">partition_name1</replaceable> { FOR VALUES <replaceable>partition_bound_spec</replaceable> | DEFAULT }, PARTITION <replaceable class="parameter">partition_name2</replaceable> { FOR VALUES <replaceable>partition_bound_spec</replaceable> | DEFAULT } [, ...])
 
 <phrase>and <replaceable class="parameter">partition_bound_spec</replaceable> is:</phrase>
 
@@ -163,7 +174,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
 
   <variablelist>
    <varlistentry id="sql-altertable-desc-add-column">
-    <term><literal>ADD COLUMN [ IF NOT EXISTS ]</literal></term>
+    <term><literal>ADD [ COLUMN ] [ IF NOT EXISTS ]</literal></term>
     <listitem>
      <para>
       This form adds a new column to the table, using the same syntax as
@@ -175,7 +186,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
    </varlistentry>
 
    <varlistentry id="sql-altertable-desc-drop-column">
-    <term><literal>DROP COLUMN [ IF EXISTS ]</literal></term>
+    <term><literal>DROP [ COLUMN ] [ IF EXISTS ]</literal></term>
     <listitem>
      <para>
       This form drops a column from a table.  Indexes and
@@ -194,7 +205,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
    </varlistentry>
 
    <varlistentry id="sql-altertable-desc-set-data-type">
-    <term><literal>SET DATA TYPE</literal></term>
+    <term><literal>ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> [ SET DATA ] TYPE</literal></term>
     <listitem>
      <para>
       This form changes the type of a column of a table. Indexes and
@@ -223,7 +234,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
    </varlistentry>
 
    <varlistentry id="sql-altertable-desc-set-drop-default">
-    <term><literal>SET</literal>/<literal>DROP DEFAULT</literal></term>
+    <term><literal>ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> { SET | DROP } DEFAULT</literal></term>
     <listitem>
      <para>
       These forms set or remove the default value for a column (where
@@ -236,7 +247,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
    </varlistentry>
 
    <varlistentry id="sql-altertable-desc-set-drop-not-null">
-    <term><literal>SET</literal>/<literal>DROP NOT NULL</literal></term>
+    <term><literal>ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> { SET | DROP } NOT NULL</literal></term>
     <listitem>
      <para>
       These forms change whether a column is marked to allow null
@@ -272,7 +283,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
    </varlistentry>
 
    <varlistentry id="sql-altertable-desc-set-expression">
-    <term><literal>SET EXPRESSION AS</literal></term>
+    <term><literal>ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> SET EXPRESSION AS</literal></term>
     <listitem>
      <para>
       This form replaces the expression of a generated column.  Existing data
@@ -292,7 +303,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
    </varlistentry>
 
    <varlistentry id="sql-altertable-desc-drop-expression">
-    <term><literal>DROP EXPRESSION [ IF EXISTS ]</literal></term>
+    <term><literal>ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> DROP EXPRESSION [ IF EXISTS ]</literal></term>
     <listitem>
      <para>
       This form turns a stored generated column into a normal base column.
@@ -314,9 +325,9 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
    </varlistentry>
 
    <varlistentry id="sql-altertable-desc-generated-identity">
-    <term><literal>ADD GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY</literal></term>
-    <term><literal>SET GENERATED { ALWAYS | BY DEFAULT }</literal></term>
-    <term><literal>DROP IDENTITY [ IF EXISTS ]</literal></term>
+    <term><literal>ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> ADD GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY</literal></term>
+    <term><literal>ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> SET GENERATED { ALWAYS | BY DEFAULT }</literal></term>
+    <term><literal>ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> DROP IDENTITY [ IF EXISTS ]</literal></term>
     <listitem>
      <para>
       These forms change whether a column is an identity column or change the
@@ -350,7 +361,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
    </varlistentry>
 
    <varlistentry id="sql-altertable-desc-set-statistics">
-    <term><literal>SET STATISTICS</literal></term>
+    <term><literal>ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> SET STATISTICS</literal></term>
     <listitem>
      <para>
       This form
@@ -373,8 +384,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
    </varlistentry>
 
    <varlistentry id="sql-altertable-desc-set-attribute-option">
-    <term><literal>SET ( <replaceable class="parameter">attribute_option</replaceable> = <replaceable class="parameter">value</replaceable> [, ... ] )</literal></term>
-    <term><literal>RESET ( <replaceable class="parameter">attribute_option</replaceable> [, ... ] )</literal></term>
+    <term><literal>ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> SET ( <replaceable class="parameter">attribute_option</replaceable> = <replaceable class="parameter">value</replaceable> [, ... ] )</literal></term>
+    <term><literal>ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> RESET ( <replaceable class="parameter">attribute_option</replaceable> [, ... ] )</literal></term>
     <listitem>
      <para>
       This form sets or resets per-attribute options.  Currently, the only
@@ -408,7 +419,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
 
    <varlistentry id="sql-altertable-desc-set-storage">
     <term>
-     <literal>SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT }</literal>
+     <literal>ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT }</literal>
      <indexterm>
       <primary>TOAST</primary>
       <secondary>per-column storage settings</secondary>
@@ -442,7 +453,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
 
    <varlistentry id="sql-altertable-desc-set-compression">
     <term>
-     <literal>SET COMPRESSION <replaceable class="parameter">compression_method</replaceable></literal>
+     <literal>ALTER [ COLUMN ] <replaceable class="parameter">column_name</replaceable> SET COMPRESSION <replaceable class="parameter">compression_method</replaceable></literal>
     </term>
     <listitem>
      <para>
-- 
2.39.5 (Apple Git-154)