MIME-Version: 1.0
From: "David G. Johnston" <david.g.johnston@gmail.com>
Date: Mon, 22 Apr 2024 12:19:11 -0700
Message-ID: <CAKFQuwYfMV-2SdrP-umr5SVNSqTn378BUvHsebetp5=DhT494w@mail.gmail.com>
Subject: doc: create table improvements
To: PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Content-Type: multipart/mixed; boundary="000000000000243f8d0616b45250"
Archived-At: <https://www.postgresql.org/message-id/CAKFQuwYfMV-2SdrP-umr5SVNSqTn378BUvHsebetp5%3DDhT494w%40mail.gmail.com>
Precedence: bulk

--000000000000243f8d0616b45250
Content-Type: multipart/alternative; boundary="000000000000243f8b0616b4524e"

--000000000000243f8b0616b4524e
Content-Type: text/plain; charset="UTF-8"

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

--000000000000243f8b0616b4524e
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div class=3D"gmail_default" style=3D"font-family:arial,he=
lvetica,sans-serif">Hey,</div><div class=3D"gmail_default" style=3D"font-fa=
mily:arial,helvetica,sans-serif"><br></div><div class=3D"gmail_default" sty=
le=3D"font-family:arial,helvetica,sans-serif">The attached patch addresses =
four somewhat related aspects of the create table reference page that bothe=
r me.</div><div class=3D"gmail_default" style=3D"font-family:arial,helvetic=
a,sans-serif"><br></div><div class=3D"gmail_default" style=3D"font-family:a=
rial,helvetica,sans-serif">This got started with Bug# 15954 [1] (unlogged o=
n a partitioned table doesn&#39;t make sense) and I&#39;ve added a paragrap=
h under &quot;unlogged&quot; to address it.</div><div class=3D"gmail_defaul=
t" style=3D"font-family:arial,helvetica,sans-serif"><br></div><div class=3D=
"gmail_default" style=3D"font-family:arial,helvetica,sans-serif">While doin=
g that, it seemed desirable to explicitly frame up both temporary and unlog=
ged as being &quot;persistence modes&quot; so I added a mention of both in =
the description.=C2=A0 Additionally, it seemed appropriate to do so immedia=
tely after the opening paragraph since the existing second paragraph goes i=
mmediately into talking about temporary tables and schemas.=C2=A0 I figured=
 a link to the reliability chapter where one learns about WAL and why/how t=
hese alternative persistence modes exist is worthwhile. (I added a missing =
comma to the first sentence while I was in the area)</div><div class=3D"gma=
il_default" style=3D"font-family:arial,helvetica,sans-serif"><br></div><div=
 class=3D"gmail_default" style=3D"font-family:arial,helvetica,sans-serif">T=
hird, I&#39;ve had a long-standing annoyance regarding the excessive length=
 of the CREATE line of each of the create table syntax blocks.=C2=A0 Replac=
ing the syntax for the persistence modes with a named placeholder introduce=
s structure and clarity while reducing the length of the line nicely.</div>=
<div class=3D"gmail_default" style=3D"font-family:arial,helvetica,sans-seri=
f"><br></div><div class=3D"gmail_default" style=3D"font-family:arial,helvet=
ica,sans-serif">Finally, while fixing line lengths, the subsequent line (fi=
rst form) for column specification is even more excessive.=C2=A0 Pulling ou=
t the column_storage syntax into a named reference nicely cleans this line =
up.</div><div class=3D"gmail_default" style=3D"font-family:arial,helvetica,=
sans-serif"><br></div><div class=3D"gmail_default" style=3D"font-family:ari=
al,helvetica,sans-serif">David J.</div><div class=3D"gmail_default" style=
=3D"font-family:arial,helvetica,sans-serif"><br></div><div class=3D"gmail_d=
efault" style=3D"font-family:arial,helvetica,sans-serif">P.S. I didn&#39;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 omiss=
ion=C2=A0when discussing those topics.</div><div class=3D"gmail_default" st=
yle=3D"font-family:arial,helvetica,sans-serif"><div class=3D"gmail_default"=
><br class=3D"gmail-Apple-interchange-newline">[1] <a href=3D"https://www.p=
ostgresql.org/message-id/flat/15954-b61523bed4b110c4%40postgresql.org">http=
s://www.postgresql.org/message-id/flat/15954-b61523bed4b110c4%40postgresql.=
org</a><br></div><div class=3D"gmail_default"><br></div></div></div>

--000000000000243f8b0616b4524e--
--000000000000243f8d0616b45250
Content-Type: text/x-patch; charset="US-ASCII"; 
	name="0001-doc-create-table-doc-enhancements.patch"
Content-Disposition: attachment; 
	filename="0001-doc-create-table-doc-enhancements.patch"
Content-Transfer-Encoding: base64
Content-ID: <f_lvbc4ykh0>
X-Attachment-Id: f_lvbc4ykh0

RnJvbSBlMzc1MDQ0ZDU1ODA5ZDIzOWJlMzNmMzFjNGVmYTg0MTA3OTBkM2YwIE1vbiBTZXAgMTcg
MDA6MDA6MDAgMjAwMQpGcm9tOiAiRGF2aWQgRy4gSm9obnN0b24iIDxkYXZpZC5nLmpvaG5zdG9u
QGdtYWlsLmNvbT4KRGF0ZTogTW9uLCAyMiBBcHIgMjAyNCAxMTo1MTo1MyAtMDcwMApTdWJqZWN0
OiBbUEFUQ0hdIGRvYzogY3JlYXRlIHRhYmxlIGRvYyBlbmhhbmNlbWVudHMKCi0tLQogZG9jL3Ny
Yy9zZ21sL3JlZi9jcmVhdGVfdGFibGUuc2dtbCB8IDM3ICsrKysrKysrKysrKysrKysrKysrKysr
KystLS0tLQogMSBmaWxlIGNoYW5nZWQsIDMxIGluc2VydGlvbnMoKyksIDYgZGVsZXRpb25zKC0p
CgpkaWZmIC0tZ2l0IGEvZG9jL3NyYy9zZ21sL3JlZi9jcmVhdGVfdGFibGUuc2dtbCBiL2RvYy9z
cmMvc2dtbC9yZWYvY3JlYXRlX3RhYmxlLnNnbWwKaW5kZXggMDJmMzFkMmQ2Zi4uOWE1ZGFmYjlh
ZiAxMDA2NDQKLS0tIGEvZG9jL3NyYy9zZ21sL3JlZi9jcmVhdGVfdGFibGUuc2dtbAorKysgYi9k
b2Mvc3JjL3NnbWwvcmVmL2NyZWF0ZV90YWJsZS5zZ21sCkBAIC0yMSw4ICsyMSw4IEBAIFBvc3Rn
cmVTUUwgZG9jdW1lbnRhdGlvbgogCiAgPHJlZnN5bm9wc2lzZGl2PgogPHN5bm9wc2lzPgotQ1JF
QVRFIFsgWyBHTE9CQUwgfCBMT0NBTCBdIHsgVEVNUE9SQVJZIHwgVEVNUCB9IHwgVU5MT0dHRUQg
XSBUQUJMRSBbIElGIE5PVCBFWElTVFMgXSA8cmVwbGFjZWFibGUgY2xhc3M9InBhcmFtZXRlciI+
dGFibGVfbmFtZTwvcmVwbGFjZWFibGU+ICggWwotICB7IDxyZXBsYWNlYWJsZSBjbGFzcz0icGFy
YW1ldGVyIj5jb2x1bW5fbmFtZTwvcmVwbGFjZWFibGU+IDxyZXBsYWNlYWJsZSBjbGFzcz0icGFy
YW1ldGVyIj5kYXRhX3R5cGU8L3JlcGxhY2VhYmxlPiBbIFNUT1JBR0UgeyBQTEFJTiB8IEVYVEVS
TkFMIHwgRVhURU5ERUQgfCBNQUlOIHwgREVGQVVMVCB9IF0gWyBDT01QUkVTU0lPTiA8cmVwbGFj
ZWFibGU+Y29tcHJlc3Npb25fbWV0aG9kPC9yZXBsYWNlYWJsZT4gXSBbIENPTExBVEUgPHJlcGxh
Y2VhYmxlPmNvbGxhdGlvbjwvcmVwbGFjZWFibGU+IF0gWyA8cmVwbGFjZWFibGUgY2xhc3M9InBh
cmFtZXRlciI+Y29sdW1uX2NvbnN0cmFpbnQ8L3JlcGxhY2VhYmxlPiBbIC4uLiBdIF0KK0NSRUFU
RSBbIDxyZXBsYWNlYWJsZT5wZXJzaXN0ZW5jZV9tb2RlPC9yZXBsYWNlYWJsZT4gXSBUQUJMRSBb
IElGIE5PVCBFWElTVFMgXSA8cmVwbGFjZWFibGUgY2xhc3M9InBhcmFtZXRlciI+dGFibGVfbmFt
ZTwvcmVwbGFjZWFibGU+ICggWworICB7IDxyZXBsYWNlYWJsZSBjbGFzcz0icGFyYW1ldGVyIj5j
b2x1bW5fbmFtZTwvcmVwbGFjZWFibGU+IDxyZXBsYWNlYWJsZSBjbGFzcz0icGFyYW1ldGVyIj5k
YXRhX3R5cGU8L3JlcGxhY2VhYmxlPiBbIDxyZXBsYWNlYWJsZT5jb2x1bW5fc3RvcmFnZTwvcmVw
bGFjZWFibGU+IF0gWyBDT0xMQVRFIDxyZXBsYWNlYWJsZT5jb2xsYXRpb248L3JlcGxhY2VhYmxl
PiBdIFsgPHJlcGxhY2VhYmxlIGNsYXNzPSJwYXJhbWV0ZXIiPmNvbHVtbl9jb25zdHJhaW50PC9y
ZXBsYWNlYWJsZT4gWyAuLi4gXSBdCiAgICAgfCA8cmVwbGFjZWFibGU+dGFibGVfY29uc3RyYWlu
dDwvcmVwbGFjZWFibGU+CiAgICAgfCBMSUtFIDxyZXBsYWNlYWJsZT5zb3VyY2VfdGFibGU8L3Jl
cGxhY2VhYmxlPiBbIDxyZXBsYWNlYWJsZT5saWtlX29wdGlvbjwvcmVwbGFjZWFibGU+IC4uLiBd
IH0KICAgICBbLCAuLi4gXQpAQCAtMzQsNyArMzQsNyBAQCBDUkVBVEUgWyBbIEdMT0JBTCB8IExP
Q0FMIF0geyBURU1QT1JBUlkgfCBURU1QIH0gfCBVTkxPR0dFRCBdIFRBQkxFIFsgSUYgTk9UIEVY
SQogWyBPTiBDT01NSVQgeyBQUkVTRVJWRSBST1dTIHwgREVMRVRFIFJPV1MgfCBEUk9QIH0gXQog
WyBUQUJMRVNQQUNFIDxyZXBsYWNlYWJsZSBjbGFzcz0icGFyYW1ldGVyIj50YWJsZXNwYWNlX25h
bWU8L3JlcGxhY2VhYmxlPiBdCiAKLUNSRUFURSBbIFsgR0xPQkFMIHwgTE9DQUwgXSB7IFRFTVBP
UkFSWSB8IFRFTVAgfSB8IFVOTE9HR0VEIF0gVEFCTEUgWyBJRiBOT1QgRVhJU1RTIF0gPHJlcGxh
Y2VhYmxlIGNsYXNzPSJwYXJhbWV0ZXIiPnRhYmxlX25hbWU8L3JlcGxhY2VhYmxlPgorQ1JFQVRF
IFsgPHJlcGxhY2VhYmxlPnBlcnNpc3RlbmNlX21vZGU8L3JlcGxhY2VhYmxlPiBdIFRBQkxFIFsg
SUYgTk9UIEVYSVNUUyBdIDxyZXBsYWNlYWJsZSBjbGFzcz0icGFyYW1ldGVyIj50YWJsZV9uYW1l
PC9yZXBsYWNlYWJsZT4KICAgICBPRiA8cmVwbGFjZWFibGUgY2xhc3M9InBhcmFtZXRlciI+dHlw
ZV9uYW1lPC9yZXBsYWNlYWJsZT4gWyAoCiAgIHsgPHJlcGxhY2VhYmxlIGNsYXNzPSJwYXJhbWV0
ZXIiPmNvbHVtbl9uYW1lPC9yZXBsYWNlYWJsZT4gWyBXSVRIIE9QVElPTlMgXSBbIDxyZXBsYWNl
YWJsZSBjbGFzcz0icGFyYW1ldGVyIj5jb2x1bW5fY29uc3RyYWludDwvcmVwbGFjZWFibGU+IFsg
Li4uIF0gXQogICAgIHwgPHJlcGxhY2VhYmxlPnRhYmxlX2NvbnN0cmFpbnQ8L3JlcGxhY2VhYmxl
PiB9CkBAIC00Niw3ICs0Niw3IEBAIENSRUFURSBbIFsgR0xPQkFMIHwgTE9DQUwgXSB7IFRFTVBP
UkFSWSB8IFRFTVAgfSB8IFVOTE9HR0VEIF0gVEFCTEUgWyBJRiBOT1QgRVhJCiBbIE9OIENPTU1J
VCB7IFBSRVNFUlZFIFJPV1MgfCBERUxFVEUgUk9XUyB8IERST1AgfSBdCiBbIFRBQkxFU1BBQ0Ug
PHJlcGxhY2VhYmxlIGNsYXNzPSJwYXJhbWV0ZXIiPnRhYmxlc3BhY2VfbmFtZTwvcmVwbGFjZWFi
bGU+IF0KIAotQ1JFQVRFIFsgWyBHTE9CQUwgfCBMT0NBTCBdIHsgVEVNUE9SQVJZIHwgVEVNUCB9
IHwgVU5MT0dHRUQgXSBUQUJMRSBbIElGIE5PVCBFWElTVFMgXSA8cmVwbGFjZWFibGUgY2xhc3M9
InBhcmFtZXRlciI+dGFibGVfbmFtZTwvcmVwbGFjZWFibGU+CitDUkVBVEUgWyA8cmVwbGFjZWFi
bGU+cGVyc2lzdGVuY2VfbW9kZTwvcmVwbGFjZWFibGU+IF0gVEFCTEUgWyBJRiBOT1QgRVhJU1RT
IF0gPHJlcGxhY2VhYmxlIGNsYXNzPSJwYXJhbWV0ZXIiPnRhYmxlX25hbWU8L3JlcGxhY2VhYmxl
PgogICAgIFBBUlRJVElPTiBPRiA8cmVwbGFjZWFibGUgY2xhc3M9InBhcmFtZXRlciI+cGFyZW50
X3RhYmxlPC9yZXBsYWNlYWJsZT4gWyAoCiAgIHsgPHJlcGxhY2VhYmxlIGNsYXNzPSJwYXJhbWV0
ZXIiPmNvbHVtbl9uYW1lPC9yZXBsYWNlYWJsZT4gWyBXSVRIIE9QVElPTlMgXSBbIDxyZXBsYWNl
YWJsZSBjbGFzcz0icGFyYW1ldGVyIj5jb2x1bW5fY29uc3RyYWludDwvcmVwbGFjZWFibGU+IFsg
Li4uIF0gXQogICAgIHwgPHJlcGxhY2VhYmxlPnRhYmxlX2NvbnN0cmFpbnQ8L3JlcGxhY2VhYmxl
PiB9CkBAIC01OCw3ICs1OCwxNiBAQCBDUkVBVEUgWyBbIEdMT0JBTCB8IExPQ0FMIF0geyBURU1Q
T1JBUlkgfCBURU1QIH0gfCBVTkxPR0dFRCBdIFRBQkxFIFsgSUYgTk9UIEVYSQogWyBPTiBDT01N
SVQgeyBQUkVTRVJWRSBST1dTIHwgREVMRVRFIFJPV1MgfCBEUk9QIH0gXQogWyBUQUJMRVNQQUNF
IDxyZXBsYWNlYWJsZSBjbGFzcz0icGFyYW1ldGVyIj50YWJsZXNwYWNlX25hbWU8L3JlcGxhY2Vh
YmxlPiBdCiAKLTxwaHJhc2U+d2hlcmUgPHJlcGxhY2VhYmxlIGNsYXNzPSJwYXJhbWV0ZXIiPmNv
bHVtbl9jb25zdHJhaW50PC9yZXBsYWNlYWJsZT4gaXM6PC9waHJhc2U+Cis8cGhyYXNlPndoZXJl
IDxyZXBsYWNlYWJsZT5wZXJzaXN0ZW5jZV9tb2RlPC9yZXBsYWNlYWJsZT4gaXM6IDwvcGhyYXNl
PgorCitbIEdMT0JBTCB8IExPQ0FMIF0geyBURU1QT1JBUlkgfCBURU1QIH0gfAorVU5MT0dHRUQK
KworPHBocmFzZT5hbmQgPHJlcGxhY2VhYmxlPmNvbHVtbl9zdG9yYWdlPC9yZXBsYWNlYWJsZT4g
aXM6PC9waHJhc2U+CisKK1NUT1JBR0UgeyBQTEFJTiB8IEVYVEVSTkFMIHwgRVhURU5ERUQgfCBN
QUlOIHwgREVGQVVMVCB9IFsgQ09NUFJFU1NJT04gPHJlcGxhY2VhYmxlPmNvbXByZXNzaW9uX21l
dGhvZDwvcmVwbGFjZWFibGU+IF0KKworPHBocmFzZT5hbmQgPHJlcGxhY2VhYmxlIGNsYXNzPSJw
YXJhbWV0ZXIiPmNvbHVtbl9jb25zdHJhaW50PC9yZXBsYWNlYWJsZT4gaXM6PC9waHJhc2U+CiAK
IFsgQ09OU1RSQUlOVCA8cmVwbGFjZWFibGUgY2xhc3M9InBhcmFtZXRlciI+Y29uc3RyYWludF9u
YW1lPC9yZXBsYWNlYWJsZT4gXQogeyBOT1QgTlVMTCB8CkBAIC0xMTgsMTEgKzEyNywyMSBAQCBX
SVRIICggTU9EVUxVUyA8cmVwbGFjZWFibGUgY2xhc3M9InBhcmFtZXRlciI+bnVtZXJpY19saXRl
cmFsPC9yZXBsYWNlYWJsZT4sIFJFTQogICA8dGl0bGU+RGVzY3JpcHRpb248L3RpdGxlPgogCiAg
IDxwYXJhPgotICAgPGNvbW1hbmQ+Q1JFQVRFIFRBQkxFPC9jb21tYW5kPiB3aWxsIGNyZWF0ZSBh
IG5ldywgaW5pdGlhbGx5IGVtcHR5IHRhYmxlCisgICA8Y29tbWFuZD5DUkVBVEUgVEFCTEU8L2Nv
bW1hbmQ+IHdpbGwgY3JlYXRlIGEgbmV3LCBpbml0aWFsbHkgZW1wdHksIHRhYmxlCiAgICBpbiB0
aGUgY3VycmVudCBkYXRhYmFzZS4gVGhlIHRhYmxlIHdpbGwgYmUgb3duZWQgYnkgdGhlIHVzZXIg
aXNzdWluZyB0aGUKICAgIGNvbW1hbmQuCiAgIDwvcGFyYT4KIAorICA8cGFyYT4KKyAgIFRoZSBy
ZWxpYWJpbGl0eSBjaGFyYWN0ZXJpc3RpY3Mgb2YgYSB0YWJsZSBhcmUgZ292ZXJuZWQgYnkgaXRz
CisgICBwZXJzaXN0ZW5jZSBtb2RlLiAgVGhlIGRlZmF1bHQgbW9kZSBpcyBkZXNjcmliZWQKKyAg
IDxsaW5rIGxpbmtlbmQ9IndhbC1yZWxpYWJpbGl0eSI+aGVyZTwvbGluaz4KKyAgIFRoZXJlIGFy
ZSB0d28gYWx0ZXJuYXRpdmUgbW9kZXMgdGhhdCBjYW4gYmUgc3BlY2lmaWVkIGR1cmluZworICAg
dGFibGUgY3JlYXRpb246CisgICA8bGluayBsaW5rZW5kPSJzcWwtY3JlYXRldGFibGUtdGVtcG9y
YXJ5Ij50ZW1wb3Jhcnk8L2xpbms+IGFuZAorICAgPGxpbmsgbGlua2VuZD0ic3FsLWNyZWF0ZXRh
YmxlLXVubG9nZ2VkIj51bmxvZ2dlZDwvbGluaz4uCisgIDwvcGFyYT4KKwogICA8cGFyYT4KICAg
IElmIGEgc2NoZW1hIG5hbWUgaXMgZ2l2ZW4gKGZvciBleGFtcGxlLCA8bGl0ZXJhbD5DUkVBVEUg
VEFCTEUKICAgIG15c2NoZW1hLm15dGFibGUgLi4uPC9saXRlcmFsPikgdGhlbiB0aGUgdGFibGUg
aXMgY3JlYXRlZCBpbiB0aGUgc3BlY2lmaWVkCkBAIC0yMjEsNiArMjQwLDEyIEBAIFdJVEggKCBN
T0RVTFVTIDxyZXBsYWNlYWJsZSBjbGFzcz0icGFyYW1ldGVyIj5udW1lcmljX2xpdGVyYWw8L3Jl
cGxhY2VhYmxlPiwgUkVNCiAgICAgICBJZiB0aGlzIGlzIHNwZWNpZmllZCwgYW55IHNlcXVlbmNl
cyBjcmVhdGVkIHRvZ2V0aGVyIHdpdGggdGhlIHVubG9nZ2VkCiAgICAgICB0YWJsZSAoZm9yIGlk
ZW50aXR5IG9yIHNlcmlhbCBjb2x1bW5zKSBhcmUgYWxzbyBjcmVhdGVkIGFzIHVubG9nZ2VkLgog
ICAgICA8L3BhcmE+CisKKyAgICAgPHBhcmE+CisgICAgICBJZiBzcGVjaWZpZWQgb24gYSBwYXJ0
aXRpb25lZCB0YWJsZSB0aGUgcHJvcGVydHkgaXMgcmVjb3JkZWQgYnV0IGlnbm9yZWQ6CisgICAg
ICB0aGUgZW50aXJlIHBhcnRpdGlvbmVkIHRhYmxlIGlzIG5vdCBhdXRvbWF0aWNhbGx5IHRydW5j
YXRlZCBhZnRlciBhIGNyYXNoCisgICAgICBvciB1bmNsZWFuIHNodXRkb3duLgorICAgICA8L3Bh
cmE+CiAgICAgPC9saXN0aXRlbT4KICAgIDwvdmFybGlzdGVudHJ5PgogCi0tIAoyLjM0LjEKCg==
--000000000000243f8d0616b45250--