DOC: fixes multiple errors in alter table doc
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:
v1-0001-doc-clarify-and-complete-ALTER-TABLE-syntax-in-re.patchapplication/octet-stream; name=v1-0001-doc-clarify-and-complete-ALTER-TABLE-syntax-in-re.patchDownload
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)
On Dec 18, 2025, at 15:22, Chao Li <li.evan.chao@gmail.com> wrote:
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 PARTITION2. 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.
<v1-0001-doc-clarify-and-complete-ALTER-TABLE-syntax-in-re.patch>
CF entry created: https://commitfest.postgresql.org/patch/6328/
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
On Thu, Dec 18, 2025 at 2:22 AM Chao Li <li.evan.chao@gmail.com> wrote:
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
I believe these are covered by the line above them:
ALTER [ COLUMN ] column_name { SET GENERATED { ALWAYS | BY DEFAULT
} | SET sequence_option | RESTART [ [ WITH ] restart ] } [...]
* RENAME
This is covered by the 4th line
ALTER TABLE [ IF EXISTS ] name
RENAME TO new_name
* SET SCHEMA
5th option...
ALTER TABLE [ IF EXISTS ] name
SET SCHEMA new_schema
* ATTACH PARTITION
* DETACH PARTITION
* MERGE PARTITION
* SPLIT PARTITION
And the above are the 7,8,9,10th options at the top.
2. In sub-command details section, "ADD COLUMN [ IF NOT EXISTS ]” missed “[]" with “COLUMN”, which is misleading, because “COLUMN” is actually optional.
Seems technically correct and potentially useful, and I see you
handled this for the DROP COLUMN variant as well, so I could see a +1
on this one.
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.
Hmm... I'm curious what you find confusing about this. Is the
confusion in trying to find or understand the information presented,
or confusing as to why it isn't all documented the same way? The
downside of your "fix" is that this introduces a lot of extra text
that is more or less noise, especially for folks trying to skim the
documents looking for very specific command references. And while I
agree that we aren't 100% consistent on this within the ALTER TABLE
subcommands, we use this same mixed pattern of omission on other pages
(see ALTER TYPE for instance). If we were to insist on making this
consistent here, I think we'd probably need to look at other pages as
well and evaluate or update them too. I'm not sure that would be an
improvement though.
Robert Treat
https://xzilla.net
On Jan 2, 2026, at 10:54, Robert Treat <rob@xzilla.net> wrote:
Hi Robert,
Thanks you very much for your review.
On Thu, Dec 18, 2025 at 2:22 AM Chao Li <li.evan.chao@gmail.com> wrote:
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
I believe these are covered by the line above them:
ALTER [ COLUMN ] column_name { SET GENERATED { ALWAYS | BY DEFAULT
} | SET sequence_option | RESTART [ [ WITH ] restart ] } [...]
* RENAME
This is covered by the 4th line
ALTER TABLE [ IF EXISTS ] name
RENAME TO new_name
* SET SCHEMA
5th option...
ALTER TABLE [ IF EXISTS ] name
SET SCHEMA new_schema
* ATTACH PARTITION
* DETACH PARTITION
* MERGE PARTITION
* SPLIT PARTITION
And the above are the 7,8,9,10th options at the top.
That’s true. I reverted all above changes.
2. In sub-command details section, "ADD COLUMN [ IF NOT EXISTS ]” missed
“[]" with “COLUMN”, which is misleading, because “COLUMN” is actually
optional.
Seems technically correct and potentially useful, and I see you
handled this for the DROP COLUMN variant as well, so I could see a +1
on this one.
Thanks for confirming.
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.
Hmm... I'm curious what you find confusing about this. Is the
confusion in trying to find or understand the information presented,
or confusing as to why it isn't all documented the same way? The
downside of your "fix" is that this introduces a lot of extra text
that is more or less noise, especially for folks trying to skim the
documents looking for very specific command references. And while I
agree that we aren't 100% consistent on this within the ALTER TABLE
subcommands, we use this same mixed pattern of omission on other pages
(see ALTER TYPE for instance). If we were to insist on making this
consistent here, I think we'd probably need to look at other pages as
well and evaluate or update them too. I'm not sure that would be an
improvement though.
The confusion came from my own first-time reading of the documentation.
Since the page is quite long, when I was reading the action descriptions
and wanted to confirm the exact sub-command syntax, I often had to scroll
back up to the syntax section. That led me to think it might be helpful to
include the full sub-command form directly with the action descriptions.
That said, I understand your concern. The change did make the text longer
and added noise. In v2, I’ve therefore reverted that broader change. As you
pointed out, if we were to pursue this kind of consistency, it would need
to be handled across other similar pages as well, which would be better
done as a dedicated and more carefully scoped patch.
So, v2’s scope is significantly reduced, only a fix for my original point 2
is retained.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
Attachments:
v2-0001-docs-reflect-optional-COLUMN-keyword-in-ALTER-TAB.patchapplication/octet-stream; name=v2-0001-docs-reflect-optional-COLUMN-keyword-in-ALTER-TAB.patchDownload
From 16b38fd753af4654ff6399938f6dcc11dbfb625d 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 v2] docs: reflect optional COLUMN keyword in ALTER TABLE
descriptions
The ALTER TABLE description entries for ADD COLUMN and DROP COLUMN
omitted the fact that the COLUMN keyword is optional. Adjust the
command summaries to match the documented syntax by marking COLUMN
as optional.
This is a documentation-only change; no behavior is altered.
Author: Chao Li <lic@highgo.com>
---
doc/src/sgml/ref/alter_table.sgml | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 1bd479c917a..d69e5de8451 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -163,7 +163,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 +175,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
--
2.39.5 (Apple Git-154)
On Sat, Jan 3, 2026 at 11:30 PM Chao Li <li.evan.chao@gmail.com> wrote:
On Jan 2, 2026, at 10:54, Robert Treat <rob@xzilla.net> wrote:
Hi Robert,Thanks you very much for your review.
On Thu, Dec 18, 2025 at 2:22 AM Chao Li <li.evan.chao@gmail.com> wrote:
Hi Hacker,
<snip>
2. In sub-command details section, "ADD COLUMN [ IF NOT EXISTS ]” missed “[]" with “COLUMN”, which is misleading, because “COLUMN” is actually optional.
Seems technically correct and potentially useful, and I see you
handled this for the DROP COLUMN variant as well, so I could see a +1
on this one.Thanks for confirming.
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.
Hmm... I'm curious what you find confusing about this. Is the
confusion in trying to find or understand the information presented,
or confusing as to why it isn't all documented the same way? The
downside of your "fix" is that this introduces a lot of extra text
that is more or less noise, especially for folks trying to skim the
documents looking for very specific command references. And while I
agree that we aren't 100% consistent on this within the ALTER TABLE
subcommands, we use this same mixed pattern of omission on other pages
(see ALTER TYPE for instance). If we were to insist on making this
consistent here, I think we'd probably need to look at other pages as
well and evaluate or update them too. I'm not sure that would be an
improvement though.The confusion came from my own first-time reading of the documentation. Since the page is quite long, when I was reading the action descriptions and wanted to confirm the exact sub-command syntax, I often had to scroll back up to the syntax section. That led me to think it might be helpful to include the full sub-command form directly with the action descriptions.
That said, I understand your concern. The change did make the text longer and added noise. In v2, I’ve therefore reverted that broader change. As you pointed out, if we were to pursue this kind of consistency, it would need to be handled across other similar pages as well, which would be better done as a dedicated and more carefully scoped patch.
So, v2’s scope is significantly reduced, only a fix for my original point 2 is retained.
Makes sense to me and seems like an improvement, so +1.
Robert Treat
https://xzilla.net
On Jan 8, 2026, at 07:13, Robert Treat <rob@xzilla.net> wrote:
On Sat, Jan 3, 2026 at 11:30 PM Chao Li <li.evan.chao@gmail.com> wrote:
On Jan 2, 2026, at 10:54, Robert Treat <rob@xzilla.net> wrote:
Hi Robert,Thanks you very much for your review.
On Thu, Dec 18, 2025 at 2:22 AM Chao Li <li.evan.chao@gmail.com> wrote:
Hi Hacker,<snip>
2. In sub-command details section, "ADD COLUMN [ IF NOT EXISTS ]” missed “[]" with “COLUMN”, which is misleading, because “COLUMN” is actually optional.
Seems technically correct and potentially useful, and I see you
handled this for the DROP COLUMN variant as well, so I could see a +1
on this one.Thanks for confirming.
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.
Hmm... I'm curious what you find confusing about this. Is the
confusion in trying to find or understand the information presented,
or confusing as to why it isn't all documented the same way? The
downside of your "fix" is that this introduces a lot of extra text
that is more or less noise, especially for folks trying to skim the
documents looking for very specific command references. And while I
agree that we aren't 100% consistent on this within the ALTER TABLE
subcommands, we use this same mixed pattern of omission on other pages
(see ALTER TYPE for instance). If we were to insist on making this
consistent here, I think we'd probably need to look at other pages as
well and evaluate or update them too. I'm not sure that would be an
improvement though.The confusion came from my own first-time reading of the documentation. Since the page is quite long, when I was reading the action descriptions and wanted to confirm the exact sub-command syntax, I often had to scroll back up to the syntax section. That led me to think it might be helpful to include the full sub-command form directly with the action descriptions.
That said, I understand your concern. The change did make the text longer and added noise. In v2, I’ve therefore reverted that broader change. As you pointed out, if we were to pursue this kind of consistency, it would need to be handled across other similar pages as well, which would be better done as a dedicated and more carefully scoped patch.
So, v2’s scope is significantly reduced, only a fix for my original point 2 is retained.
Makes sense to me and seems like an improvement, so +1.
Hi Robert,
Thank you very much for your review. This is the CF entry https://commitfest.postgresql.org/patch/6328/, you may add you as a reviewer. And I just changed the status to Ready for Committer.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/