Обсуждение: doc: create table improvements
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.
Вложения
> + 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.
On Wed, Apr 24, 2024 at 3:30 AM Peter Eisentraut <peter@eisentraut.org> 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.
On Wed, Apr 24, 2024 at 7:45 AM David G. Johnston <david.g.johnston@gmail.com> wrote:
On Wed, Apr 24, 2024 at 3:30 AM Peter Eisentraut <peter@eisentraut.org> 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.
Or maybe:
A table operates in one of three persistence modes (default, [temporary], and [unlogged]) described in [Chapter 28]. --point to the intro page for the chapter as expanded as below, not the reliability page.
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index 05e2a8f8be..102cfeca68 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -5,8 +5,17 @@
<para>
This chapter explains how to control the reliability of
- <productname>PostgreSQL</productname>, including details about the
- Write-Ahead Log.
+ <productname>PostgreSQL</productname>. At its core this
+ involves writing all changes to disk twice - first to a
+ journal of changes called the write-ahead-log (WAL) and
+ then to the physical pages that comprise permanent tables
+ on disk (heap). This results in four high-level
+ <term>persistence modes</term> for tables.
+ The default mode results in both these features being
+ enabled. Temporary tables forgo both of these options,
+ while unlogged tables only forgo WAL. There is no WAL-only
+ operating mode. The rest of this chapter discusses
+ implementation details related to these two options.
</para>
index 05e2a8f8be..102cfeca68 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -5,8 +5,17 @@
<para>
This chapter explains how to control the reliability of
- <productname>PostgreSQL</productname>, including details about the
- Write-Ahead Log.
+ <productname>PostgreSQL</productname>. At its core this
+ involves writing all changes to disk twice - first to a
+ journal of changes called the write-ahead-log (WAL) and
+ then to the physical pages that comprise permanent tables
+ on disk (heap). This results in four high-level
+ <term>persistence modes</term> for tables.
+ The default mode results in both these features being
+ enabled. Temporary tables forgo both of these options,
+ while unlogged tables only forgo WAL. There is no WAL-only
+ operating mode. The rest of this chapter discusses
+ implementation details related to these two options.
</para>
David J.
On Wed, 2024-04-24 at 07:45 -0700, David G. Johnston wrote:
> On Wed, Apr 24, 2024 at 3:30 AM Peter Eisentraut <peter@eisentraut.org> 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
Вложения
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"``.
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
Вложения
> On 16 Oct 2025, at 15:19, Laurenz Albe <laurenz.albe@cybertec.at> 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
Daniel Gustafsson <daniel@yesql.se> 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