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
From e375044d55809d239be33f31c4efa8410790d3f0 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johns...@gmail.com>
Date: Mon, 22 Apr 2024 11:51:53 -0700
Subject: [PATCH] doc: create table doc enhancements
---
doc/src/sgml/ref/create_table.sgml | 37 +++++++++++++++++++++++++-----
1 file changed, 31 insertions(+), 6 deletions(-)
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
@@ -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>column_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>column_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 |
@@ -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>
+ <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>
+
<para>
If a schema name is given (for example, <literal>CREATE TABLE
myschema.mytable ...</literal>) then the table is created in the specified
@@ -221,6 +240,12 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
If this is specified, any sequences created together with the unlogged
table (for identity or serial columns) are also created as unlogged.
</para>
+
+ <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>
</listitem>
</varlistentry>
--
2.34.1
