Re: CREATE TABLE creates a composite type corresponding to the table row, which is and is not there

On Fri, May 17, 2024 at 4:57 PM Erik Wienhold <ewie(at)ewie(dot)name> wrote:

> On 2024-05-16 17:47 +0200, David G. Johnston wrote:
> > On Wed, May 15, 2024 at 8:46 AM Robert Haas <robertmhaas(at)gmail(dot)com>
> wrote:
> >
> > > On Thu, Apr 4, 2024 at 12:41 AM Erik Wienhold <ewie(at)ewie(dot)name> wrote:
> > > > Thanks, fixed in v4. Looks like American English prefers that comma
> and
> > > > it's also more common in our docs.
> > >
> > > Reviewing this patch:
> > >
> > > - Creates a <firstterm>typed table</firstterm>, which takes its
> > > - structure from the specified composite type (name optionally
> > > - schema-qualified). A typed table is tied to its type; for
> > > - example the table will be dropped if the type is dropped
> > > - (with <literal>DROP TYPE ... CASCADE</literal>).
> > > + Creates a <firstterm>typed table</firstterm>, which takes its
> > > structure
> > > + from an existing (name optionally schema-qualified) stand-alone
> > > composite
> > > + type (i.e., created using <xref linkend="sql-createtype"/>)
> though
> > > it
> > > + still produces a new composite type as well. The table will
> have
> > > + a dependency on the referenced type such that cascaded alter and
> > > drop
> > > + actions on the type will propagate to the table.
> > >
> > > It would be better if this diff didn't reflow the unchanged portions
> > > of the paragraph.
>
> Right. I now reformatted it so that first line remains unchanged. But
> the rest of the para is still a complete rewrite.
>
> > > I agree that it's a good idea to mention that the table must have been
> > > created using CREATE TYPE .. AS here, but I disagree with the rest of
> > > the rewording in this hunk. I think we could just add "creating using
> > > CREATE TYPE" to the end of the first sentence, with an xref, and leave
> > > the rest as it is.
> >
> >
> >
> > > I don't see a reason to mention that the typed
> > > table also spawns a rowtype; that's just standard CREATE TABLE
> > > behavior and not really relevant here.
> >
> >
> > I figured it wouldn't be immediately obvious that the system would
> create a
> > second type with identical structure. Of course, in order for SELECT tbl
> > FROM tbl; to work it must indeed do so. I'm not married to pointing out
> > this dynamic explicitly though.
> >
> >
> > > And I don't understand what the
> > > rest of the rewording does for us.
> > >
> >
> > It calls out the explicit behavior that the table's columns can change
> due
> > to actions on the underlying type. Mentioning this unique behavior seems
> > worth a sentence.
> >
> >
> > > <para>
> > > - When a typed table is created, then the data types of the
> > > - columns are determined by the underlying composite type and are
> > > - not specified by the <literal>CREATE TABLE</literal> command.
> > > + A typed table always has the same column names and data types
> as the
> > > + type it is derived from, and you cannot specify additional
> columns.
> > > But the <literal>CREATE TABLE</literal> command can add defaults
> > > - and constraints to the table and can specify storage parameters.
> > > + and constraints to the table, as well as specify storage
> parameters.
> > > </para>
> > >
> > > I don't see how this is better.
> > >
> >
> > I'll agree this is more of a stylistic change, but mainly because the
> talk
> > about data types reasonably implies the other items the patch explicitly
> > mentions - names and additional columns.
>
> I prefer David's changes to both paras because right now the details of
> typed tables are spread over the respective CREATE and ALTER commands
> for types and tables. Or maybe we should add those details to the
> existing "Typed Tables" section at the very end of CREATE TABLE?
>
> > > - errmsg("type %s is not a composite type",
> > > + errmsg("type %s is not a stand-alone composite type",
> > >
> > > I agree with Peter's complaint that people aren't going to understand
> > > what a stand-alone composite type means when they see the revised
> > > error message; to really help people, we're going to need to do better
> > > than this, I think.
> > >
> > >
> > We have a glossary.
>

If sticking with stand-alone composite type as a formal term we should
document it in the glossary. It's unclear whether this will survive review
though. With the wording provided in this patch it doesn't really add
enough to continue a strong defense of it.

> It's now a separate error message (like I already had in v1) which
> states that the specified type must not be a row type of another table
> (based on Peter's feedback). And the hint directs the user to CREATE
> TYPE.
>
> In passing, I also quoted the type name in the existing error message
> for consistency. I saw that table names etc. are already quoted in
> other error messages.
>
>
The hint and the quoting both violate the documented rules for these things:

https://www.postgresql.org/docs/current/error-style-guide.html#ERROR-STYLE-GUIDE-QUOTES

There are functions in the backend that will double-quote their own output
as needed (for example, format_type_be()). Do not put additional quotes
around the output of such functions.

https://www.postgresql.org/docs/current/error-style-guide.html#ERROR-STYLE-GUIDE-GRAMMAR-PUNCTUATION

Detail and hint messages: Use complete sentences, and end each with a
period. Capitalize the first word of sentences.

David J.