public inbox for [email protected]
help / color / mirror / Atom feeddoc: create table improvements
15+ messages / 7 participants
[nested] [flat]
* doc: create table improvements
@ 2024-04-22 19:19 David G. Johnston <[email protected]>
2024-04-24 10:30 ` Re: doc: create table improvements Peter Eisentraut <[email protected]>
0 siblings, 1 reply; 15+ messages in thread
From: David G. Johnston @ 2024-04-22 19:19 UTC (permalink / raw)
To: PostgreSQL Hackers <[email protected]>
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
Attachments:
[text/x-patch] 0001-doc-create-table-doc-enhancements.patch (5.5K, 3-0001-doc-create-table-doc-enhancements.patch)
download | inline diff:
From e375044d55809d239be33f31c4efa8410790d3f0 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <[email protected]>
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
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: doc: create table improvements
2024-04-22 19:19 doc: create table improvements David G. Johnston <[email protected]>
@ 2024-04-24 10:30 ` Peter Eisentraut <[email protected]>
2024-04-24 14:45 ` Re: doc: create table improvements David G. Johnston <[email protected]>
0 siblings, 1 reply; 15+ messages in thread
From: Peter Eisentraut @ 2024-04-24 10:30 UTC (permalink / raw)
To: David G. Johnston <[email protected]>; PostgreSQL Hackers <[email protected]>
> + 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.
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: doc: create table improvements
2024-04-22 19:19 doc: create table improvements David G. Johnston <[email protected]>
2024-04-24 10:30 ` Re: doc: create table improvements Peter Eisentraut <[email protected]>
@ 2024-04-24 14:45 ` David G. Johnston <[email protected]>
2025-02-28 13:56 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
0 siblings, 1 reply; 15+ messages in thread
From: David G. Johnston @ 2024-04-24 14:45 UTC (permalink / raw)
To: Peter Eisentraut <[email protected]>; +Cc: PostgreSQL Hackers <[email protected]>
On Wed, Apr 24, 2024 at 3:30 AM Peter Eisentraut <[email protected]>
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. But better framing and phrasing I can
do:
A table may be opted out of certain storage aspects of reliability, as
described [here], by specifying either of the alternate persistence modes:
[temporary] or [logged]. The specific trade-offs and implications are
detailed below.
David J.
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: doc: create table improvements
2024-04-22 19:19 doc: create table improvements David G. Johnston <[email protected]>
2024-04-24 10:30 ` Re: doc: create table improvements Peter Eisentraut <[email protected]>
2024-04-24 14:45 ` Re: doc: create table improvements David G. Johnston <[email protected]>
@ 2025-02-28 13:56 ` Laurenz Albe <[email protected]>
2025-10-16 03:28 ` Re: doc: create table improvements jian he <[email protected]>
0 siblings, 1 reply; 15+ messages in thread
From: Laurenz Albe @ 2025-02-28 13:56 UTC (permalink / raw)
To: David G. Johnston <[email protected]>; Peter Eisentraut <[email protected]>; +Cc: PostgreSQL Hackers <[email protected]>
On Wed, 2024-04-24 at 07:45 -0700, David G. Johnston wrote:
> On Wed, Apr 24, 2024 at 3:30 AM Peter Eisentraut <[email protected]> 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
Attachments:
[text/x-patch] v2-0001-Unclutter-CREATE-TABLE-synopsis.patch (5.0K, 2-v2-0001-Unclutter-CREATE-TABLE-synopsis.patch)
download | inline diff:
From 338dfb52d83d0f9c07421641a0111a2f8e63b34e Mon Sep 17 00:00:00 2001
From: Laurenz Albe <[email protected]>
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
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: doc: create table improvements
2024-04-22 19:19 doc: create table improvements David G. Johnston <[email protected]>
2024-04-24 10:30 ` Re: doc: create table improvements Peter Eisentraut <[email protected]>
2024-04-24 14:45 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-02-28 13:56 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
@ 2025-10-16 03:28 ` jian he <[email protected]>
2025-10-16 13:19 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
0 siblings, 1 reply; 15+ messages in thread
From: jian he @ 2025-10-16 03:28 UTC (permalink / raw)
To: Laurenz Albe <[email protected]>; +Cc: David G. Johnston <[email protected]>; Peter Eisentraut <[email protected]>; PostgreSQL Hackers <[email protected]>
hi.
-<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
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"``.
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: doc: create table improvements
2024-04-22 19:19 doc: create table improvements David G. Johnston <[email protected]>
2024-04-24 10:30 ` Re: doc: create table improvements Peter Eisentraut <[email protected]>
2024-04-24 14:45 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-02-28 13:56 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-16 03:28 ` Re: doc: create table improvements jian he <[email protected]>
@ 2025-10-16 13:19 ` Laurenz Albe <[email protected]>
2025-10-16 13:36 ` Re: doc: create table improvements Daniel Gustafsson <[email protected]>
2025-10-20 09:23 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
0 siblings, 2 replies; 15+ messages in thread
From: Laurenz Albe @ 2025-10-16 13:19 UTC (permalink / raw)
To: jian he <[email protected]>; +Cc: David G. Johnston <[email protected]>; Peter Eisentraut <[email protected]>; PostgreSQL Hackers <[email protected]>
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
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: doc: create table improvements
2024-04-22 19:19 doc: create table improvements David G. Johnston <[email protected]>
2024-04-24 10:30 ` Re: doc: create table improvements Peter Eisentraut <[email protected]>
2024-04-24 14:45 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-02-28 13:56 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-16 03:28 ` Re: doc: create table improvements jian he <[email protected]>
2025-10-16 13:19 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
@ 2025-10-16 13:36 ` Daniel Gustafsson <[email protected]>
2025-10-16 15:01 ` Re: doc: create table improvements Tom Lane <[email protected]>
1 sibling, 1 reply; 15+ messages in thread
From: Daniel Gustafsson @ 2025-10-16 13:36 UTC (permalink / raw)
To: Laurenz Albe <[email protected]>; +Cc: jian he <[email protected]>; David G. Johnston <[email protected]>; Peter Eisentraut <[email protected]>; PostgreSQL Hackers <[email protected]>
> On 16 Oct 2025, at 15:19, Laurenz Albe <[email protected]> wrote:
> On Thu, 2025-10-16 at 11:28 +0800, jian he wrote:
>> I don't know the purpose of this extra ``"class="parameter"``.
>
> I don't know either. I guess it makes no visible difference.
It's simply markup defined by DocBook to indicate what type the content to be
replaced is, in this case a parameter. While it might not make any visual
difference in our rendering, someone might be rendering the docs in another way
where it does show a difference (like using a different font or decoration to
differentiate parameters from functions etc).
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: doc: create table improvements
2024-04-22 19:19 doc: create table improvements David G. Johnston <[email protected]>
2024-04-24 10:30 ` Re: doc: create table improvements Peter Eisentraut <[email protected]>
2024-04-24 14:45 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-02-28 13:56 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-16 03:28 ` Re: doc: create table improvements jian he <[email protected]>
2025-10-16 13:19 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-16 13:36 ` Re: doc: create table improvements Daniel Gustafsson <[email protected]>
@ 2025-10-16 15:01 ` Tom Lane <[email protected]>
0 siblings, 0 replies; 15+ messages in thread
From: Tom Lane @ 2025-10-16 15:01 UTC (permalink / raw)
To: Daniel Gustafsson <[email protected]>; +Cc: Laurenz Albe <[email protected]>; jian he <[email protected]>; David G. Johnston <[email protected]>; Peter Eisentraut <[email protected]>; PostgreSQL Hackers <[email protected]>
Daniel Gustafsson <[email protected]> writes:
> It's simply markup defined by DocBook to indicate what type the content to be
> replaced is, in this case a parameter. While it might not make any visual
> difference in our rendering, someone might be rendering the docs in another way
> where it does show a difference (like using a different font or decoration to
> differentiate parameters from functions etc).
That's the theory anyway. But we've been so massively inconsistent
in whether to use class markup or not (no doubt exactly because it
makes no difference for us) that I would expect a rendering where
it does make a difference to look really awful.
regards, tom lane
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: doc: create table improvements
2024-04-22 19:19 doc: create table improvements David G. Johnston <[email protected]>
2024-04-24 10:30 ` Re: doc: create table improvements Peter Eisentraut <[email protected]>
2024-04-24 14:45 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-02-28 13:56 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-16 03:28 ` Re: doc: create table improvements jian he <[email protected]>
2025-10-16 13:19 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
@ 2025-10-20 09:23 ` Laurenz Albe <[email protected]>
2025-10-20 11:41 ` Re: doc: create table improvements David G. Johnston <[email protected]>
1 sibling, 1 reply; 15+ messages in thread
From: Laurenz Albe @ 2025-10-20 09:23 UTC (permalink / raw)
To: David G. Johnston <[email protected]>; +Cc: Peter Eisentraut <[email protected]>; PostgreSQL Hackers <[email protected]>; jian he <[email protected]>
On Thu, 2025-10-16 at 15:19 +0200, Laurenz Albe wrote:
> Attached is version 3.
David, do you as the original patch author want to comment?
The patch is "waiting for author".
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: doc: create table improvements
2024-04-22 19:19 doc: create table improvements David G. Johnston <[email protected]>
2024-04-24 10:30 ` Re: doc: create table improvements Peter Eisentraut <[email protected]>
2024-04-24 14:45 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-02-28 13:56 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-16 03:28 ` Re: doc: create table improvements jian he <[email protected]>
2025-10-16 13:19 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-20 09:23 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
@ 2025-10-20 11:41 ` David G. Johnston <[email protected]>
2025-10-23 04:43 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
0 siblings, 1 reply; 15+ messages in thread
From: David G. Johnston @ 2025-10-20 11:41 UTC (permalink / raw)
To: Laurenz Albe <[email protected]>; +Cc: Peter Eisentraut <[email protected]>; PostgreSQL Hackers <[email protected]>; jian he <[email protected]>
On Monday, October 20, 2025, Laurenz Albe <[email protected]> wrote:
> On Thu, 2025-10-16 at 15:19 +0200, Laurenz Albe wrote:
> > Attached is version 3.
>
> David, do you as the original patch author want to comment?
> The patch is "waiting for author".
>
Thanks,
I question whether “parameter” is even the correct class to assign here and
so would rather avoid the issue by not assigning a class.
“If none is specified, the data will be persistent” would be better written
“If unspecified the data will be persistent” (or, “if not specified…”)
Everything else looks good.
David J.
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: doc: create table improvements
2024-04-22 19:19 doc: create table improvements David G. Johnston <[email protected]>
2024-04-24 10:30 ` Re: doc: create table improvements Peter Eisentraut <[email protected]>
2024-04-24 14:45 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-02-28 13:56 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-16 03:28 ` Re: doc: create table improvements jian he <[email protected]>
2025-10-16 13:19 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-20 09:23 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-20 11:41 ` Re: doc: create table improvements David G. Johnston <[email protected]>
@ 2025-10-23 04:43 ` Laurenz Albe <[email protected]>
2025-12-16 01:44 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-12-16 02:14 ` Re: doc: create table improvements Chao Li <[email protected]>
0 siblings, 2 replies; 15+ messages in thread
From: Laurenz Albe @ 2025-10-23 04:43 UTC (permalink / raw)
To: David G. Johnston <[email protected]>; +Cc: Peter Eisentraut <[email protected]>; PostgreSQL Hackers <[email protected]>; jian he <[email protected]>
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
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: doc: create table improvements
2024-04-22 19:19 doc: create table improvements David G. Johnston <[email protected]>
2024-04-24 10:30 ` Re: doc: create table improvements Peter Eisentraut <[email protected]>
2024-04-24 14:45 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-02-28 13:56 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-16 03:28 ` Re: doc: create table improvements jian he <[email protected]>
2025-10-16 13:19 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-20 09:23 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-20 11:41 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-10-23 04:43 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
@ 2025-12-16 01:44 ` David G. Johnston <[email protected]>
1 sibling, 0 replies; 15+ messages in thread
From: David G. Johnston @ 2025-12-16 01:44 UTC (permalink / raw)
To: Laurenz Albe <[email protected]>; +Cc: Peter Eisentraut <[email protected]>; PostgreSQL Hackers <[email protected]>; jian he <[email protected]>
On Wed, Oct 22, 2025 at 9:43 PM Laurenz Albe <[email protected]>
wrote:
> Patch attached; if it is fine with you, I'll mark it "ready for committer".
>
>
Thank you. It works for me. I've moved the CF entry to the current CF and
marked it ready for committer.
David J.
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: doc: create table improvements
2024-04-22 19:19 doc: create table improvements David G. Johnston <[email protected]>
2024-04-24 10:30 ` Re: doc: create table improvements Peter Eisentraut <[email protected]>
2024-04-24 14:45 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-02-28 13:56 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-16 03:28 ` Re: doc: create table improvements jian he <[email protected]>
2025-10-16 13:19 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-20 09:23 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-20 11:41 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-10-23 04:43 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
@ 2025-12-16 02:14 ` Chao Li <[email protected]>
2025-12-16 10:25 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
1 sibling, 1 reply; 15+ messages in thread
From: Chao Li @ 2025-12-16 02:14 UTC (permalink / raw)
To: Laurenz Albe <[email protected]>; +Cc: David G. Johnston <[email protected]>; Peter Eisentraut <[email protected]>; PostgreSQL Hackers <[email protected]>; jian he <[email protected]>
> On Oct 23, 2025, at 12:43, Laurenz Albe <[email protected]> wrote:
>
> 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
> <v4-0001-Unclutter-CREATE-TABLE-synopsis.patch>
Overall the change looks good to me. I have only one comment about the naming of “oversize_storage”. Why not just “storage_parameters” or similar that sounds more straightforward?
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: doc: create table improvements
2024-04-22 19:19 doc: create table improvements David G. Johnston <[email protected]>
2024-04-24 10:30 ` Re: doc: create table improvements Peter Eisentraut <[email protected]>
2024-04-24 14:45 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-02-28 13:56 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-16 03:28 ` Re: doc: create table improvements jian he <[email protected]>
2025-10-16 13:19 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-20 09:23 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-20 11:41 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-10-23 04:43 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-12-16 02:14 ` Re: doc: create table improvements Chao Li <[email protected]>
@ 2025-12-16 10:25 ` Laurenz Albe <[email protected]>
2026-03-26 21:50 ` Re: doc: create table improvements David G. Johnston <[email protected]>
0 siblings, 1 reply; 15+ messages in thread
From: Laurenz Albe @ 2025-12-16 10:25 UTC (permalink / raw)
To: Chao Li <[email protected]>; +Cc: David G. Johnston <[email protected]>; Peter Eisentraut <[email protected]>; PostgreSQL Hackers <[email protected]>; jian he <[email protected]>
On Tue, 2025-12-16 at 10:14 +0800, Chao Li wrote:
> > On Oct 23, 2025, at 12:43, Laurenz Albe <[email protected]> wrote:
> > <v4-0001-Unclutter-CREATE-TABLE-synopsis.patch>
>
> Overall the change looks good to me. I have only one comment about the naming
> of “oversize_storage”. Why not just “storage_parameters” or similar that
> sounds more straightforward?
"Storage parameter" is not a good idea, because we use that term for
something else: CREATE TABLE ... WITH (storage_parameter = value)
I think "oversize_storage" expresses well what is regulated here.
I'm open to "toast_options" or similar as an alternative, but I think
it might be better to avoid jargon - not everybody reading that page
will be familiar with the term.
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 15+ messages in thread
* Re: doc: create table improvements
2024-04-22 19:19 doc: create table improvements David G. Johnston <[email protected]>
2024-04-24 10:30 ` Re: doc: create table improvements Peter Eisentraut <[email protected]>
2024-04-24 14:45 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-02-28 13:56 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-16 03:28 ` Re: doc: create table improvements jian he <[email protected]>
2025-10-16 13:19 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-20 09:23 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-10-20 11:41 ` Re: doc: create table improvements David G. Johnston <[email protected]>
2025-10-23 04:43 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
2025-12-16 02:14 ` Re: doc: create table improvements Chao Li <[email protected]>
2025-12-16 10:25 ` Re: doc: create table improvements Laurenz Albe <[email protected]>
@ 2026-03-26 21:50 ` David G. Johnston <[email protected]>
0 siblings, 0 replies; 15+ messages in thread
From: David G. Johnston @ 2026-03-26 21:50 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: Laurenz Albe <[email protected]>; Chao Li <[email protected]>; Peter Eisentraut <[email protected]>; PostgreSQL Hackers <[email protected]>; jian he <[email protected]>
On Thursday, March 26, 2026, Tom Lane <[email protected]> wrote:
>
>
> This does make the first-quoted synopsis line a little longer than
> David had it, but it's still not any longer than several other
> lines in the CREATE TABLE synopsis. So let's call it good and
> not let line length minimization push us into a confusing grammar.
Makes sense.
>
> Pushed like that.
Thank you.
David J.
^ permalink raw reply [nested|flat] 15+ messages in thread
end of thread, other threads:[~2026-03-26 21:50 UTC | newest]
Thread overview: 15+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2024-04-22 19:19 doc: create table improvements David G. Johnston <[email protected]>
2024-04-24 10:30 ` Peter Eisentraut <[email protected]>
2024-04-24 14:45 ` David G. Johnston <[email protected]>
2025-02-28 13:56 ` Laurenz Albe <[email protected]>
2025-10-16 03:28 ` jian he <[email protected]>
2025-10-16 13:19 ` Laurenz Albe <[email protected]>
2025-10-16 13:36 ` Daniel Gustafsson <[email protected]>
2025-10-16 15:01 ` Tom Lane <[email protected]>
2025-10-20 09:23 ` Laurenz Albe <[email protected]>
2025-10-20 11:41 ` David G. Johnston <[email protected]>
2025-10-23 04:43 ` Laurenz Albe <[email protected]>
2025-12-16 01:44 ` David G. Johnston <[email protected]>
2025-12-16 02:14 ` Chao Li <[email protected]>
2025-12-16 10:25 ` Laurenz Albe <[email protected]>
2026-03-26 21:50 ` David G. Johnston <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox