On Sun, Mar 8, 2026 at 5:04 PM David G. Johnston <[email protected]>
wrote:
> On Sunday, March 8, 2026, Igor Korot <[email protected]> wrote:
>
>> David,
>>
>> On Sun, Mar 8, 2026 at 6:49 PM David G. Johnston
>> <[email protected]> wrote:
>> >
>> > On Sunday, March 8, 2026, Igor Korot <[email protected]> wrote:
>> >>
>> >>
>> >> So the "WITH " clause is definitely available for indexes.
>> >
>> >
>> > Yeah, given you aren’t getting a syntax error all this advice to change
>> the syntax is wrong. Though assuming you meant to apply it to the table
>> was at least reasonable given the lack of confirmed intent statement for
>> what the command should be doing.
>>
>> Thanks.
>> It is a little confusing how it is written in the docs.
>>
>> But I'm not sure how to explain it better. ;-)
>>
>>
> Yeah, using the same term for two separate things isn’t ideal. Using
> table_storage_parameters and index_storage_parameters separately, and
> directly pointing the later to the create index page, would probably be
> better than an overlookable single sentence in the big storage parameters
> paragraph.
>
>
Concretely (will send to -hackers later if needed):
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
For consistency with the changes made in create table.
@@ -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
This is just adding a documentation index entry where one is needed.
@@ -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 982532fe725..acd61534265 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
Distinguish in the synopsis the two sets of storage parameters in play here.
@@ -30,7 +30,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } |
UNLOGGED ] TABLE [ IF NOT EXI
[ 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 [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } |
UNLOGGED ] TABLE [ IF NOT EXI
) ]
[ 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 [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } |
UNLOGGED ] TABLE [ IF NOT EXI
) ] { 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> ]
@@ -100,7 +100,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
<phrase><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> ]
Add the second variant in the description area consistent with the other
multi-variant syntax blocks being documented here.
Also mention and link to the index ones directly instead of only via the
table storage parameters section.
The comment about OIDS doesn't fit in with the paragraph about storage
parameters, give it its own paragraph.
@@ -1451,12 +1451,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;
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.
We already name Index Storage Parameters, we should add "Table" here.
@@ -1555,8 +1560,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>
And point to the actual storage parameter section directly instead of the
whole page.
@@ -1567,7 +1572,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
We continue to speak of "storage parameters" in each page without
qualification, just adding table/index for titles and syntax labels for the
specific clarity needed in those cases.
David J.
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 982532fe725..acd61534265 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -30,7 +30,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
[ 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 [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
) ]
[ 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 [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
) ] { 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> ]
@@ -100,7 +100,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
<phrase><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><replaceable class="parameter">exclude_element</replaceable> in an <literal>EXCLUDE</literal> constraint is:</phrase>
@@ -1451,12 +1451,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;
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.
@@ -1555,8 +1560,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>
@@ -1567,7 +1572,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
