public inbox for [email protected]
help / color / mirror / Atom feedFrom: Chao Li <[email protected]>
To: Postgres hackers <[email protected]>
Subject: DOC: fixes multiple errors in alter table doc
Date: Thu, 18 Dec 2025 15:22:09 +0800
Message-ID: <CAEoWx2n6ShLMOnjOtf63TjjgGbgiTVT5OMsSOFmbjGb6Xue1Bw@mail.gmail.com> (raw)
Hi Hacker,
While working on a patch these days, my eyes are on the “alter table” doc,
and found multiple errors:
1. Several sub-commands are missed in the top “action” list:
* ALTER COLUMN SET <sequence-option>
* ALTER COLUMN RESTART
* RENAME
* SET SCHEMA
* ATTACH PARTITION
* DETACH PARTITION
* MERGE PARTITION
* SPLIT PARTITION
2. In sub-command details section, "ADD COLUMN [ IF NOT EXISTS ]” missed
“[]" with “COLUMN”, which is misleading, because “COLUMN” is actually
optional.
3. For all “alter column” sub-commands, "ALTER [ COLUMN ]” are omitted,
which is also confusing, because none of other sub-commands omit their
prefix part.
This patch fixed all these issue.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
Attachments:
[application/octet-stream] v1-0001-doc-clarify-and-complete-ALTER-TABLE-syntax-in-re.patch (10.9K, ../CAEoWx2n6ShLMOnjOtf63TjjgGbgiTVT5OMsSOFmbjGb6Xue1Bw@mail.gmail.com/3-v1-0001-doc-clarify-and-complete-ALTER-TABLE-syntax-in-re.patch)
download | inline diff:
From ac2dea06882535671165e38aaa384171396fbe88 Mon Sep 17 00:00:00 2001
From: "Chao Li (Evan)" <[email protected]>
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 <[email protected]>
---
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)
view thread (9+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected]
Subject: Re: DOC: fixes multiple errors in alter table doc
In-Reply-To: <CAEoWx2n6ShLMOnjOtf63TjjgGbgiTVT5OMsSOFmbjGb6Xue1Bw@mail.gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox