Subject: Adding a Column documentation is misleading

From: PG Doc comments form <[email-masked]>
Date: Wed, 06 Nov 2019 03:24:44 +0000

The following documentation comment has been logged on the website:

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'.

A similar problem exists for removing a column, and other actions.

---

From: Alvaro Herrera <[email-masked]>
Date: Wed, 6 Nov 2019 10:13:30 -0300

> '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.

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

---

From: "David G. Johnston" <[email-masked]>
Date: Wed, 6 Nov 2019 07:12:17 -0700

> A similar problem exists for removing a column, and other actions.

Chapter 5 is tutorial-like and uses actual meaningful names instead of
syntax placeholders.  I don’t really see a problem aside from maybe a
different example name could be chosen.  Making it column_name isn’t an
improvement.

David J.

---

From: Gavin Flower <[email-masked]>
Date: Fri, 8 Nov 2019 09:36:13 +1300

> Let's hear your proposed changes.
Now it's explained, it is obvious!

Sorry, for the noise.

Cheers,
Gavin