doc: create table improvements

From: "David G(dot) Johnston" <david(dot)g(dot)johnston(at)gmail(dot)com>
To: PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: doc: create table improvements
Date: 2024-04-22 19:19:11
Message-ID: CAKFQuwYfMV-2SdrP-umr5SVNSqTn378BUvHsebetp5=DhT494w@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

Hey,

The attached patch addresses four somewhat related aspects of the create
table reference page that bother me.

This got started with Bug# 15954 [1] (unlogged on a partitioned table
doesn't make sense) and I've added a paragraph under "unlogged" to address
it.

While doing that, it seemed desirable to explicitly frame up both temporary
and unlogged as being "persistence modes" so I added a mention of both in
the description. Additionally, it seemed appropriate to do so immediately
after the opening paragraph since the existing second paragraph goes
immediately into talking about temporary tables and schemas. I figured a
link to the reliability chapter where one learns about WAL and why/how
these alternative persistence modes exist is worthwhile. (I added a missing
comma to the first sentence while I was in the area)

Third, I've had a long-standing annoyance regarding the excessive length of
the CREATE line of each of the create table syntax blocks. Replacing the
syntax for the persistence modes with a named placeholder introduces
structure and clarity while reducing the length of the line nicely.

Finally, while fixing line lengths, the subsequent line (first form) for
column specification is even more excessive. Pulling out the
column_storage syntax into a named reference nicely cleans this line up.

David J.

P.S. I didn't go into depth on the fact the persistence options are not
inherited/copied/like-able; so for now the fact they are not so is
discovered by their omission when discussing those topics.

[1]
https://www.postgresql.org/message-id/flat/15954-b61523bed4b110c4%40postgresql.org

Attachment Content-Type Size
0001-doc-create-table-doc-enhancements.patch text/x-patch 5.5 KB

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Robert Haas 2024-04-22 19:19:15 Re: post-freeze damage control
Previous Message Nathan Bossart 2024-04-22 19:01:03 Re: improve performance of pg_dump --binary-upgrade