Subject: Re: Adding a Column documentation is misleading
To: Alvaro Herrera <alvherre@2ndquadrant.com>, pgsql-docs@lists.postgresql.org
References: <20191106131330.GA8130@alvherre.pgsql>
From: Gavin Flower <GavinFlower@archidevsys.co.nz>
Organization: ArchiDevSys
Message-ID: <d3143650-7268-8ae3-6814-fa24760fa709@archidevsys.co.nz>
Date: Fri, 8 Nov 2019 09:36:13 +1300
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.1.1
MIME-Version: 1.0
In-Reply-To: <20191106131330.GA8130@alvherre.pgsql>
Content-Type: text/plain; charset=iso-8859-15; format=flowed
Content-Transfer-Encoding: 7bit
Content-Language: en-US
Precedence: bulk

On 07/11/2019 02:13, Alvaro Herrera wrote:
> On 2019-Nov-06, PG Doc comments form wrote:
>
>> Page: https://www.postgresql.org/docs/12/ddl-alter.html
>> Description:
>>
>> In 5.6.1. Adding a Column, there is a kind of example 'ALTER TABLE products
>> ADD COLUMN description text;'
>>
>> The words 'description' and 'text' are misleading -- as according to the
>> formal documentation of the SQL command
>> (https://www.postgresql.org/docs/12/sql-altertable.html), they should be
>> 'column_name' and 'data_type'.
> Well, it's an example, so "description" is the column name and "text" is
> its data type.  If you had a table called products, you could run that
> command and it would work just fine (assuming you don't already have a
> column called description, doh).
>
> Maybe the example could be made clearer by using some other column name
> and some other data type, so that they don't resemble english prose or
> keywords.  Maybe "alter table cities add column year_founded integer".
> Do you want to propose something better than that?
>
>> A similar problem exists for removing a column, and other actions.
> Let's hear your proposed changes.
>
Now it's explained, it is obvious!

Sorry, for the noise.


Cheers,
Gavin