Message-ID: <ae5203d1f68267b1e67cfd32023ece1367689b83.camel@cybertec.at>
Subject: Re: doc: create table improvements
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: "David G. Johnston" <david.g.johnston@gmail.com>, Peter Eisentraut
	 <peter@eisentraut.org>
Cc: PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Date: Fri, 28 Feb 2025 14:56:44 +0100
In-Reply-To: <CAKFQuwYk7NsEAEsPEUdbc_gXB0OR+gZzmBjDcUSe5JZuE+d_iw@mail.gmail.com>
References: 
	<CAKFQuwYfMV-2SdrP-umr5SVNSqTn378BUvHsebetp5=DhT494w@mail.gmail.com>
	 <ec0bd3d2-3e15-4492-b93a-683c04ec345c@eisentraut.org>
	 <CAKFQuwYk7NsEAEsPEUdbc_gXB0OR+gZzmBjDcUSe5JZuE+d_iw@mail.gmail.com>
Content-Type: multipart/mixed; boundary="=-SBYb+Bawm4vDzxzB2Zn9"
User-Agent: Evolution 3.54.3 (3.54.3-1.fc41) 
MIME-Version: 1.0
Archived-At: <https://www.postgresql.org/message-id/ae5203d1f68267b1e67cfd32023ece1367689b83.camel%40cybertec.at>
Precedence: bulk

--=-SBYb+Bawm4vDzxzB2Zn9
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Wed, 2024-04-24 at 07:45 -0700, David G. Johnston wrote:
> On Wed, Apr 24, 2024 at 3:30=E2=80=AFAM Peter Eisentraut <peter@eisentrau=
t.org> wrote:
> > =C2=A0> +=C2=A0 =C2=A0The reliability characteristics of a table are go=
verned by its
> > =C2=A0> +=C2=A0 =C2=A0persistence mode.=C2=A0 The default mode is descr=
ibed
> > =C2=A0> +=C2=A0 =C2=A0<link linkend=3D"wal-reliability">here</link>
> > =C2=A0> +=C2=A0 =C2=A0There are two alternative modes that can be speci=
fied during
> > =C2=A0> +=C2=A0 =C2=A0table creation:
> > =C2=A0> +=C2=A0 =C2=A0<link linkend=3D"sql-createtable-temporary">tempo=
rary</link> and
> > =C2=A0> +=C2=A0 =C2=A0<link linkend=3D"sql-createtable-unlogged">unlogg=
ed</link>.
> >=20
> > Not sure reliability is the best word here.=C2=A0 I mean, a temporary t=
able=20
> > isn't any less reliable than any other table.=C2=A0 It just does differ=
ent=20
> > things.
>=20
> Given the name of the section where this is all discussed I'm having trou=
ble
> going=C2=A0with a different word.=C2=A0

This patch has rotted somewhat, and parts of it have become obsolete
with commit e2bab2d792.  Still, I think that it is a good idea to shorten
the lines in the synopsis.

A detailed review:

> diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create=
_table.sgml
> index 02f31d2d6f..9a5dafb9af 100644
> --- a/doc/src/sgml/ref/create_table.sgml
> +++ b/doc/src/sgml/ref/create_table.sgml
> [...]
> +<phrase>and <replaceable>column_storage</replaceable> is:</phrase>
> +
> +STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT } [ COMPRESSION <=
replaceable>compression_method</replaceable> ]
> [...]

I don't know if "column_storage" is descriptive.  After all, this is solely
about TOAST details, which is only one aspect of storage.
I have renamed it to "oversize_storage".


@@ -118,11 +127,21 @@ WITH ( MODULUS <replaceable class=3D"parameter">numer=
ic_literal</replaceable>, REM
   <title>Description</title>
=20
   <para>
-   <command>CREATE TABLE</command> will create a new, initially empty tabl=
e
+   <command>CREATE TABLE</command> will create a new, initially empty, tab=
le
    in the current database. The table will be owned by the user issuing th=
e
    command.
   </para>

I am not a native speaker, but the sentence feels better to me without
the extra comma.  I took the liberty to undo this change, partly because
it is unrelated to the topic of the patch.

+  <para>
+   The reliability characteristics of a table are governed by its
+   persistence mode.  The default mode is described
+   <link linkend=3D"wal-reliability">here</link>
+   There are two alternative modes that can be specified during
+   table creation:
+   <link linkend=3D"sql-createtable-temporary">temporary</link> and
+   <link linkend=3D"sql-createtable-unlogged">unlogged</link>.
+  </para>

I agree with Peter that "reliability" is not ideal.  I went with
"durability" instead.  I removed the link to the reliability discussion
and rephrased the sentence somewhat.

+
+     <para>
+      If specified on a partitioned table the property is recorded but ign=
ored:
+      the entire partitioned table is not automatically truncated after a =
crash
+      or unclean shutdown.
+     </para>

This has become obsolete with e2bab2d792, so I removed it.

Attached is an updated patch.

Yours,
Laurenz Albe

--=-SBYb+Bawm4vDzxzB2Zn9
Content-Disposition: attachment; filename="v2-0001-Unclutter-CREATE-TABLE-synopsis.patch"
Content-Transfer-Encoding: base64
Content-Type: text/x-patch; name="v2-0001-Unclutter-CREATE-TABLE-synopsis.patch";
	charset="UTF-8"

RnJvbSAzMzhkZmI1MmQ4M2QwZjljMDc0MjE2NDFhMDExMWEyZjhlNjNiMzRlIE1vbiBTZXAgMTcg
MDA6MDA6MDAgMjAwMQpGcm9tOiBMYXVyZW56IEFsYmUgPGxhdXJlbnouYWxiZUBjeWJlcnRlYy5h
dD4KRGF0ZTogRnJpLCAyOCBGZWIgMjAyNSAxNDozNjoyNSArMDEwMApTdWJqZWN0OiBbUEFUQ0gg
djJdIFVuY2x1dHRlciBDUkVBVEUgVEFCTEUgc3lub3BzaXMKCkZhY3RvciBvdXQgdGhlICJwZXJz
aXN0ZW5jZSBtb2RlIiBhbmQgIm92ZXJzaXplIHN0b3JhZ2UiIHBhcnRzCm9mIHRoZSBzeW50YXgg
c3lub3BzaXMgdG8gcmVkdWNlIHRoZSBsaW5lIGxlbmd0aCBhbmQgaW5jcmVhc2UKdGhlIHJlYWRh
YmlsaXR5LgoKQXV0aG9yOiBEYXZpZCBHLiBKb2huc3RvbgpSZXZpZXdlZC1ieTogTGF1cmVueiBB
bGJlCkRpc2N1c3Npb246IGh0dHBzOi8vcG9zdGdyLmVzL20vQ0FLRlF1d1lmTVYtMlNkclAtdW1y
NVNWTlNxVG4zNzhCVXZIc2ViZXRwNSUzRERoVDQ5NHclNDBtYWlsLmdtYWlsLmNvbQotLS0KIGRv
Yy9zcmMvc2dtbC9yZWYvY3JlYXRlX3RhYmxlLnNnbWwgfCAyNyArKysrKysrKysrKysrKysrKysr
KysrLS0tLS0KIDEgZmlsZSBjaGFuZ2VkLCAyMiBpbnNlcnRpb25zKCspLCA1IGRlbGV0aW9ucygt
KQoKZGlmZiAtLWdpdCBhL2RvYy9zcmMvc2dtbC9yZWYvY3JlYXRlX3RhYmxlLnNnbWwgYi9kb2Mv
c3JjL3NnbWwvcmVmL2NyZWF0ZV90YWJsZS5zZ21sCmluZGV4IDBhM2U1MjBmMjE1Li43M2YxOGQ2
YjMzMSAxMDA2NDQKLS0tIGEvZG9jL3NyYy9zZ21sL3JlZi9jcmVhdGVfdGFibGUuc2dtbAorKysg
Yi9kb2Mvc3JjL3NnbWwvcmVmL2NyZWF0ZV90YWJsZS5zZ21sCkBAIC0yMSw4ICsyMSw4IEBAIFBv
c3RncmVTUUwgZG9jdW1lbnRhdGlvbgogCiAgPHJlZnN5bm9wc2lzZGl2PgogPHN5bm9wc2lzPgot
Q1JFQVRFIFsgWyBHTE9CQUwgfCBMT0NBTCBdIHsgVEVNUE9SQVJZIHwgVEVNUCB9IHwgVU5MT0dH
RUQgXSBUQUJMRSBbIElGIE5PVCBFWElTVFMgXSA8cmVwbGFjZWFibGUgY2xhc3M9InBhcmFtZXRl
ciI+dGFibGVfbmFtZTwvcmVwbGFjZWFibGU+ICggWwotICB7IDxyZXBsYWNlYWJsZSBjbGFzcz0i
cGFyYW1ldGVyIj5jb2x1bW5fbmFtZTwvcmVwbGFjZWFibGU+IDxyZXBsYWNlYWJsZSBjbGFzcz0i
cGFyYW1ldGVyIj5kYXRhX3R5cGU8L3JlcGxhY2VhYmxlPiBbIFNUT1JBR0UgeyBQTEFJTiB8IEVY
VEVSTkFMIHwgRVhURU5ERUQgfCBNQUlOIHwgREVGQVVMVCB9IF0gWyBDT01QUkVTU0lPTiA8cmVw
bGFjZWFibGU+Y29tcHJlc3Npb25fbWV0aG9kPC9yZXBsYWNlYWJsZT4gXSBbIENPTExBVEUgPHJl
cGxhY2VhYmxlPmNvbGxhdGlvbjwvcmVwbGFjZWFibGU+IF0gWyA8cmVwbGFjZWFibGUgY2xhc3M9
InBhcmFtZXRlciI+Y29sdW1uX2NvbnN0cmFpbnQ8L3JlcGxhY2VhYmxlPiBbIC4uLiBdIF0KK0NS
RUFURSBbIDxyZXBsYWNlYWJsZT5wZXJzaXN0ZW5jZV9tb2RlPC9yZXBsYWNlYWJsZT4gXSBUQUJM
RSBbIElGIE5PVCBFWElTVFMgXSA8cmVwbGFjZWFibGUgY2xhc3M9InBhcmFtZXRlciI+dGFibGVf
bmFtZTwvcmVwbGFjZWFibGU+ICggWworICB7IDxyZXBsYWNlYWJsZSBjbGFzcz0icGFyYW1ldGVy
Ij5jb2x1bW5fbmFtZTwvcmVwbGFjZWFibGU+IDxyZXBsYWNlYWJsZSBjbGFzcz0icGFyYW1ldGVy
Ij5kYXRhX3R5cGU8L3JlcGxhY2VhYmxlPiBbIDxyZXBsYWNlYWJsZT5vdmVyc2l6ZV9zdG9yYWdl
PC9yZXBsYWNlYWJsZT4gXSBbIENPTExBVEUgPHJlcGxhY2VhYmxlPmNvbGxhdGlvbjwvcmVwbGFj
ZWFibGU+IF0gWyA8cmVwbGFjZWFibGUgY2xhc3M9InBhcmFtZXRlciI+Y29sdW1uX2NvbnN0cmFp
bnQ8L3JlcGxhY2VhYmxlPiBbIC4uLiBdIF0KICAgICB8IDxyZXBsYWNlYWJsZT50YWJsZV9jb25z
dHJhaW50PC9yZXBsYWNlYWJsZT4KICAgICB8IExJS0UgPHJlcGxhY2VhYmxlPnNvdXJjZV90YWJs
ZTwvcmVwbGFjZWFibGU+IFsgPHJlcGxhY2VhYmxlPmxpa2Vfb3B0aW9uPC9yZXBsYWNlYWJsZT4g
Li4uIF0gfQogICAgIFssIC4uLiBdCkBAIC0zNCw3ICszNCw3IEBAIENSRUFURSBbIFsgR0xPQkFM
IHwgTE9DQUwgXSB7IFRFTVBPUkFSWSB8IFRFTVAgfSB8IFVOTE9HR0VEIF0gVEFCTEUgWyBJRiBO
T1QgRVhJCiBbIE9OIENPTU1JVCB7IFBSRVNFUlZFIFJPV1MgfCBERUxFVEUgUk9XUyB8IERST1Ag
fSBdCiBbIFRBQkxFU1BBQ0UgPHJlcGxhY2VhYmxlIGNsYXNzPSJwYXJhbWV0ZXIiPnRhYmxlc3Bh
Y2VfbmFtZTwvcmVwbGFjZWFibGU+IF0KIAotQ1JFQVRFIFsgWyBHTE9CQUwgfCBMT0NBTCBdIHsg
VEVNUE9SQVJZIHwgVEVNUCB9IHwgVU5MT0dHRUQgXSBUQUJMRSBbIElGIE5PVCBFWElTVFMgXSA8
cmVwbGFjZWFibGUgY2xhc3M9InBhcmFtZXRlciI+dGFibGVfbmFtZTwvcmVwbGFjZWFibGU+CitD
UkVBVEUgWyA8cmVwbGFjZWFibGU+cGVyc2lzdGVuY2VfbW9kZTwvcmVwbGFjZWFibGU+IF0gVEFC
TEUgWyBJRiBOT1QgRVhJU1RTIF0gPHJlcGxhY2VhYmxlIGNsYXNzPSJwYXJhbWV0ZXIiPnRhYmxl
X25hbWU8L3JlcGxhY2VhYmxlPgogICAgIE9GIDxyZXBsYWNlYWJsZSBjbGFzcz0icGFyYW1ldGVy
Ij50eXBlX25hbWU8L3JlcGxhY2VhYmxlPiBbICgKICAgeyA8cmVwbGFjZWFibGUgY2xhc3M9InBh
cmFtZXRlciI+Y29sdW1uX25hbWU8L3JlcGxhY2VhYmxlPiBbIFdJVEggT1BUSU9OUyBdIFsgPHJl
cGxhY2VhYmxlIGNsYXNzPSJwYXJhbWV0ZXIiPmNvbHVtbl9jb25zdHJhaW50PC9yZXBsYWNlYWJs
ZT4gWyAuLi4gXSBdCiAgICAgfCA8cmVwbGFjZWFibGU+dGFibGVfY29uc3RyYWludDwvcmVwbGFj
ZWFibGU+IH0KQEAgLTQ2LDcgKzQ2LDcgQEAgQ1JFQVRFIFsgWyBHTE9CQUwgfCBMT0NBTCBdIHsg
VEVNUE9SQVJZIHwgVEVNUCB9IHwgVU5MT0dHRUQgXSBUQUJMRSBbIElGIE5PVCBFWEkKIFsgT04g
Q09NTUlUIHsgUFJFU0VSVkUgUk9XUyB8IERFTEVURSBST1dTIHwgRFJPUCB9IF0KIFsgVEFCTEVT
UEFDRSA8cmVwbGFjZWFibGUgY2xhc3M9InBhcmFtZXRlciI+dGFibGVzcGFjZV9uYW1lPC9yZXBs
YWNlYWJsZT4gXQogCi1DUkVBVEUgWyBbIEdMT0JBTCB8IExPQ0FMIF0geyBURU1QT1JBUlkgfCBU
RU1QIH0gfCBVTkxPR0dFRCBdIFRBQkxFIFsgSUYgTk9UIEVYSVNUUyBdIDxyZXBsYWNlYWJsZSBj
bGFzcz0icGFyYW1ldGVyIj50YWJsZV9uYW1lPC9yZXBsYWNlYWJsZT4KK0NSRUFURSBbIDxyZXBs
YWNlYWJsZT5wZXJzaXN0ZW5jZV9tb2RlPC9yZXBsYWNlYWJsZT4gXSBUQUJMRSBbIElGIE5PVCBF
WElTVFMgXSA8cmVwbGFjZWFibGUgY2xhc3M9InBhcmFtZXRlciI+dGFibGVfbmFtZTwvcmVwbGFj
ZWFibGU+CiAgICAgUEFSVElUSU9OIE9GIDxyZXBsYWNlYWJsZSBjbGFzcz0icGFyYW1ldGVyIj5w
YXJlbnRfdGFibGU8L3JlcGxhY2VhYmxlPiBbICgKICAgeyA8cmVwbGFjZWFibGUgY2xhc3M9InBh
cmFtZXRlciI+Y29sdW1uX25hbWU8L3JlcGxhY2VhYmxlPiBbIFdJVEggT1BUSU9OUyBdIFsgPHJl
cGxhY2VhYmxlIGNsYXNzPSJwYXJhbWV0ZXIiPmNvbHVtbl9jb25zdHJhaW50PC9yZXBsYWNlYWJs
ZT4gWyAuLi4gXSBdCiAgICAgfCA8cmVwbGFjZWFibGU+dGFibGVfY29uc3RyYWludDwvcmVwbGFj
ZWFibGU+IH0KQEAgLTU4LDcgKzU4LDE2IEBAIENSRUFURSBbIFsgR0xPQkFMIHwgTE9DQUwgXSB7
IFRFTVBPUkFSWSB8IFRFTVAgfSB8IFVOTE9HR0VEIF0gVEFCTEUgWyBJRiBOT1QgRVhJCiBbIE9O
IENPTU1JVCB7IFBSRVNFUlZFIFJPV1MgfCBERUxFVEUgUk9XUyB8IERST1AgfSBdCiBbIFRBQkxF
U1BBQ0UgPHJlcGxhY2VhYmxlIGNsYXNzPSJwYXJhbWV0ZXIiPnRhYmxlc3BhY2VfbmFtZTwvcmVw
bGFjZWFibGU+IF0KIAotPHBocmFzZT53aGVyZSA8cmVwbGFjZWFibGUgY2xhc3M9InBhcmFtZXRl
ciI+Y29sdW1uX2NvbnN0cmFpbnQ8L3JlcGxhY2VhYmxlPiBpczo8L3BocmFzZT4KKzxwaHJhc2U+
d2hlcmUgPHJlcGxhY2VhYmxlPnBlcnNpc3RlbmNlX21vZGU8L3JlcGxhY2VhYmxlPiBpczogPC9w
aHJhc2U+CisKK1sgR0xPQkFMIHwgTE9DQUwgXSB7IFRFTVBPUkFSWSB8IFRFTVAgfSB8CitVTkxP
R0dFRAorCis8cGhyYXNlPmFuZCA8cmVwbGFjZWFibGU+b3ZlcnNpemVfc3RvcmFnZTwvcmVwbGFj
ZWFibGU+IGlzOjwvcGhyYXNlPgorCitTVE9SQUdFIHsgUExBSU4gfCBFWFRFUk5BTCB8IEVYVEVO
REVEIHwgTUFJTiB8IERFRkFVTFQgfSBbIENPTVBSRVNTSU9OIDxyZXBsYWNlYWJsZT5jb21wcmVz
c2lvbl9tZXRob2Q8L3JlcGxhY2VhYmxlPiBdCisKKzxwaHJhc2U+YW5kIDxyZXBsYWNlYWJsZSBj
bGFzcz0icGFyYW1ldGVyIj5jb2x1bW5fY29uc3RyYWludDwvcmVwbGFjZWFibGU+IGlzOjwvcGhy
YXNlPgogCiBbIENPTlNUUkFJTlQgPHJlcGxhY2VhYmxlIGNsYXNzPSJwYXJhbWV0ZXIiPmNvbnN0
cmFpbnRfbmFtZTwvcmVwbGFjZWFibGU+IF0KIHsgTk9UIE5VTEwgWyBOTyBJTkhFUklUIF0gIHwK
QEAgLTEyMyw2ICsxMzIsMTQgQEAgV0lUSCAoIE1PRFVMVVMgPHJlcGxhY2VhYmxlIGNsYXNzPSJw
YXJhbWV0ZXIiPm51bWVyaWNfbGl0ZXJhbDwvcmVwbGFjZWFibGU+LCBSRU0KICAgIGNvbW1hbmQu
CiAgIDwvcGFyYT4KIAorICA8cGFyYT4KKyAgIFRoZSBkdXJhYmlsaXR5IGNoYXJhY3RlcmlzdGlj
cyBvZiBhIHRhYmxlIGFyZSBnb3Zlcm5lZCBieSBpdHMgcGVyc2lzdGVuY2UKKyAgIG1vZGUuICBJ
ZiBub25lIGlzIHNwZWNpZmllZCwgdGhlIGRhdGEgd2lsbCBiZSBwZXJzaXN0ZW50IGFuZCBjcmFz
aC1zYWZlLgorICAgRm9yIGxlc3Mgc3RyaW5nZW50IHJlcXVpcmVtZW50cyBhbmQgYmV0dGVyIHBl
cmZvcm1hbmNlLCBhIHRhYmxlIGNhbiBiZQorICAgc3BlY2lmaWVkIGFzIDxsaW5rIGxpbmtlbmQ9
InNxbC1jcmVhdGV0YWJsZS10ZW1wb3JhcnkiPnRlbXBvcmFyeTwvbGluaz4KKyAgIG9yIDxsaW5r
IGxpbmtlbmQ9InNxbC1jcmVhdGV0YWJsZS11bmxvZ2dlZCI+dW5sb2dnZWQ8L2xpbms+LgorICA8
L3BhcmE+CisKICAgPHBhcmE+CiAgICBJZiBhIHNjaGVtYSBuYW1lIGlzIGdpdmVuIChmb3IgZXhh
bXBsZSwgPGxpdGVyYWw+Q1JFQVRFIFRBQkxFCiAgICBteXNjaGVtYS5teXRhYmxlIC4uLjwvbGl0
ZXJhbD4pIHRoZW4gdGhlIHRhYmxlIGlzIGNyZWF0ZWQgaW4gdGhlIHNwZWNpZmllZAotLSAKMi40
OC4xCgo=


--=-SBYb+Bawm4vDzxzB2Zn9--