From: Tom Lane Date: Thu, 26 Mar 2026 21:27:32 +0000 (-0400) Subject: Doc: declutter CREATE TABLE synopsis. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a6d26e0fb29b8b644a495a6c2d5ed5c50b41addb;p=thirdparty%2Fpostgresql.git Doc: declutter CREATE TABLE synopsis. Factor out the "persistence mode" and storage/compression parts of the syntax synopsis to reduce line lengths and increase readability. Also add an introductory para about the persistence modes so that the Description section still lines up with the synopsis. Author: David G. Johnston Reviewed-by: Laurenz Albe Reviewed-by: Jian He Discussion: https://postgr.es/m/CAKFQuwYfMV-2SdrP-umr5SVNSqTn378BUvHsebetp5=DhT494w@mail.gmail.com --- diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index 982532fe725..80829b23945 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -21,8 +21,8 @@ PostgreSQL documentation -CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] table_name ( [ - { column_name data_type [ STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT } ] [ COMPRESSION compression_method ] [ COLLATE collation ] [ column_constraint [ ... ] ] +CREATE [ persistence_mode ] TABLE [ IF NOT EXISTS ] table_name ( [ + { column_name data_type [ column_storage ] [ column_compression ] [ COLLATE collation ] [ column_constraint [ ... ] ] | table_constraint | LIKE source_table [ like_option ... ] } [, ... ] @@ -34,7 +34,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] [ TABLESPACE tablespace_name ] -CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] table_name +CREATE [ persistence_mode ] TABLE [ IF NOT EXISTS ] table_name OF type_name [ ( { column_name [ WITH OPTIONS ] [ column_constraint [ ... ] ] | table_constraint } @@ -46,7 +46,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] [ TABLESPACE tablespace_name ] -CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] table_name +CREATE [ persistence_mode ] TABLE [ IF NOT EXISTS ] table_name PARTITION OF parent_table [ ( { column_name [ WITH OPTIONS ] [ column_constraint [ ... ] ] | table_constraint } @@ -58,7 +58,19 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] [ TABLESPACE tablespace_name ] -where column_constraint is: +where persistence_mode is: + +{ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } } | UNLOGGED + +and column_storage is: + +STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT } + +and column_compression is: + +COMPRESSION compression_method + +and column_constraint is: [ CONSTRAINT constraint_name ] { NOT NULL [ NO INHERIT ] | @@ -97,17 +109,17 @@ FROM ( { partition_bound_expr | MIN TO ( { partition_bound_expr | MINVALUE | MAXVALUE } [, ...] ) | WITH ( MODULUS numeric_literal, REMAINDER numeric_literal ) -index_parameters in UNIQUE, PRIMARY KEY, and EXCLUDE constraints are: +and index_parameters in UNIQUE, PRIMARY KEY, and EXCLUDE constraints are: [ INCLUDE ( column_name [, ... ] ) ] [ WITH ( storage_parameter [= value] [, ... ] ) ] [ USING INDEX TABLESPACE tablespace_name ] -exclude_element in an EXCLUDE constraint is: +and exclude_element in an EXCLUDE constraint is: { column_name | ( expression ) } [ COLLATE collation ] [ opclass [ ( opclass_parameter = value [, ... ] ) ] ] [ ASC | DESC ] [ NULLS { FIRST | LAST } ] -referential_action in a FOREIGN KEY/REFERENCES constraint is: +and referential_action in a FOREIGN KEY/REFERENCES constraint is: { NO ACTION | RESTRICT | CASCADE | SET NULL [ ( column_name [, ... ] ) ] | SET DEFAULT [ ( column_name [, ... ] ) ] } @@ -123,6 +135,14 @@ WITH ( MODULUS numeric_literal, REM command. + + 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 temporary + or unlogged. + + If a schema name is given (for example, CREATE TABLE myschema.mytable ...) then the table is created in the specified @@ -312,7 +332,7 @@ WITH ( MODULUS numeric_literal, REM - This form sets the storage mode for the column. This controls whether this + This clause sets the storage mode for the column. This controls whether this column is held inline or in a secondary TOAST table, and whether the data should be compressed or not. PLAIN must be used for fixed-length values such as integer and is diff --git a/doc/src/sgml/ref/create_table_as.sgml b/doc/src/sgml/ref/create_table_as.sgml index 6b41226cbd6..0492933ff38 100644 --- a/doc/src/sgml/ref/create_table_as.sgml +++ b/doc/src/sgml/ref/create_table_as.sgml @@ -21,14 +21,18 @@ PostgreSQL documentation -CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] table_name - [ (column_name [, ...] ) ] +CREATE [ persistence_mode ] TABLE [ IF NOT EXISTS ] table_name + [ ( column_name [, ...] ) ] [ USING method ] [ WITH ( storage_parameter [= value] [, ... ] ) | WITHOUT OIDS ] [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] [ TABLESPACE tablespace_name ] AS query [ WITH [ NO ] DATA ] + +where persistence_mode is: + +{ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } } | UNLOGGED