Re: doc: create table improvements

On Wed, Apr 24, 2024 at 7:45 AM David G. Johnston <
david(dot)g(dot)johnston(at)gmail(dot)com> wrote:

> On Wed, Apr 24, 2024 at 3:30 AM Peter Eisentraut <peter(at)eisentraut(dot)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>

David J.