On Wed, 2024-04-24 at 07:45 -0700, David G. Johnston wrote:
> On Wed, Apr 24, 2024 at 3:30 AM Peter Eisentraut <pe...@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
From 338dfb52d83d0f9c07421641a0111a2f8e63b34e Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.a...@cybertec.at>
Date: Fri, 28 Feb 2025 14:36:25 +0100
Subject: [PATCH v2] Unclutter CREATE TABLE synopsis
Factor out the "persistence mode" and "oversize storage" parts
of the syntax synopsis to reduce the line length and increase
the readability.
Author: David G. Johnston
Reviewed-by: Laurenz Albe
Discussion: https://postgr.es/m/CAKFQuwYfMV-2SdrP-umr5SVNSqTn378BUvHsebetp5%3DDhT494w%40mail.gmail.com
---
doc/src/sgml/ref/create_table.sgml | 27 ++++++++++++++++++++++-----
1 file changed, 22 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index 0a3e520f215..73f18d6b331 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -21,8 +21,8 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
-CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] <replaceable class="parameter">table_name</replaceable> ( [
- { <replaceable class="parameter">column_name</replaceable> <replaceable class="parameter">data_type</replaceable> [ STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT } ] [ COMPRESSION <replaceable>compression_method</replaceable> ] [ COLLATE <replaceable>collation</replaceable> ] [ <replaceable class="parameter">column_constraint</replaceable> [ ... ] ]
+CREATE [ <replaceable>persistence_mode</replaceable> ] TABLE [ IF NOT EXISTS ] <replaceable class="parameter">table_name</replaceable> ( [
+ { <replaceable class="parameter">column_name</replaceable> <replaceable class="parameter">data_type</replaceable> [ <replaceable>oversize_storage</replaceable> ] [ COLLATE <replaceable>collation</replaceable> ] [ <replaceable class="parameter">column_constraint</replaceable> [ ... ] ]
| <replaceable>table_constraint</replaceable>
| LIKE <replaceable>source_table</replaceable> [ <replaceable>like_option</replaceable> ... ] }
[, ... ]
@@ -34,7 +34,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
[ TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
-CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] <replaceable class="parameter">table_name</replaceable>
+CREATE [ <replaceable>persistence_mode</replaceable> ] TABLE [ IF NOT EXISTS ] <replaceable class="parameter">table_name</replaceable>
OF <replaceable class="parameter">type_name</replaceable> [ (
{ <replaceable class="parameter">column_name</replaceable> [ WITH OPTIONS ] [ <replaceable class="parameter">column_constraint</replaceable> [ ... ] ]
| <replaceable>table_constraint</replaceable> }
@@ -46,7 +46,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
[ TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
-CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] <replaceable class="parameter">table_name</replaceable>
+CREATE [ <replaceable>persistence_mode</replaceable> ] TABLE [ IF NOT EXISTS ] <replaceable class="parameter">table_name</replaceable>
PARTITION OF <replaceable class="parameter">parent_table</replaceable> [ (
{ <replaceable class="parameter">column_name</replaceable> [ WITH OPTIONS ] [ <replaceable class="parameter">column_constraint</replaceable> [ ... ] ]
| <replaceable>table_constraint</replaceable> }
@@ -58,7 +58,16 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
[ TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
-<phrase>where <replaceable class="parameter">column_constraint</replaceable> is:</phrase>
+<phrase>where <replaceable>persistence_mode</replaceable> is: </phrase>
+
+[ GLOBAL | LOCAL ] { TEMPORARY | TEMP } |
+UNLOGGED
+
+<phrase>and <replaceable>oversize_storage</replaceable> is:</phrase>
+
+STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT } [ COMPRESSION <replaceable>compression_method</replaceable> ]
+
+<phrase>and <replaceable class="parameter">column_constraint</replaceable> is:</phrase>
[ CONSTRAINT <replaceable class="parameter">constraint_name</replaceable> ]
{ NOT NULL [ NO INHERIT ] |
@@ -123,6 +132,14 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
command.
</para>
+ <para>
+ The durability characteristics of a table are governed by its persistence
+ mode. If none is specified, the data will be persistent and crash-safe.
+ For less stringent requirements and better performance, a table can be
+ specified as <link linkend="sql-createtable-temporary">temporary</link>
+ or <link linkend="sql-createtable-unlogged">unlogged</link>.
+ </para>
+
<para>
If a schema name is given (for example, <literal>CREATE TABLE
myschema.mytable ...</literal>) then the table is created in the specified
--
2.48.1
