doc: Clarify that COLUMN is optional in ALTER TABLE ... ADD/DROP COLUMN.

In ALTER TABLE ... ADD/DROP COLUMN, the COLUMN keyword is optional. However,
part of the documentation could be read as if COLUMN were required, which may
mislead users about the command syntax.

This commit updates the ALTER TABLE documentation to clearly state that
COLUMN is optional for ADD and DROP.

Also this commit adds regression tests covering ALTER TABLE ... ADD/DROP
without the COLUMN keyword.

Backpatch to all supported versions.

Author: Chao Li <lic@highgo.com>
Reviewed-by: Robert Treat <rob@xzilla.net>
Reviewed-by: Fujii Masao <masao.fujii@gmail.com>
Discussion: https://postgr.es/m/CAEoWx2n6ShLMOnjOtf63TjjgGbgiTVT5OMsSOFmbjGb6Xue1Bw@mail.gmail.com
Backpatch-through: 14

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index b7083e20c62cddb9f2ab965d203d4014514b8195..7db01652cffb537ee0155b5c7ccd28c35adb2d28 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -155,7 +155,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
@@ -167,7 +167,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

diff --git a/src/test/regress/expected/alter_table.out b/src/test/regress/expected/alter_table.out
index f53f00c428b3833fe589dc5c6cfac7a9ff10d6a1..632fbfdba84b366eb7a68cb471a4edecfb57e4dd 100644 (file)
--- a/src/test/regress/expected/alter_table.out
+++ b/src/test/regress/expected/alter_table.out
@@ -3760,6 +3760,16 @@ Referenced by:
 ALTER TABLE test_add_column
        ADD COLUMN IF NOT EXISTS c5 SERIAL CHECK (c5 > 10);
 NOTICE:  column "c5" of relation "test_add_column" already exists, skipping
+ALTER TABLE test_add_column
+       ADD c6 integer; -- omit COLUMN
+ALTER TABLE test_add_column
+       ADD IF NOT EXISTS c6 integer;
+NOTICE:  column "c6" of relation "test_add_column" already exists, skipping
+ALTER TABLE test_add_column
+       DROP c6; -- omit COLUMN
+ALTER TABLE test_add_column
+       DROP IF EXISTS c6;
+NOTICE:  column "c6" of relation "test_add_column" does not exist, skipping
 \d test_add_column*
                             Table "public.test_add_column"
  Column |  Type   | Collation | Nullable |                   Default                   

diff --git a/src/test/regress/sql/alter_table.sql b/src/test/regress/sql/alter_table.sql
index ab23d80f63b8da840cb90d2e9f6beb5cfe1a2de4..a4e915a857f3a02573b3fe37f39f46ba3fbe3019 100644 (file)
--- a/src/test/regress/sql/alter_table.sql
+++ b/src/test/regress/sql/alter_table.sql
@@ -2309,6 +2309,14 @@ ALTER TABLE test_add_column
 \d test_add_column
 ALTER TABLE test_add_column
        ADD COLUMN IF NOT EXISTS c5 SERIAL CHECK (c5 > 10);
+ALTER TABLE test_add_column
+       ADD c6 integer; -- omit COLUMN
+ALTER TABLE test_add_column
+       ADD IF NOT EXISTS c6 integer;
+ALTER TABLE test_add_column
+       DROP c6; -- omit COLUMN
+ALTER TABLE test_add_column
+       DROP IF EXISTS c6;
 \d test_add_column*
 DROP TABLE test_add_column;
 \d test_add_column*