public inbox for [email protected]
help / color / mirror / Atom feedFrom: David G. Johnston <[email protected]>
To: PostgreSQL Hackers <[email protected]>
Subject: Docs: Distinguish table and index storage parameters in CREATE TABLE
Date: Fri, 3 Apr 2026 11:18:50 -0700
Message-ID: <CAKFQuwYe1vf7k+gx_f5ny1mpz_CrhMhaa_NgVb-87_=DHj3JEw@mail.gmail.com> (raw)
Hi,
Per the discussion on -general [1] I propose that we stop using the generic
label storage_parameter on the create table reference page and instead set
up proper labels for table and index variants.
David J.
[1]
https://www.postgresql.org/message-id/flat/CA%2BFnnTyGEM-1mwxKPbwFTOodf%2BYUX%3DTxTmBPY5S%3DYh1h%3Do...
Attachments:
[application/octet-stream] v1-0001-pgsql-doc-Distinguish-table-and-index-storage-parame.patch.patch (9.9K, 3-v1-0001-pgsql-doc-Distinguish-table-and-index-storage-parame.patch.patch)
download | inline diff:
From a485ff1b04faf706f834f533066de61176d05cd4 Mon Sep 17 00:00:00 2001
From: Developer <dev@local>
Date: Fri, 3 Apr 2026 11:00:09 -0700
Subject: [PATCH] pgsql: doc: Distinguish table and index storage parameters in
CREATE TABLE
The WITH clause in CREATE TABLE applies to both tables and constraint
indexes, but uses a single storage_parameter placeholder in the syntax
synopsis making the distinction unclear.
Rename the placeholder to table_storage_parameter and
index_storage_parameter respectively in the synopsis and add a separate
term for the index variant in the WITH parameter description. Update
the description to reference the index storage parameters section in
CREATE INDEX directly rather than the top-level CREATE INDEX page.
Also rename the Storage Parameters subsection to Table Storage
Parameters to make clear it covers only table parameters.
---
doc/src/sgml/ref/create_index.sgml | 8 ++++++--
doc/src/sgml/ref/create_table.sgml | 25 +++++++++++++++----------
2 files changed, 21 insertions(+), 12 deletions(-)
diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index bb7505d171b..d50c71c0a11 100644
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -25,7 +25,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
( { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ COLLATE <replaceable class="parameter">collation</replaceable> ] [ <replaceable class="parameter">opclass</replaceable> [ ( <replaceable class="parameter">opclass_parameter</replaceable> = <replaceable class="parameter">value</replaceable> [, ... ] ) ] ] [ ASC | DESC ] [ NULLS { FIRST | LAST } ] [, ...] )
[ INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ...] ) ]
[ NULLS [ NOT ] DISTINCT ]
- [ WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
+ [ WITH ( <replaceable class="parameter">index_storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
[ TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
[ WHERE <replaceable class="parameter">predicate</replaceable> ]
</synopsis>
@@ -349,7 +349,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
</varlistentry>
<varlistentry>
- <term><replaceable class="parameter">storage_parameter</replaceable></term>
+ <term><replaceable class="parameter">index_storage_parameter</replaceable></term>
<listitem>
<para>
The name of an index-method-specific storage parameter. See
@@ -385,6 +385,10 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
<refsect2 id="sql-createindex-storage-parameters" xreflabel="Index Storage Parameters">
<title>Index Storage Parameters</title>
+ <indexterm zone="sql-createindex-storage-parameters">
+ <primary>storage parameters</primary>
+ </indexterm>
+
<para>
The optional <literal>WITH</literal> clause specifies <firstterm>storage
parameters</firstterm> for the index. Each index method has its own set
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index 80829b23945..89a29430828 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -30,7 +30,7 @@ CREATE [ <replaceable>persistence_mode</replaceable> ] TABLE [ IF NOT EXISTS ] <
[ INHERITS ( <replaceable>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 ]
+[ WITH ( <replaceable class="parameter">table_storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) | WITHOUT OIDS ]
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
[ TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
@@ -42,7 +42,7 @@ CREATE [ <replaceable>persistence_mode</replaceable> ] TABLE [ IF NOT EXISTS ] <
) ]
[ 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 ]
+[ WITH ( <replaceable class="parameter">table_storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) | WITHOUT OIDS ]
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
[ TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
@@ -54,7 +54,7 @@ CREATE [ <replaceable>persistence_mode</replaceable> ] TABLE [ IF NOT EXISTS ] <
) ] { FOR VALUES <replaceable class="parameter">partition_bound_spec</replaceable> | DEFAULT }
[ 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 ]
+[ WITH ( <replaceable class="parameter">table_storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) | WITHOUT OIDS ]
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
[ TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
@@ -112,7 +112,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
<phrase>and <replaceable class="parameter">index_parameters</replaceable> in <literal>UNIQUE</literal>, <literal>PRIMARY KEY</literal>, and <literal>EXCLUDE</literal> constraints are:</phrase>
[ INCLUDE ( <replaceable class="parameter">column_name</replaceable> [, ... ] ) ]
-[ WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
+[ WITH ( <replaceable class="parameter">index_storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
[ USING INDEX TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> ]
<phrase>and <replaceable class="parameter">exclude_element</replaceable> in an <literal>EXCLUDE</literal> constraint is:</phrase>
@@ -1471,12 +1471,17 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
</varlistentry>
<varlistentry id="sql-createtable-parms-with">
- <term><literal>WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
+ <term><literal>WITH ( <replaceable class="parameter">table_storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
+ <term><literal>WITH ( <replaceable class="parameter">index_storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
<listitem>
<para>
- This clause specifies optional storage parameters for a table or index;
+ These clauses specify optional storage parameters for tables and indexes respectively;
see <xref linkend="sql-createtable-storage-parameters"/> below for more
- information. For backward-compatibility the <literal>WITH</literal>
+ information on table storage parameters. For index storage parameters
+ see <xref linkend="sql-createindex-storage-parameters"/>.
+ </para>
+ <para>
+ For backward-compatibility the <literal>WITH</literal>
clause for a table can also include <literal>OIDS=FALSE</literal> to
specify that rows of the new table should not contain OIDs (object
identifiers), <literal>OIDS=TRUE</literal> is not supported anymore.
@@ -1575,8 +1580,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
</variablelist>
- <refsect2 id="sql-createtable-storage-parameters" xreflabel="Storage Parameters">
- <title>Storage Parameters</title>
+ <refsect2 id="sql-createtable-storage-parameters" xreflabel="Table Storage Parameters">
+ <title>Table Storage Parameters</title>
<indexterm zone="sql-createtable-storage-parameters">
<primary>storage parameters</primary>
@@ -1587,7 +1592,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
for tables, and for indexes associated with a <literal>UNIQUE</literal>,
<literal>PRIMARY KEY</literal>, or <literal>EXCLUDE</literal> constraint.
Storage parameters for
- indexes are documented in <xref linkend="sql-createindex"/>.
+ indexes are documented in <xref linkend="sql-createindex-storage-parameters"/>
The storage parameters currently
available for tables are listed below. For many of these parameters, as
shown, there is an additional parameter with the same name prefixed with
--
2.43.0
view thread (8+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected]
Subject: Re: Docs: Distinguish table and index storage parameters in CREATE TABLE
In-Reply-To: <CAKFQuwYe1vf7k+gx_f5ny1mpz_CrhMhaa_NgVb-87_=DHj3JEw@mail.gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox