Re: Doc: fix the rewrite condition when executing ALTER TABLE ADD COLUMN

On 30.04.25 17:17, Robert Treat wrote:
> On Wed, Apr 30, 2025 at 5:15 AM Peter Eisentraut <peter@eisentraut.org> wrote:
>>
>> On 28.04.25 18:56, Álvaro Herrera wrote:
>>> On 2025-Apr-23, Nathan Bossart wrote:
>>>
>>>> On Mon, Mar 24, 2025 at 11:37:20AM +0100, Álvaro Herrera wrote:
>>>
>>>>> I'd add a note about these two things to the open items page, and wait
>>>>> to see if we get some of these limitations fixed, so that if we don't,
>>>>> we remember to note this limitation in the documentation.
>>>>
>>>> Are we still waiting on something for this, or should we proceed with the
>>>> documentation changes?  It doesn't seem tremendously urgent, but I noticed
>>>> it's been about a month since the last message on this thread.
>>>
>>> I've edited the Open Items page to disclaim my responsibility from this
>>> item, since this comes from virtual generated columns which is not my
>>> turf.  I think we should just document the current state of affairs; we
>>> can come back with further code improvements during the next cycle.
>>
>> Here is a proposed patch that includes some text about virtual generated
>> columns and also fixes up a small mistake in the previous patch
>> (confused identity and generated columns) and improves the wording and
>> formatting a bit more.
> 
> If I were going to quibble, I'd probably rewrite the second paragraph as
> 
> +    Changing the type of an existing column will normally cause the
> entire table
> +    and its indexes to be rewritten.
> +    As an exception, when changing the type of an existing column,
>       if the <literal>USING</literal> clause does not change the column
>       contents and the old type is either binary coercible to the new type
>       or an unconstrained domain over the new type, a table rewrite is not
> -    needed.  However, indexes must always be rebuilt unless the system
> +    needed.  However, indexes will still need to be rebuilt unless the system
>       can verify that the new index would be logically equivalent to the
>       existing one.  For example, if the collation for a column has been
>       changed, an index rebuild is required because the new sort
>       order might be different.  However, in the absence of a collation
>       change, a column can be changed from <type>text</type> to
>       <type>varchar</type> (or vice versa) without rebuilding the indexes
> -    because these data types sort identically.  Table and/or index
> +    because these data types sort identically.
> 
> But otherwise this LGTM.

Thanks, I have worked this into the commit.  I wanted to get away from 
phrases like "needs to be rebuilt" or "must be rebuilt" because that 
possibly sounds like you have to do it manually.  So I tweaked it a bit 
further, but I think I captured the essence.

I'm closing the open item.