Subject: DOC: fixes multiple errors in alter table doc

From: Chao Li <[email-masked]>
Date: Thu, 18 Dec 2025 15:22:09 +0800

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/

---

From: Chao Li <[email-masked]>
Date: Fri, 19 Dec 2025 13:26:38 +0800

> On Dec 18, 2025, at 15:22, 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:
> 
> 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.
> 
> <v1-0001-doc-clarify-and-complete-ALTER-TABLE-syntax-in-re.patch>

CF entry created: https://commitfest.postgresql.org/patch/6328/

Best regards,

---

From: Fujii Masao <[email-masked]>
Date: Mon, 2 Mar 2026 18:04:52 +0900

On Thu, Jan 22, 2026 at 6:38 PM Chao Li <[email-masked]> wrote:
> PFA v3: Rebased, and added reviewer and discussion information.

LGTM.

Should we apply the same change to the ALTER FOREIGN TABLE docs as well?

While reviewing that section, I noticed that ADD COLUMN IF NOT EXISTS appears
to work for ALTER FOREIGN TABLE, but it isn't documented. I'm not sure why
it was left out, but perhaps we should document it and add a regression test in
a separate patch?

Regards,

-- 
Fujii Masao

---

From: Chao Li <[email-masked]>
Date: Mon, 2 Mar 2026 17:22:29 +0800

> On Mar 2, 2026, at 17:04, Fujii Masao <[email-masked]> wrote:
> 

Sure, I can make the change.

> it was left out, but perhaps we should document it and add a regression test in

I will verify that, then update the doc and regression test accordingly.

Best regards,

---

From: Chao Li <[email-masked]>
Date: Tue, 3 Mar 2026 10:09:11 +0800

> On Mar 2, 2026, at 17:22, Chao Li <[email-masked]> wrote:
> 
> 
> 

PFA v4:

0001 - alter table related changes

 * Add test cases for omitting COLUMN of ALTER TABLE ADD/DROP [COLUMN]
 * Add a test case for ADD COLUMN IF NOT EXIST (already had DROP COLUMN IF EXIST)

0002 - alter foreign table related changes

 * doc: Add IF NOT EXSTS for ADD COLUMN
 * doc: Mark COLUMN as optional for ADD/DROP COLUMN in the same way as 0001
 * Add test cases for omitting COLUMN of ALTER FOREIGN TABLE ADD/DROP [COLUMN]
 * Add a test cases for for ADD COLUMN IF NOT EXIST
 * Add a test cases for for DROP COLUMN IF EXIST

Best regards,

---

From: Robert Treat <[email-masked]>
Date: Mon, 2 Mar 2026 23:41:13 -0500

>  * Add a test cases for for DROP COLUMN IF EXIST

LGTM, although I was curious why you went with c12 vs c11 in
+ALTER FOREIGN TABLE ft1 ADD c12 integer; -- omit COLUMN
or maybe that should be changed?

Robert Treat
https://xzilla.net

---

From: Fujii Masao <[email-masked]>
Date: Thu, 5 Mar 2026 13:42:56 +0900

On Tue, Mar 3, 2026 at 5:05 PM Chao Li <[email-masked]> wrote:
> PFA v5:
>
> * In 0002, renamed c12 to c11 in the ALTER FOREIGN TABLE tests.
> * In 0002, added one more test case: ALTER FOREIGN TABLE ft1 DROP IF EXISTS no_column;

Thanks for updating the patches!

I've committed the 0001 patch and backpatched it to all supported versions.

 -- alter noexisting table
 ALTER FOREIGN TABLE IF EXISTS doesnt_exist_ft1 ADD COLUMN c4 integer;
+ALTER FOREIGN TABLE IF EXISTS doesnt_exist_ft1 ADD c5 integer;
<snip>
 ALTER FOREIGN TABLE IF EXISTS doesnt_exist_ft1 DROP COLUMN IF EXISTS no_column;
+ALTER FOREIGN TABLE IF EXISTS doesnt_exist_ft1 DROP IF EXISTS no_column;

Regarding 0002 patch, could you explain the reason for adding these
two additional tests? I was just curious why because other four tests that
the patch adds seem sufficient.

Aside from that point, the patch looks good to me.

Regards,

-- 
Fujii Masao

---

From: Fujii Masao <[email-masked]>
Date: Fri, 6 Mar 2026 15:40:30 +0900

On Thu, Mar 5, 2026 at 2:06 PM Chao Li <[email-masked]> wrote:
> They are combinations of “IF [NOT] EXISTS” and omitting “COLUMN", I added them just for better coverage.

Which table-level or column-level "IF [NOT] EXISTS" are you referring to?
If you mean the combination of column-level "IF [NOT] EXISTS" with
"COLUMN" omitted, then the first test above should be "ALTER FOREIGN TABLE
IF EXISTS doesnt_exist_ft1 ADD IF NOT EXISTS c5 integer"?

Regards,

-- 
Fujii Masao

---

From: Fujii Masao <[email-masked]>
Date: Mon, 9 Mar 2026 18:43:39 +0900

On Fri, Mar 6, 2026 at 4:53 PM Chao Li <[email-masked]> wrote:
> PFA v6.

Thanks for updating the patch!

> The two test cases on table level “IF EXISTS” are removed. So, now the patch adds totally 4 test cases: 2 for omitting COLUMN, 2 for combinations of column level “IF [NOT] EXISTS” and omitting COUMN.

The latest patch doesn't seem to include the combination of column-level
IF NOT EXISTS for ADD COLUMN and omitting COLUMN.

Based on your patch, I updated the regression tests as follows and
pushed the changes:

+ALTER FOREIGN TABLE ft1 ADD c11 integer; -- omit COLUMN
+ALTER FOREIGN TABLE ft1 DROP c11; -- omit COLUMN

I moved the ALTER FOREIGN TABLE DROP test into the section that lists the other
existing ALTER FOREIGN TABLE DROP COLUMN tests.

Regarding table-level IF EXISTS tests, it seemed to me that most
ALTER FOREIGN TABLE ADD/DROP variants should also be tested there,
following the existing structure in foreign_data.sql. So I added some
additional cases, for example ALTER FOREIGN TABLE IF EXISTS ADD COLUMN IF
NOT EXISTS.

Regards,

-- 
Fujii Masao