On Wed, 2024-04-24 at 07:45 -0700, David G. Johnston wrote:
> On Wed, Apr 24, 2024 at 3:30 AM Peter Eisentraut <peter@eisentraut.org> wrote:
> > > + The reliability characteristics of a table are governed by its
> > > + persistence mode. The default mode is described
> > > + <link linkend="wal-reliability">here</link>
> > > + There are two alternative modes that can be specified during
> > > + table creation:
> > > + <link linkend="sql-createtable-temporary">temporary</link> and
> > > + <link linkend="sql-createtable-unlogged">unlogged</link>.
> >
> > Not sure reliability is the best word here. I mean, a temporary table
> > isn't any less reliable than any other table. It just does different
> > things.
>
> Given the name of the section where this is all discussed I'm having trouble
> going with a different word.
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="parameter">numeric_literal</replaceable>, REM
<title>Description</title>
<para>
- <command>CREATE TABLE</command> will create a new, initially empty table
+ <command>CREATE TABLE</command> will create a new, initially empty, table
in the current database. The table will be owned by the user issuing the
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="wal-reliability">here</link>
+ There are two alternative modes that can be specified during
+ table creation:
+ <link linkend="sql-createtable-temporary">temporary</link> and
+ <link linkend="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 ignored:
+ 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
