Feedback-ID: ie0a040ee:Fastmail
Message-ID: <21ff4e12-0b59-4062-be22-f89c6e69773f@eisentraut.org>
Date: Wed, 18 Sep 2024 09:22:02 +0200
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: Elaborate on phrase "table metadata" in the Notes section of
 ALTER by specifying pg_attribute
To: amin@gilani.me, pgsql-docs@lists.postgresql.org
References: <172608553929.1128079.5845807167540849323@wrigleys.postgresql.org>
Content-Language: en-US
From: Peter Eisentraut <peter@eisentraut.org>
In-Reply-To: 
 <172608553929.1128079.5845807167540849323@wrigleys.postgresql.org>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Archived-At: 
 <https://www.postgresql.org/message-id/21ff4e12-0b59-4062-be22-f89c6e69773f%40eisentraut.org>
Precedence: bulk

On 11.09.24 22:12, PG Doc comments form wrote:
> Page:https://www.postgresql.org/docs/16/sql-altertable.html
> Description:
> 
> I am newish to Postgres, and the term "table metadata" was confusing to
> me.

I think it is pretty easy to do a quick internet search to find out what 
table metadata is in the context of an SQL database.  Your complaint 
isn't wrong in the sense that the term isn't formally defined here, but 
in this case I would opt against adding more text and leave it up to the 
user to do the extra research as necessary.  The operation being 
discussed isn't something a completely new user would immediately 
encounter, after all.

> 
> I am more than happy to submit a patch for this. I'm just unfamiliar with
> the process. Please advise.
> 
>> When a column is added with ADD COLUMN and a non-volatile DEFAULT is
> specified, the default is evaluated at the time of the statement and the
> result stored in the table's metadata. That value will be used for the
> column for all existing rows. If no DEFAULT is specified, NULL is used. In
> neither case is a rewrite of the table required.
> 
> Specifically this sentence: "the result stored in the table's metadata"
> 
> Suggest adding specific language to correct it to "the result stored in the
> table's metadata. See `pg_attribute` for more information."
>