public inbox for [email protected]  

help / color / mirror / Atom feed

From: Robert Treat <[email protected]>
To: Chao Li <[email protected]>
Cc: Postgres hackers <[email protected]>
Subject: Re: DOC: fixes multiple errors in alter table doc
Date: Thu, 1 Jan 2026 21:54:06 -0500
Message-ID: <CABV9wwMPmo-dg=oV+NaJGa_==uo5+TTvk58aNtjVQZBtMcRVBw@mail.gmail.com> (raw)
In-Reply-To: <CAEoWx2n6ShLMOnjOtf63TjjgGbgiTVT5OMsSOFmbjGb6Xue1Bw@mail.gmail.com>
References: <CAEoWx2n6ShLMOnjOtf63TjjgGbgiTVT5OMsSOFmbjGb6Xue1Bw@mail.gmail.com>

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

view thread (6+ 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], [email protected]
  Subject: Re: DOC: fixes multiple errors in alter table doc
  In-Reply-To: <CABV9wwMPmo-dg=oV+NaJGa_==uo5+TTvk58aNtjVQZBtMcRVBw@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