public inbox for [email protected]
help / color / mirror / Atom feedFrom: Laurenz Albe <[email protected]>
To: David G. Johnston <[email protected]>
Cc: Peter Eisentraut <[email protected]>
Cc: PostgreSQL Hackers <[email protected]>
Cc: jian he <[email protected]>
Subject: Re: doc: create table improvements
Date: Thu, 23 Oct 2025 07:43:25 +0300
Message-ID: <[email protected]> (raw)
In-Reply-To: <CAKFQuwaEo8dxUmVsmjkb4WBEtKHUazeaN1pwsbDpLsFdANDAkQ@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>
<[email protected]>
<[email protected]>
<CAKFQuwaEo8dxUmVsmjkb4WBEtKHUazeaN1pwsbDpLsFdANDAkQ@mail.gmail.com>
On Mon, 2025-10-20 at 07:41 -0400, David G. Johnston wrote:
> I question whether “parameter” is even the correct class to assign here
> and so would rather avoid the issue by not assigning a class.
Right. I have removed the vestiges from my failed attempt to improve
the "parameter" decorations.
> “If none is specified, the data will be persistent” would be better
> written “If unspecified the data will be persistent” (or, “if not specified…”)
I decided to use the trusted phrasing "by default".
> Everything else looks good.
Patch attached; if it is fine with you, I'll mark it "ready for committer".
Yours,
Laurenz Albe
Attachments:
[text/x-patch] v4-0001-Unclutter-CREATE-TABLE-synopsis.patch (5.1K, 2-v4-0001-Unclutter-CREATE-TABLE-synopsis.patch)
download | inline diff:
From 0af816233e1d7e599042fd3f6bdcbf666f8621d1 Mon Sep 17 00:00:00 2001
From: Laurenz Albe <[email protected]>
Date: Thu, 23 Oct 2025 07:40:40 +0300
Subject: [PATCH v4] 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 | 26 +++++++++++++++++++++-----
1 file changed, 21 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index a157a244e4e..44623ae9b28 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 class="parameter">collation</replaceable> ] [ <replaceable>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,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. By default, 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