On Saturday, January 22, 2022, James Coleman <
jtc331@gmail.com> wrote:
On Sat, Jan 22, 2022 at 12:35 AM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> On Fri, Jan 21, 2022 at 5:14 PM James Coleman <jtc331@gmail.com> wrote:
>>
>>
>> > Really? That's horrid, because that's directly useful advice.
>>
>> Remedied, but rewritten a bit to better fit with the new style/goal of
>> that tip).
>>
>> Version 3 is attached.
>>
>
> Coming back to this after a respite I think the tip needs to be moved just like everything else. For much the same reason (though this may only be a personal bias), I know what SQL Commands do the various things that DDL encompasses (especially the basics like adding a column) and so the DDL section is really just a tutorial-like chapter that I will generally forget about because I will go straight to the official source which is the SQL Command Reference. My future self would want the tip to show up there. If we put the tip after the existing paragraph that starts: "Adding a column with a volatile DEFAULT or changing the type of an existing column..." the need to specify an example function in the tip goes away - though maybe it should be moved to the notes paragraph instead: "with a volatile DEFAULT (e.g., clock_timestamp()) or changing the type of an existing column..."
In my mind that actually might be a reason to keep it that way. I
expect someone who's somewhat experienced to know there are things
(like table rewrites and scans) you need to consider and therefore go
to the ALTER TABLE page and read the details. But for someone newer
the tutorial page needs to introduce them to the idea that those
gotchas exist.
Readers of the DDL page are given a hint of the issues and directed to additional, arguably mandatory, reading. They can not worry about the nuances during their learning phase but instead can defer that reading until they actually have need to alter a (large) table. But expecting them to read the command reference page is reasonable and is IMO the more probable place they will look when they start doing stuff in earnest. For the inexperienced reader breaking this up in this manner based upon depth of detail feels right to me.
David J.