On Thu, 2025-10-16 at 11:28 +0800, jian he wrote:
> -<phrase>where <replaceable
> class="parameter">column_constraint</replaceable> is:</phrase>
> +<phrase>where <replaceable>persistence_mode</replaceable> is: </phrase>
> +
> +[ GLOBAL | LOCAL ] { TEMPORARY | TEMP } |
> +UNLOGGED
>
> we can just do it with one line:
> [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED
You are right; changed.
> most of the time, the patch using:
> <replaceable>persistence_mode</replaceable>
> <replaceable>oversize_storage</replaceable>
>
> for column_constraint we are using
> <replaceable class="parameter">column_constraint</replaceable>
>
> do we need change it to
> <replaceable class="parameter">persistence_mode</replaceable>
> <replaceable class="parameter">oversize_storage</replaceable>
> ?
>
> I don't know the purpose of this extra ``"class="parameter"``.
I don't know either. I guess it makes no visible difference.
Anyway, I had a try to establish some consistency in using that
attribute, but had to give up. There is no rhyme and reason for
me. All I did was label <replaceable>parent_table</replaceable>
and <replaceable>source_table</replaceable> with class="parameter",
since that seemed appropriate.
I left the rest alone, any massive changes in that area would make
the patch rather noisy.
Attached is version 3.
Yours,
Laurenz Albe
From b4ae92a4ed7a6ee903686d98f6cc703265d5c231 Mon Sep 17 00:00:00 2001
From: Laurenz Albe <[email protected]>
Date: Thu, 16 Oct 2025 15:13:57 +0200
Subject: [PATCH v3] 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 <[email protected]>
Reviewed-by: Laurenz Albe <[email protected]>
Reviewed-by: Jian He <[email protected]>
Discussion: https://postgr.es/m/CAKFQuwYfMV-2SdrP-umr5SVNSqTn378BUvHsebetp5%3DDhT494w%40mail.gmail.com
---
doc/src/sgml/ref/create_table.sgml | 30 +++++++++++++++++++++++-------
1 file changed, 23 insertions(+), 7 deletions(-)
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index a157a244e4e..e46b480bcf9 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -21,20 +21,20 @@ 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 class="parameter">collation</replaceable> ] [ <replaceable>column_constraint</replaceable> [ ... ] ]
| <replaceable>table_constraint</replaceable>
- | LIKE <replaceable>source_table</replaceable> [ <replaceable>like_option</replaceable> ... ] }
+ | LIKE <replaceable class="parameter">source_table</replaceable> [ <replaceable>like_option</replaceable> ... ] }
[, ... ]
] )
-[ INHERITS ( <replaceable>parent_table</replaceable> [, ... ] ) ]
+[ INHERITS ( <replaceable class="parameter">parent_table</replaceable> [, ... ] ) ]
[ PARTITION BY { RANGE | LIST | HASH } ( { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ COLLATE <replaceable class="parameter">collation</replaceable> ] [ <replaceable class="parameter">opclass</replaceable> ] [, ... ] ) ]
[ USING <replaceable class="parameter">method</replaceable> ]
[ WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) | WITHOUT OIDS ]
[ 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,15 @@ 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 +131,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.51.0
