Subject: Re: DOC: fixes multiple errors in alter table doc

From: Robert Treat <[email-masked]>
Date: Thu, 1 Jan 2026 21:54:06 -0500

On Thu, Dec 18, 2025 at 2:22 AM Chao Li <[email-masked]> 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

---

From: Chao Li <[email-masked]>
Date: Sun, 4 Jan 2026 12:30:36 +0800

On Jan 2, 2026, at 10:54, Robert Treat <[email-masked]> wrote:

Hi Robert,

Thanks you very much for your review.

Hi Hacker,

While working on a patch these days, my eyes are on the “alter table” doc,
and found multiple errors:

  * RENAME

  * SET SCHEMA

5th option...

  * ATTACH PARTITION
  * DETACH PARTITION
  * MERGE PARTITION
  * SPLIT PARTITION

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.

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.

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/

---

From: Robert Treat <[email-masked]>
Date: Wed, 7 Jan 2026 18:13:33 -0500

> On Thu, Dec 18, 2025 at 2:22 AM Chao Li <[email-masked]> wrote:
<snip>
> 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

---

From: Chao Li <[email-masked]>
Date: Thu, 8 Jan 2026 09:38:48 +0800

> On Jan 8, 2026, at 07:13, Robert Treat <[email-masked]> wrote:
> 

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,

---

From: Chao Li <[email-masked]>
Date: Thu, 22 Jan 2026 17:32:38 +0800

> On Jan 8, 2026, at 09:38, Chao Li <[email-masked]> wrote:
> 
> 
> 

Bump. This is a tiny doc fix.

Best regards,