public inbox for [email protected]
help / color / mirror / Atom feedFrom: Laurenz Albe <[email protected]>
To: jian he <[email protected]>
Cc: David G. Johnston <[email protected]>
Cc: Peter Eisentraut <[email protected]>
Cc: PostgreSQL Hackers <[email protected]>
Subject: Re: doc: create table improvements
Date: Thu, 16 Oct 2025 15:19:32 +0200
Message-ID: <[email protected]> (raw)
In-Reply-To: <CACJufxFgZtLENzJkZZssKdWEfHo1hk9uyC0h3JcGJJb19XRJQQ@mail.gmail.com>
References: <CAKFQuwYfMV-2SdrP-umr5SVNSqTn378BUvHsebetp5=DhT494w@mail.gmail.com>
<[email protected]>
<CAKFQuwYk7NsEAEsPEUdbc_gXB0OR+gZzmBjDcUSe5JZuE+d_iw@mail.gmail.com>
<[email protected]>
<CACJufxFgZtLENzJkZZssKdWEfHo1hk9uyC0h3JcGJJb19XRJQQ@mail.gmail.com>
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
Attachments:
[text/x-patch] v3-0001-Unclutter-CREATE-TABLE-synopsis.patch (5.8K, 2-v3-0001-Unclutter-CREATE-TABLE-synopsis.patch)
download | inline diff:
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
view thread (15+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected], [email protected], [email protected], [email protected]
Subject: Re: doc: create table improvements
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox