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
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
