Subject: Re: docs: clarify ALTER TABLE behavior on partitioned tables

From: "David G. Johnston" <[email-masked]>
Date: Fri, 9 Jan 2026 09:12:24 -0700

On Fri, Jan 9, 2026 at 1:11 AM Chao Li <[email-masked]> wrote:

> >
> > The main points of interest:
> >
> > Saying that "ONLY" is a no-op when the observed behavior is that only
> the mentioned tables are affected seems wrong.  I've removed those
> instances.
>
> Maybe the original phrasing “has no effect” wasn’t clear for what I meant.
> What I was trying to express is that ONLY is intended to control whether an
> action propagates to child tables: with ONLY it should not propagate, and
> without ONLY it should.
>
> For these particular sub-commands, however, the observed behavior is that
> they behave the same with or without ONLY. From a documentation
> perspective, stating that explicitly could help avoid user confusion.
>
> Separately, I do have a plan to tighten this behavior in the future: for
> these commands, specifying ONLY would raise an error instead. If such a
> change is merged later, the documentation note could naturally be removed
> at that point.
>
> So I’d like to keep the statement for now, but I’m very happy to adjust
> the wording if you have a clearer phrasing to suggest.
>

I've removed some I missed and tweaked others.  I'm OK with leaving mention
of ONLY in these sections but what happens is that ONLY becomes implicitly
added to the command, which is what I'd rather communicate.  The remaining
wording is a bit redundant now but flows nicely.

> Before I integrate your edits and prepare v3, I’d appreciate hearing your
> thoughts on the points about ONLY and “newly created”.
>
>
As I continue to think about the "newly created" material the more I
believe it is misplaced.  That there is existing wording to that effect
doesn't change my conclusion.  I would add no additional text here even if
you don't want to remove the existing mentions at this point.  But I think
the scope of this patch should be increased to fix this misplacement as
well.  Since moving content - refactoring - is what is happening here.  In
the attached 0003 I've removed the paragraphs that this patch now makes
redundant within the alter table documentation.  I wouldn't mind if they
got moved to somewhere in Chapter 5.12 (Table Partitioning) and not just
erased, along with ensuring that 5.12 includes how table creation
definition inheritance works and removing those mentions from the alter
table docs as well.

I'm not sure whether I'd fully remove all that content since some of it
does pertain just to table inheritance.  That feature seems like something
best related to notes and not brought into the main flow like you are doing
with partitioned tables.

David J.
From 3fc3b4eb84dbdbe58eb283c3322ff6cf16d9a1d0 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <[email-masked]>
Date: Wed, 7 Jan 2026 14:50:36 -0700
Subject: [PATCH 1/2] docs Clarify ALTER TABLE

---
 doc/src/sgml/ref/alter_table.sgml | 309 +++++++++++++++++++++++++-----
 1 file changed, 257 insertions(+), 52 deletions(-)

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 1bd479c917a..b1190fae968 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -171,6 +171,12 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       is specified and a column already exists with this name,
       no error is thrown.
      </para>
+     <para>
+      When applied to a partitioned table, the column is added to the
+      partitioned table definition and is implicitly present in all
+      partitions. Specifying <literal>ONLY</literal> is not allowed, and
+      this command cannot be used on individual partitions.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -190,6 +196,12 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       does not exist, no error is thrown. In this case a notice
       is issued instead.
      </para>
+     <para>
+      When applied to a partitioned table, the column is removed from the
+      partitioned table definition and is implicitly removed from all
+      partitions. Specifying <literal>ONLY</literal> is not allowed, and
+      this command cannot be used on individual partitions.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -211,7 +223,6 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       clause must be provided if there is no implicit or assignment
       cast from old to new type.
      </para>
-
      <para>
       When this form is used, the column's statistics are removed,
       so running <link linkend="sql-analyze"><command>ANALYZE</command></link>
@@ -219,6 +230,12 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       For a virtual generated column, <command>ANALYZE</command>
       is not necessary because such columns never have statistics.
      </para>
+     <para>
+      When applied to a partitioned table, the data type change is applied
+      to the partitioned table definition and affects all partitions.
+      Specifying <literal>ONLY</literal> is not allowed, and this command
+      cannot be used on individual partitions.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -232,6 +249,13 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       or <command>UPDATE</command> commands; it does not cause rows already
       in the table to change.
      </para>
+     <para>
+      When applied to a partitioned table, the default value is propagated
+      to all existing partitions unless <literal>ONLY</literal> is specified.
+      New partitions created afterwards inherit the default from the
+      partitioned table, but individual partitions may define a different
+      default.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -242,7 +266,6 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       These forms change whether a column is marked to allow null
       values or to reject null values.
      </para>
-
      <para>
       <literal>SET NOT NULL</literal> may only be applied to a column
       provided none of the records in the table contain a
@@ -255,18 +278,19 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       If a column has an invalid not-null constraint,
       <literal>SET NOT NULL</literal> validates it.
      </para>
-
      <para>
-      If this table is a partition, one cannot perform <literal>DROP NOT NULL</literal>
-      on a column if it is marked <literal>NOT NULL</literal> in the parent
-      table.  To drop the <literal>NOT NULL</literal> constraint from all the
-      partitions, perform <literal>DROP NOT NULL</literal> on the parent
-      table.  Even if there is no <literal>NOT NULL</literal> constraint on the
-      parent, such a constraint can still be added to individual partitions,
-      if desired; that is, the children can disallow nulls even if the parent
-      allows them, but not the other way around.  It is also possible to drop
-      the <literal>NOT NULL</literal> constraint from <literal>ONLY</literal>
-      the parent table, which does not remove it from the children.
+      If this table is a partition, one cannot perform
+      <literal>DROP NOT NULL</literal> on a column if it is marked
+      <literal>NOT NULL</literal> in the parent table. To drop the
+      <literal>NOT NULL</literal> constraint from all partitions, perform
+      <literal>DROP NOT NULL</literal> on the parent table. Even if there is
+      no <literal>NOT NULL</literal> constraint on the parent, such a
+      constraint can still be added to individual partitions; that is, the
+      children can disallow nulls even if the parent allows them, but not
+      the other way around. It is also possible to apply
+      <literal>SET NOT NULL</literal> or <literal>DROP NOT NULL</literal> to
+      <literal>ONLY</literal> the parent table, which does not affect the
+      children.
      </para>
     </listitem>
    </varlistentry>
@@ -279,7 +303,6 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       in a stored generated column is rewritten and all the future changes
       will apply the new generation expression.
      </para>
-
      <para>
       When this form is used on a stored generated column, its statistics
       are removed, so running
@@ -288,6 +311,13 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       For a virtual generated column, <command>ANALYZE</command>
       is not necessary because such columns never have statistics.
      </para>
+     <para>
+      When applied to a partitioned table, the generation expression is
+      propagated to all existing partitions unless <literal>ONLY</literal>
+      is specified. New partitions created afterwards inherit the
+      expression from the partitioned table, while individual partitions
+      may define a different expression.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -299,17 +329,21 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       Existing data in the columns is retained, but future changes will no
       longer apply the generation expression.
      </para>
-
      <para>
       This form is currently only supported for stored generated columns (not
       virtual ones).
      </para>
-
      <para>
       If <literal>DROP EXPRESSION IF EXISTS</literal> is specified and the
       column is not a generated column, no error is thrown.  In this case a
       notice is issued instead.
      </para>
+     <para>
+      When applied to a partitioned table, the generation expression is
+      dropped from the partitioned table definition and from all
+      partitions. Specifying <literal>ONLY</literal> is not allowed, and
+      this command cannot be used on individual partitions.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -327,12 +361,17 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       and <command>UPDATE</command> commands; they do not cause rows
       already in the table to change.
      </para>
-
      <para>
       If <literal>DROP IDENTITY IF EXISTS</literal> is specified and the
       column is not an identity column, no error is thrown.  In this case a
       notice is issued instead.
      </para>
+     <para>
+      When applied to a partitioned table, the identity property is defined
+      on the partitioned table definition and applies to all partitions.
+      Specifying <literal>ONLY</literal> is not allowed, and these forms
+      cannot be used on individual partitions.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -346,6 +385,13 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       supported by <link linkend="sql-altersequence"><command>ALTER SEQUENCE</command></link> such
       as <literal>INCREMENT BY</literal>.
      </para>
+     <para>
+      When applied to a partitioned table, these forms alter the sequence
+      associated with the identity column on the partitioned table
+      definition and affect all partitions. Specifying <literal>ONLY</literal>
+      is not allowed, and these forms cannot be used on individual
+      partitions.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -369,6 +415,12 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       <literal>SET STATISTICS</literal> acquires a
       <literal>SHARE UPDATE EXCLUSIVE</literal> lock.
      </para>
+     <para>
+      For partitioned tables, this action applies to the partitioned table
+      and all of its partitions unless <literal>ONLY</literal> is specified.
+      Partitions created afterwards do not inherit the statistics target
+      from the partitioned table.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -403,6 +455,13 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       Changing per-attribute options acquires a
       <literal>SHARE UPDATE EXCLUSIVE</literal> lock.
      </para>
+     <para>
+      For partitioned tables, these forms can be applied independently to
+      the partitioned table and to individual partitions. Changes made to
+      the partitioned table do not propagate to existing partitions, and
+      partitions created afterwards do not inherit the setting.
+      Specifying <literal>ONLY</literal> is allowed but has no effect.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -437,6 +496,13 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       during future table updates.
       See <xref linkend="storage-toast"/> for more information.
      </para>
+     <para>
+      When applied to a partitioned table, the storage setting is propagated
+      to all existing partitions unless <literal>ONLY</literal> is specified.
+      New partitions created afterwards inherit the setting from the
+      partitioned table, while individual partitions may use a different
+      storage setting.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -467,6 +533,14 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       consulting the <xref linkend="guc-default-toast-compression"/> setting
       at the time of data insertion to determine the method to use.
      </para>
+     <para>
+      When applied to a partitioned table, the compression setting is applied
+      to the partitioned table definition and does not propagate to existing
+      partitions. New partitions created afterwards inherit the setting from
+      the partitioned table, while individual partitions may use a different
+      compression method. Specifying <literal>ONLY</literal> is allowed but has
+      no effect.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -479,7 +553,6 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       VALID</literal>, which is currently only allowed for foreign-key,
       <literal>CHECK</literal>, and not-null constraints.
      </para>
-
      <para>
       Normally, this form will cause a scan of the table to verify that all
       existing rows in the table satisfy the new constraint.  But if
@@ -495,7 +568,6 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       See <xref linkend="sql-altertable-notes"/> below for more information
       about using the <literal>NOT VALID</literal> option.
      </para>
-
      <para>
       Although most forms of <literal>ADD
       <replaceable class="parameter">table_constraint</replaceable></literal>
@@ -506,12 +578,16 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       referenced table, in addition to the lock on the table on which the
       constraint is declared.
      </para>
-
      <para>
       Additional restrictions apply when unique or primary key constraints
       are added to partitioned tables; see <link linkend="sql-createtable"><command>CREATE TABLE</command></link>.
      </para>
-
+     <para>
+      When applied to a partitioned table, the constraint is added to the
+      partitioned table and is automatically applied to all partitions.
+      Specifying <literal>ONLY</literal> is not allowed. New partitions
+      created afterwards inherit the constraint from the partitioned table.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -523,7 +599,6 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       constraint to a table based on an existing unique index.  All the
       columns of the index will be included in the constraint.
      </para>
-
      <para>
       The index cannot have expression columns nor be a partial index.
       Also, it must be a b-tree index with default sort ordering.  These
@@ -531,7 +606,6 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       built by a regular <literal>ADD PRIMARY KEY</literal> or <literal>ADD UNIQUE</literal>
       command.
      </para>
-
      <para>
       If <literal>PRIMARY KEY</literal> is specified, and the index's columns are not
       already marked <literal>NOT NULL</literal>, then this command will attempt to
@@ -539,13 +613,11 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       That requires a full table scan to verify the column(s) contain no
       nulls.  In all other cases, this is a fast operation.
      </para>
-
      <para>
       If a constraint name is provided then the index will be renamed to match
       the constraint name.  Otherwise the constraint will be named the same as
       the index.
      </para>
-
      <para>
       After this command is executed, the index is <quote>owned</quote> by the
       constraint, in the same way as if the index had been built by
@@ -553,11 +625,10 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       command.  In particular, dropping the constraint will make the index
       disappear too.
      </para>
-
      <para>
-      This form is not currently supported on partitioned tables.
+      This form is not supported on partitioned tables, but can be used on
+      individual (leaf) partitions.
      </para>
-
      <note>
       <para>
        Adding a constraint using an existing index can be helpful in
@@ -578,6 +649,12 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       created. Currently only foreign key constraints may be altered in
       this fashion, but see below.
      </para>
+     <para>
+      When applied to a partitioned table, the constraint is altered on the
+      partitioned table definition and the change applies to all partitions.
+      Specifying <literal>ONLY</literal> is not allowed, and this command
+      cannot be used on individual partitions.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -596,7 +673,11 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       non-inheritable on a table with children, then the corresponding
       constraint on children will be marked as no longer inherited,
       but not removed.
-      </para>
+     </para>
+     <para>
+      These forms are not supported on partitioned tables, but can be used
+      on individual (leaf) partitions.
+     </para>
      </listitem>
     </varlistentry>
 
@@ -615,6 +696,12 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      <para>
       This command acquires a <literal>SHARE UPDATE EXCLUSIVE</literal> lock.
      </para>
+     <para>
+      When applied to a partitioned table, the constraint is validated on the
+      partitioned table and on all partitions. Unlike most constraint-related
+      sub-commands, individual partitions may validate the constraint
+      independently of the partitioned table.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -627,6 +714,13 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       If <literal>IF EXISTS</literal> is specified and the constraint
       does not exist, no error is thrown. In this case a notice is issued instead.
      </para>
+     <para>
+      When applied to a partitioned table, the constraint is dropped from
+      all existing partitions unless <literal>ONLY</literal> is specified.
+      New partitions created afterwards do not include the dropped
+      constraint, while individual partitions may drop the constraint
+      independently of the partitioned table.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -648,7 +742,6 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       of course the integrity of the constraint cannot be guaranteed if the
       triggers are not executed.
      </para>
-
      <para>
       The trigger firing mechanism is also affected by the configuration
       variable <xref linkend="guc-session-replication-role"/>. Simply enabled
@@ -658,7 +751,6 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       mode, and triggers configured as <literal>ENABLE ALWAYS</literal> will
       fire regardless of the current replication role.
      </para>
-
      <para>
       The effect of this mechanism is that in the default configuration,
       triggers do not fire on replicas.  This is useful because if a trigger
@@ -670,13 +762,14 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       to <literal>ENABLE ALWAYS</literal> so that it is also fired on
       replicas.
      </para>
-
      <para>
       When this command is applied to a partitioned table, the states of
-      corresponding clone triggers in the partitions are updated too,
-      unless <literal>ONLY</literal> is specified.
+      corresponding clone triggers in existing partitions are updated too,
+      unless <literal>ONLY</literal> is specified. Triggers in partitions
+      created afterwards inherit the trigger state from the partitioned
+      table, while individual partitions may configure trigger states
+      independently.
      </para>
-
      <para>
       This command acquires a <literal>SHARE ROW EXCLUSIVE</literal> lock.
      </para>
@@ -694,12 +787,18 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       are always applied in order to keep views working even if the current
       session is in a non-default replication role.
      </para>
-
      <para>
       The rule firing mechanism is also affected by the configuration variable
       <xref linkend="guc-session-replication-role"/>, analogous to triggers as
       described above.
      </para>
+     <para>
+      For partitioned tables, these forms can be applied independently to
+      the partitioned table and to individual partitions. Changes made to
+      the partitioned table do not propagate to existing partitions, and
+      partitions created afterwards do not inherit the setting.
+      Specifying <literal>ONLY</literal> is allowed but has no effect.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -715,6 +814,13 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       See also
       <link linkend="sql-createpolicy"><command>CREATE POLICY</command></link>.
      </para>
+     <para>
+      For partitioned tables, these forms can be applied independently to
+      the partitioned table and to individual partitions. Changes made to
+      the partitioned table do not propagate to existing partitions, and
+      partitions created afterwards do not inherit the setting.
+      Specifying <literal>ONLY</literal> is allowed but has no effect.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -730,6 +836,13 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       See also
       <link linkend="sql-createpolicy"><command>CREATE POLICY</command></link>.
      </para>
+     <para>
+      For partitioned tables, these forms can be applied independently to
+      the partitioned table and to individual partitions. Changes made to
+      the partitioned table do not propagate to existing partitions, and
+      partitions created afterwards do not inherit the setting.
+      Specifying <literal>ONLY</literal> is allowed but has no effect.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -744,6 +857,10 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      <para>
       Changing cluster options acquires a <literal>SHARE UPDATE EXCLUSIVE</literal> lock.
      </para>
+     <para>
+      This form is not supported on partitioned tables, but can be used on
+      individual (leaf) partitions.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -759,6 +876,10 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      <para>
       Changing cluster options acquires a <literal>SHARE UPDATE EXCLUSIVE</literal> lock.
      </para>
+     <para>
+      This form is not supported on partitioned tables, but can be used on
+      individual (leaf) partitions.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -770,6 +891,12 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       system column.  As <literal>oid</literal> system columns cannot be
       added anymore, this never has an effect.
      </para>
+     <para>
+      For partitioned tables, this form behaves the same as for regular
+      tables; it has no effect on either the partitioned table or its
+      partitions. Specifying <literal>ONLY</literal> is allowed but has no
+      effect.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -785,12 +912,15 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       See <xref linkend="tableam"/> for more information.
      </para>
      <para>
-      When applied to a partitioned table, there is no data to rewrite,
-      but partitions created afterwards will default to the given access
-      method unless overridden by a <literal>USING</literal> clause.
-      Specifying <varname>DEFAULT</varname> removes a previous value,
-      causing future partitions to default to
-      <varname>default_table_access_method</varname>.
+      When applied to a partitioned table, there is no data to rewrite.
+      Partitions created afterwards will use the access method specified
+      on the partitioned table, if any, unless overridden by a
+      <literal>USING</literal> clause; otherwise they default to
+      <varname>default_table_access_method</varname>. Specifying
+      <literal>DEFAULT</literal> removes a previously set access method,
+      causing future partitions to use
+      <varname>default_table_access_method</varname>. Specifying
+      <literal>ONLY</literal> is allowed but has no effect.
      </para>
     </listitem>
    </varlistentry>
@@ -803,12 +933,12 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       moves the data file(s) associated with the table to the new tablespace.
       Indexes on the table, if any, are not moved; but they can be moved
       separately with additional <literal>SET TABLESPACE</literal> commands.
-      When applied to a partitioned table, nothing is moved, but any
-      partitions created afterwards with
-      <command>CREATE TABLE PARTITION OF</command> will use that tablespace,
-      unless overridden by a <literal>TABLESPACE</literal> clause.
+      When applied to a partitioned table, no data is moved. Existing
+      partitions are not affected, but partitions created afterwards with
+      <command>CREATE TABLE PARTITION OF</command> will use the specified
+      tablespace unless overridden by a <literal>TABLESPACE</literal> clause.
+      Specifying <literal>ONLY</literal> is allowed but has no effect.
      </para>
-
      <para>
       All tables in the current database in a tablespace can be moved by using
       the <literal>ALL IN TABLESPACE</literal> form, which will lock all tables
@@ -835,15 +965,14 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       (see <xref linkend="sql-createtable-unlogged"/>).  It cannot be applied
       to a temporary table.
      </para>
-
      <para>
       This also changes the persistence of any sequences linked to the table
       (for identity or serial columns).  However, it is also possible to
       change the persistence of such sequences separately.
      </para>
-
      <para>
-      This form is not supported for partitioned tables.
+      This form is not supported on partitioned tables, but can be used on
+      individual (leaf) partitions.
      </para>
     </listitem>
    </varlistentry>
@@ -865,12 +994,15 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       time the table is locked so currently executing queries will not be
       affected.
      </para>
-
      <para>
       <literal>SHARE UPDATE EXCLUSIVE</literal> lock will be taken for
       fillfactor, TOAST and autovacuum storage parameters, as well as the
       planner parameter <varname>parallel_workers</varname>.
      </para>
+     <para>
+      This form is not supported on partitioned tables, but can be used on
+      individual (leaf) partitions.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -882,6 +1014,11 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       defaults.  As with <literal>SET</literal>, a table rewrite might be
       needed to update the table entirely.
      </para>
+     <para>
+      When applied to a partitioned table, this form is accepted but has no
+      effect. It can be used on individual (leaf) partitions, where it
+      behaves as for a regular table.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -895,7 +1032,6 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       already contain all the same columns as the parent (it could have
       additional columns, too).  The columns must have matching data types.
      </para>
-
      <para>
       In addition, all <literal>CHECK</literal> and <literal>NOT NULL</literal>
       constraints on the parent must also exist on the child, except those
@@ -907,6 +1043,10 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       <literal>FOREIGN KEY</literal> constraints are not considered, but
       this might change in the future.
      </para>
+     <para>
+      This form does not support partitioned tables; it cannot be applied to
+      either a partitioned table or its partitions.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -919,6 +1059,10 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       Queries against the parent table will no longer include records drawn
       from the target table.
      </para>
+     <para>
+      This form does not support partitioned tables; it cannot be applied to
+      either a partitioned table or its partitions.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -933,6 +1077,12 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       that <command>CREATE TABLE OF</command> would permit an equivalent table
       definition.
      </para>
+     <para>
+      When applied to a partitioned table, this form affects only the
+      partitioned table itself. Specifying <literal>ONLY</literal> is
+      allowed but has no effect, and this form cannot be used on individual
+      partitions.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -942,6 +1092,12 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      <para>
       This form dissociates a typed table from its type.
      </para>
+     <para>
+      When applied to a partitioned table, this form affects only the
+      partitioned table itself. Specifying <literal>ONLY</literal> is
+      allowed but has no effect, and this form cannot be used on individual
+      partitions.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -952,6 +1108,13 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       This form changes the owner of the table, sequence, view, materialized view,
       or foreign table to the specified user.
      </para>
+     <para>
+      For partitioned tables, this form can be applied independently to the
+      partitioned table and to individual partitions. Changing the owner of
+      the partitioned table does not affect existing partitions, and
+      partitions created afterwards do not inherit the new owner.
+      Specifying <literal>ONLY</literal> is allowed but has no effect.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -1008,6 +1171,14 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
        </listitem>
       </varlistentry>
      </variablelist></para>
+
+     <para>
+      For partitioned tables, this form can be applied independently to the
+      partitioned table and to individual partitions. Changing the replica
+      identity of the partitioned table does not affect existing partitions,
+      and partitions created afterwards do not inherit the setting.
+      Specifying <literal>ONLY</literal> is allowed but has no effect.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -1022,6 +1193,12 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       the index is renamed as well.
       There is no effect on the stored data.
      </para>
+     <para>
+      For partitioned tables, this form behaves the same as for regular
+      tables. Renaming a partitioned table, column, or constraint does not
+      propagate to partitions, and <literal>ONLY</literal> can be specified
+      but has no effect.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -1032,6 +1209,13 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       This form moves the table into another schema.  Associated indexes,
       constraints, and sequences owned by table columns are moved as well.
      </para>
+     <para>
+      For partitioned tables, this form can be applied independently to the
+      partitioned table and to individual partitions. Moving the partitioned
+      table to another schema does not affect existing partitions, and
+      partitions created afterwards do not inherit the new schema.
+      Specifying <literal>ONLY</literal> is allowed but has no effect.
+     </para>
     </listitem>
    </varlistentry>
 
@@ -1410,6 +1594,27 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
         <literal>*</literal> can be specified after the table name to explicitly
         indicate that descendant tables are included.
        </para>
+
+       <para>
+        For a table that uses table inheritance, descendant tables are those
+        that inherit from the named table, directly or indirectly.
+        For a partitioned table, descendant tables are its partitions.
+       </para>
+
+       <para>
+        Note that for partitioned tables, <literal>ONLY</literal> does not control
+        recursion for all <command>ALTER TABLE</command> actions. Some actions
+        apply only to the partitioned table itself, regardless of whether
+        <literal>ONLY</literal> is specified, while others are propagated to
+        partitions. The exact behavior depends on the specific action being
+        performed.
+       </para>
+
+       <para>
+        Users should consult the documentation of each individual
+        <command>ALTER TABLE</command> action to determine whether and how it
+        affects partitions.
+       </para>
       </listitem>
      </varlistentry>
 
-- 
2.34.1

From 44c2e6dc79fbac78185816612b6a49c05557232b Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <[email-masked]>
Date: Fri, 9 Jan 2026 08:54:48 -0700
Subject: [PATCH] docs: ONLY tweaks and bulk note removal

---
 doc/src/sgml/ref/alter_table.sgml | 74 ++++++-------------------------
 1 file changed, 14 insertions(+), 60 deletions(-)

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 75a26087eb6..adf988b420e 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -529,9 +529,9 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       at the time of data insertion to determine the method to use.
      </para>
      <para>
-      When applied to a partitioned table, the compression method must be
-      applied separately to the partitioned table and/or to individual partitions.
-      Specifying <literal>ONLY</literal> is allowed but has no effect.
+      When applied to a partitioned table <literal>ONLY</literal> is implicit,
+      the compression method must be applied separately to the partitioned table
+      and/or to individual partitions.
       However, newly created partitions inherit the compression method from the
       partitioned table unless they define a different compression method.
      </para>
@@ -903,8 +903,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       <varname>default_table_access_method</varname>. Specifying
       <literal>DEFAULT</literal> removes a previously set access method,
       causing future partitions to use
-      <varname>default_table_access_method</varname>. Specifying
-      <literal>ONLY</literal> is allowed but has no effect.
+      <varname>default_table_access_method</varname>.
      </para>
     </listitem>
    </varlistentry>
@@ -921,7 +920,6 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       partitions are not affected, but partitions created afterwards with
       <command>CREATE TABLE PARTITION OF</command> will use the specified
       tablespace unless overridden by a <literal>TABLESPACE</literal> clause.
-      Specifying <literal>ONLY</literal> is allowed but has no effect.
      </para>
      <para>
       All tables in the current database in a tablespace can be moved by using
@@ -1062,10 +1060,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       definition.
      </para>
      <para>
-      When applied to a partitioned table, this form affects only the
-      partitioned table itself. Specifying <literal>ONLY</literal> is
-      allowed but has no effect, and this form cannot be used on individual
-      partitions.
+      When applied to a partitioned table <literal>ONLY</literal> is implicit,
+      and this form cannot be used on individual partitions.
      </para>
     </listitem>
    </varlistentry>
@@ -1077,10 +1073,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       This form dissociates a typed table from its type.
      </para>
      <para>
-      When applied to a partitioned table, this form affects only the
-      partitioned table itself. Specifying <literal>ONLY</literal> is
-      allowed but has no effect, and this form cannot be used on individual
-      partitions.
+      When applied to a partitioned table <literal>ONLY</literal> is implicit,
+      and this form cannot be used on individual partitions.
      </para>
     </listitem>
    </varlistentry>
@@ -1156,8 +1150,9 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </variablelist></para>
 
      <para>
-      For partitioned tables, this form must be applied independently to the
-      partitioned table and/or to individual partitions.
+      When applied to a partitioned table <literal>ONLY</literal> is implicit,
+      this form must be applied independently to the partitioned table and/or
+      to individual partitions.
       Newly created partitions do not inherit the setting from the
       partitioned table.
      </para>
@@ -1191,8 +1186,9 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       constraints, and sequences owned by table columns are moved as well.
      </para>
      <para>
-      For partitioned tables, this form must be applied independently to the
-      partitioned table and/or to individual partitions.
+      When applied to a partitioned table <literal>ONLY</literal> is implicit,
+      this form must be applied independently to the partitioned table and/or
+      to individual partitions.
       Newly created partitions do not inherit their schema from the
       partitioned table.
      </para>
@@ -1952,48 +1948,6 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
     the column.
    </para>
 
-   <para>
-    If a table has any descendant tables, it is not permitted to add,
-    rename, or change the type of a column in the parent table without doing
-    the same to the descendants.  This ensures that the descendants always
-    have columns matching the parent.  Similarly, a <literal>CHECK</literal>
-    constraint cannot be renamed in the parent without also renaming it in
-    all descendants, so that <literal>CHECK</literal> constraints also match
-    between the parent and its descendants.  (That restriction does not apply
-    to index-based constraints, however.)
-    Also, because selecting from the parent also selects from its descendants,
-    a constraint on the parent cannot be marked valid unless it is also marked
-    valid for those descendants.  In all of these cases, <command>ALTER TABLE
-    ONLY</command> will be rejected.
-   </para>
-
-   <para>
-    A recursive <literal>DROP COLUMN</literal> operation will remove a
-    descendant table's column only if the descendant does not inherit
-    that column from any other parents and never had an independent
-    definition of the column.  A nonrecursive <literal>DROP
-    COLUMN</literal> (i.e., <command>ALTER TABLE ONLY ... DROP
-    COLUMN</command>) never removes any descendant columns, but
-    instead marks them as independently defined rather than inherited.
-    A nonrecursive <literal>DROP COLUMN</literal> command will fail for a
-    partitioned table, because all partitions of a table must have the same
-    columns as the partitioning root.
-   </para>
-
-   <para>
-    The actions for identity columns (<literal>ADD
-    GENERATED</literal>, <literal>SET</literal> etc., <literal>DROP
-    IDENTITY</literal>), as well as the actions
-    <literal>CLUSTER</literal>, <literal>OWNER</literal>,
-    and <literal>TABLESPACE</literal> never recurse to descendant tables;
-    that is, they always act as though <literal>ONLY</literal> were specified.
-    Actions affecting trigger states recurse to partitions of partitioned
-    tables (unless <literal>ONLY</literal> is specified), but never to
-    traditional-inheritance descendants.
-    Adding a constraint recurses only for <literal>CHECK</literal> constraints
-    that are not marked <literal>NO INHERIT</literal>.
-   </para>
-
    <para>
     Changing any part of a system catalog table is not permitted.
    </para>
-- 
2.34.1

From 19f0a7ec08bf6a95dd3af6742f7be7bf000acde1 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <[email-masked]>
Date: Wed, 7 Jan 2026 14:53:50 -0700
Subject: [PATCH 2/2] doc Clarify ALTER TABLE edits

---
 doc/src/sgml/ref/alter_table.sgml | 144 +++++++++++++-----------------
 1 file changed, 62 insertions(+), 82 deletions(-)

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index b1190fae968..75a26087eb6 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -173,7 +173,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       When applied to a partitioned table, the column is added to the
-      partitioned table definition and is implicitly present in all
+      partitioned table definition and is implicitly added to all
       partitions. Specifying <literal>ONLY</literal> is not allowed, and
       this command cannot be used on individual partitions.
      </para>
@@ -232,9 +232,9 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       When applied to a partitioned table, the data type change is applied
-      to the partitioned table definition and affects all partitions.
-      Specifying <literal>ONLY</literal> is not allowed, and this command
-      cannot be used on individual partitions.
+      to the partitioned table definition and is implicitly applied to all
+      partitions. Specifying <literal>ONLY</literal> is not allowed,
+      and this command cannot be used on individual partitions.
      </para>
     </listitem>
    </varlistentry>
@@ -251,10 +251,9 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       When applied to a partitioned table, the default value is propagated
-      to all existing partitions unless <literal>ONLY</literal> is specified.
-      New partitions created afterwards inherit the default from the
-      partitioned table, but individual partitions may define a different
-      default.
+      to all partitions unless <literal>ONLY</literal> is specified.
+      Newly created partitions inherit the default from the partitioned table
+      unless they define a different default.
      </para>
     </listitem>
    </varlistentry>
@@ -289,8 +288,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       children can disallow nulls even if the parent allows them, but not
       the other way around. It is also possible to apply
       <literal>SET NOT NULL</literal> or <literal>DROP NOT NULL</literal> to
-      <literal>ONLY</literal> the parent table, which does not affect the
-      children.
+      <literal>ONLY</literal> the parent table.
      </para>
     </listitem>
    </varlistentry>
@@ -313,10 +311,9 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       When applied to a partitioned table, the generation expression is
-      propagated to all existing partitions unless <literal>ONLY</literal>
-      is specified. New partitions created afterwards inherit the
-      expression from the partitioned table, while individual partitions
-      may define a different expression.
+      propagated to all partitions unless <literal>ONLY</literal>
+      is specified. Newly created partitions inherit the expression from the
+      partitioned table unless they define a different expression.
      </para>
     </listitem>
    </varlistentry>
@@ -368,7 +365,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       When applied to a partitioned table, the identity property is defined
-      on the partitioned table definition and applies to all partitions.
+      on the partitioned table and is applied to all partitions.
       Specifying <literal>ONLY</literal> is not allowed, and these forms
       cannot be used on individual partitions.
      </para>
@@ -388,7 +385,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      <para>
       When applied to a partitioned table, these forms alter the sequence
       associated with the identity column on the partitioned table
-      definition and affect all partitions. Specifying <literal>ONLY</literal>
+      and all individual partitions. Specifying <literal>ONLY</literal>
       is not allowed, and these forms cannot be used on individual
       partitions.
      </para>
@@ -456,11 +453,10 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       <literal>SHARE UPDATE EXCLUSIVE</literal> lock.
      </para>
      <para>
-      For partitioned tables, these forms can be applied independently to
-      the partitioned table and to individual partitions. Changes made to
-      the partitioned table do not propagate to existing partitions, and
-      partitions created afterwards do not inherit the setting.
-      Specifying <literal>ONLY</literal> is allowed but has no effect.
+      For partitioned tables, these forms must be applied separately to
+      the partitioned table and/or to individual partitions.
+      Newly created partitions do not inherit their attribute options from the
+      partitioned table.
      </para>
     </listitem>
    </varlistentry>
@@ -499,9 +495,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      <para>
       When applied to a partitioned table, the storage setting is propagated
       to all existing partitions unless <literal>ONLY</literal> is specified.
-      New partitions created afterwards inherit the setting from the
-      partitioned table, while individual partitions may use a different
-      storage setting.
+      Newly created partitions inherit the setting from the partitioned table
+      unless they define a different storage setting.
      </para>
     </listitem>
    </varlistentry>
@@ -534,12 +529,11 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       at the time of data insertion to determine the method to use.
      </para>
      <para>
-      When applied to a partitioned table, the compression setting is applied
-      to the partitioned table definition and does not propagate to existing
-      partitions. New partitions created afterwards inherit the setting from
-      the partitioned table, while individual partitions may use a different
-      compression method. Specifying <literal>ONLY</literal> is allowed but has
-      no effect.
+      When applied to a partitioned table, the compression method must be
+      applied separately to the partitioned table and/or to individual partitions.
+      Specifying <literal>ONLY</literal> is allowed but has no effect.
+      However, newly created partitions inherit the compression method from the
+      partitioned table unless they define a different compression method.
      </para>
     </listitem>
    </varlistentry>
@@ -584,9 +578,9 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       When applied to a partitioned table, the constraint is added to the
-      partitioned table and is automatically applied to all partitions.
-      Specifying <literal>ONLY</literal> is not allowed. New partitions
-      created afterwards inherit the constraint from the partitioned table.
+      partitioned table and is implicitly added to all partitions.
+      Specifying <literal>ONLY</literal> is not allowed.
+      Newly created partitions inherit constraints from the partitioned table.
      </para>
     </listitem>
    </varlistentry>
@@ -627,7 +621,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       This form is not supported on partitioned tables, but can be used on
-      individual (leaf) partitions.
+      individual partitions.
      </para>
      <note>
       <para>
@@ -651,7 +645,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       When applied to a partitioned table, the constraint is altered on the
-      partitioned table definition and the change applies to all partitions.
+      partitioned table definition is implicitly applied to all partitions.
       Specifying <literal>ONLY</literal> is not allowed, and this command
       cannot be used on individual partitions.
      </para>
@@ -676,7 +670,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       These forms are not supported on partitioned tables, but can be used
-      on individual (leaf) partitions.
+      on individual partitions.
      </para>
      </listitem>
     </varlistentry>
@@ -717,9 +711,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      <para>
       When applied to a partitioned table, the constraint is dropped from
       all existing partitions unless <literal>ONLY</literal> is specified.
-      New partitions created afterwards do not include the dropped
-      constraint, while individual partitions may drop the constraint
-      independently of the partitioned table.
+      Individual partitions may drop constraints independently of the
+      partitioned table.
      </para>
     </listitem>
    </varlistentry>
@@ -793,11 +786,10 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       described above.
      </para>
      <para>
-      For partitioned tables, these forms can be applied independently to
-      the partitioned table and to individual partitions. Changes made to
-      the partitioned table do not propagate to existing partitions, and
-      partitions created afterwards do not inherit the setting.
-      Specifying <literal>ONLY</literal> is allowed but has no effect.
+      For partitioned tables, these forms must be applied separately to
+      the partitioned table and/or to individual partitions.
+      Newly created partitions do not inherit the setting from the
+      partitioned table.
      </para>
     </listitem>
    </varlistentry>
@@ -815,11 +807,10 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       <link linkend="sql-createpolicy"><command>CREATE POLICY</command></link>.
      </para>
      <para>
-      For partitioned tables, these forms can be applied independently to
-      the partitioned table and to individual partitions. Changes made to
-      the partitioned table do not propagate to existing partitions, and
-      partitions created afterwards do not inherit the setting.
-      Specifying <literal>ONLY</literal> is allowed but has no effect.
+      For partitioned tables, these forms must be applied separately to
+      the partitioned table and/or to individual partitions.
+      Newly created partitions do not inherit the setting from the
+      partitioned table.
      </para>
     </listitem>
    </varlistentry>
@@ -837,11 +828,10 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       <link linkend="sql-createpolicy"><command>CREATE POLICY</command></link>.
      </para>
      <para>
-      For partitioned tables, these forms can be applied independently to
-      the partitioned table and to individual partitions. Changes made to
-      the partitioned table do not propagate to existing partitions, and
-      partitions created afterwards do not inherit the setting.
-      Specifying <literal>ONLY</literal> is allowed but has no effect.
+      For partitioned tables, these forms must be applied separately to
+      the partitioned table and/or to individual partitions.
+      Newly created partitions do not inherit the setting from the
+      partitioned table.
      </para>
     </listitem>
    </varlistentry>
@@ -859,7 +849,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       This form is not supported on partitioned tables, but can be used on
-      individual (leaf) partitions.
+      individual partitions.
      </para>
     </listitem>
    </varlistentry>
@@ -878,7 +868,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       This form is not supported on partitioned tables, but can be used on
-      individual (leaf) partitions.
+      individual partitions.
      </para>
     </listitem>
    </varlistentry>
@@ -891,12 +881,6 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       system column.  As <literal>oid</literal> system columns cannot be
       added anymore, this never has an effect.
      </para>
-     <para>
-      For partitioned tables, this form behaves the same as for regular
-      tables; it has no effect on either the partitioned table or its
-      partitions. Specifying <literal>ONLY</literal> is allowed but has no
-      effect.
-     </para>
     </listitem>
    </varlistentry>
 
@@ -972,7 +956,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       This form is not supported on partitioned tables, but can be used on
-      individual (leaf) partitions.
+      individual partitions.
      </para>
     </listitem>
    </varlistentry>
@@ -1001,7 +985,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       This form is not supported on partitioned tables, but can be used on
-      individual (leaf) partitions.
+      individual partitions.
      </para>
     </listitem>
    </varlistentry>
@@ -1016,7 +1000,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       When applied to a partitioned table, this form is accepted but has no
-      effect. It can be used on individual (leaf) partitions, where it
+      effect.  It can be used on individual partitions, where it
       behaves as for a regular table.
      </para>
     </listitem>
@@ -1109,11 +1093,10 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       or foreign table to the specified user.
      </para>
      <para>
-      For partitioned tables, this form can be applied independently to the
-      partitioned table and to individual partitions. Changing the owner of
-      the partitioned table does not affect existing partitions, and
-      partitions created afterwards do not inherit the new owner.
-      Specifying <literal>ONLY</literal> is allowed but has no effect.
+      For partitioned tables, this form must be applied separately to
+      the partitioned table and/or to individual partitions.
+      Newly created partitions do not inherit their owner from the
+      partitioned table.
      </para>
     </listitem>
    </varlistentry>
@@ -1173,11 +1156,10 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </variablelist></para>
 
      <para>
-      For partitioned tables, this form can be applied independently to the
-      partitioned table and to individual partitions. Changing the replica
-      identity of the partitioned table does not affect existing partitions,
-      and partitions created afterwards do not inherit the setting.
-      Specifying <literal>ONLY</literal> is allowed but has no effect.
+      For partitioned tables, this form must be applied independently to the
+      partitioned table and/or to individual partitions.
+      Newly created partitions do not inherit the setting from the
+      partitioned table.
      </para>
     </listitem>
    </varlistentry>
@@ -1196,8 +1178,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      <para>
       For partitioned tables, this form behaves the same as for regular
       tables. Renaming a partitioned table, column, or constraint does not
-      propagate to partitions, and <literal>ONLY</literal> can be specified
-      but has no effect.
+      propagate to partitions.
      </para>
     </listitem>
    </varlistentry>
@@ -1210,11 +1191,10 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       constraints, and sequences owned by table columns are moved as well.
      </para>
      <para>
-      For partitioned tables, this form can be applied independently to the
-      partitioned table and to individual partitions. Moving the partitioned
-      table to another schema does not affect existing partitions, and
-      partitions created afterwards do not inherit the new schema.
-      Specifying <literal>ONLY</literal> is allowed but has no effect.
+      For partitioned tables, this form must be applied independently to the
+      partitioned table and/or to individual partitions.
+      Newly created partitions do not inherit their schema from the
+      partitioned table.
      </para>
     </listitem>
    </varlistentry>
-- 
2.34.1

---

From: Chao Li <[email-masked]>
Date: Mon, 12 Jan 2026 10:45:55 +0800

> On Jan 10, 2026, at 00:12, David G. Johnston <[email-masked]> wrote:
> 
> > Saying that "ONLY" is a no-op when the observed behavior is that only the mentioned tables are affected seems wrong.  I've removed those instances.
> 
> Maybe the original phrasing “has no effect” wasn’t clear for what I meant. What I was trying to express is that ONLY is intended to control whether an action propagates to child tables: with ONLY it should not propagate, and without ONLY it should.
> 
> For these particular sub-commands, however, the observed behavior is that they behave the same with or without ONLY. From a documentation perspective, stating that explicitly could help avoid user confusion.
> 
> Separately, I do have a plan to tighten this behavior in the future: for these commands, specifying ONLY would raise an error instead. If such a change is merged later, the documentation note could naturally be removed at that point.
> 
> So I’d like to keep the statement for now, but I’m very happy to adjust the wording if you have a clearer phrasing to suggest.
> 
> I've removed some I missed and tweaked others.  I'm OK with leaving mention of ONLY in these sections but what happens is that ONLY becomes implicitly added to the command, which is what I'd rather communicate.  The remaining wording is a bit redundant now but flows nicely.

Changing the phrase “has no effect” to “implicitly” looks good to me. ONLY is implicit on the following sub-commands:

 * SET/RESET (attribute_option = value)
 * ENABLE/DISABLE [ REPLICA | ALWAYS] RULE
 * ENABLE/DISABLE ROW LEVEL SECURITY
 * NO FORCE / FORCE ROW LEVEL SECURITY
 * OWNER TO
 * REPLICA IDENTITY
 * SET SCHEMA
 * SET COMPRESSION
 * SET TABLESPACE
 * OF type
 * NOT OF
 * RENAME

I saw you removed “ONLY” statement from some of them and changing “has no effect” to “implicit” on rests. So, I just want to confirm if you intentionally removed those or just missed changing them?

> 
> Before I integrate your edits and prepare v3, I’d appreciate hearing your thoughts on the points about ONLY and “newly created”.
> 
> 
> As I continue to think about the "newly created" material the more I believe it is misplaced.  That there is existing wording to that effect doesn't change my conclusion.  I would add no additional text here even if you don't want to remove the existing mentions at this point.  But I think the scope of this patch should be increased to fix this misplacement as well.  Since moving content - refactoring - is what is happening here.  In the attached 0003 I've removed the paragraphs that this patch now makes redundant within the alter table documentation.  I wouldn't mind if they got moved to somewhere in Chapter 5.12 (Table Partitioning) and not just erased, along with ensuring that 5.12 includes how table creation  definition inheritance works and removing those mentions from the alter table docs as well.

A new partition automatically inheriting the parent’s setting is an expected behavior, and most of sub-commands meet the expectation. So I’m fine to remove the “newly created” material from these “good" sub-commands.

Only a few sub-commands break the expectation, they are:

 * SET STATISTICS
 * SET/RESET (attribute_option = value)
 * ENABLE/DISABLE [ REPLICA | ALWAYS] RULE
 * ENABLE/DISABLE ROW LEVEL SECURITY
 * NO FORCE / FORCE ROW LEVEL SECURITY
 * OWNER TO
 * REPLICA IDENTITY
 * SET SCHEMA

The current behavior (not inherit) is questionable, we will need separate discussions for each of them to clarify if that’s intended or “bugs”. So, how about only retain the “newly created” material for these sub-commands and remove from the rests? In this case, I don’t think we need to update 5.12.  

What I am thinking is that, we will eventually remove the “newly created” material from these sub-commands, because next step we are going to fix the behavior on them one by one. Maybe some of them are designed to not “inherit the parent’s setting”, then we can add a paragraph/section to 5.12 to describe that.

> 
> I'm not sure whether I'd fully remove all that content since some of it does pertain just to table inheritance.  That feature seems like something best related to notes and not brought into the main flow like you are doing with partitioned tables.
> 
> David J.
> 
> 
> <v2-0001-docs-Clarify-ALTER-TABLE-v1.patch><v2-0003-docs-ONLY-tweaks-and-bulk-note-removal.patch><v2-0002-docs-Clarify-ALTER-TABLE-v1-edits.patch>

--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/

---

From: "David G. Johnston" <[email-masked]>
Date: Sun, 11 Jan 2026 21:04:28 -0700

On Sunday, January 11, 2026, Chao Li <[email-masked]> wrote:

>
> The current behavior (not inherit) is questionable, we will need separate
> discussions for each of them to clarify if that’s intended or “bugs”. So,
> how about only retain the “newly created” material for these sub-commands
> and remove from the rests? In this case, I don’t think we need to update
> 5.12.
>
> What I am thinking is that, we will eventually remove the “newly created”
> material from these sub-commands, because next step we are going to fix the
> behavior on them one by one. Maybe some of them are designed to not
> “inherit the parent’s setting”, then we can add a paragraph/section to 5.12
> to describe that.
>

I’m against having material in the alter table command that doesn’t
describe the effects of executing alter table.  I’d consider possibly
pointing out if the cascade behavior of alter table doesn’t match up with
the inherit behavior of create table.  There doesn’t seem to be any such
discrepancies though.  I also have my doubts that any of this behavior is
going to change.  Better to behave as if it won’t.

David J.

---

From: Chao Li <[email-masked]>
Date: Mon, 12 Jan 2026 13:51:26 +0800

> On Jan 12, 2026, at 12:04, David G. Johnston <[email-masked]> wrote:
> 
> I also have my doubts that any of this behavior is going to change.  Better to behave as if it won’t.

Please see [1], people wanted to change the behavior from long time back. From the previous discussions, there were no objections on the behavior change. However, the blocker was about how to keep “consistent” behaviors across all sub-commands. That’s why I created this patch to clarify the current behaviors.

[1]  https://postgr.es/m/[email-masked]

Best regards,

---

From: "David G. Johnston" <[email-masked]>
Date: Mon, 12 Jan 2026 17:20:28 -0700

On Sun, Jan 11, 2026 at 10:52 PM Chao Li <[email-masked]> wrote:

> If we stop here, these inconsistencies will remain indefinitely, which I
> believe nobody really wants. With that in mind, I’d like to suggest a
> two-phase approach.
>
> Phase 1: Document current behavior and set expectations
>
> * Identify all ALTER TABLE actions involved in these inconsistencies.
> * Update the ALTER TABLE and CREATE TABLE documentation to clearly
> describe the current behavior for partitioned tables, and (where
> appropriate) the intended or ideal behavior.
> * Explicitly document the meaning of ONLY for partitioned tables, and note
> that some actions may behave differently, with details described in each
> action’s section.

I agree, we should modify alter to note the cascade and/or non-cascade
scenarios and modify create to note the things that are (not) inherited.
I'm fine with the "newly created" stuff being put into create table instead
of touching 5.12.

We should not be documenting "ideal behavior" - only actual behavior.

We should indeed document that ONLY, if added to an alter command that
would cascade to partitions, prevents that cascading.  If added to a
command that wouldn't cascade anyway it is usually accepted as just
specifying the default behavior.  There is no way to indicate explicitly
that one wishes to cascade.

I still have my doubts whether changing long-standing behavior is going to
happen.  But that is also fairly immaterial since best practice is to
proceed without even trying to predict the future and instead just deal
with what is in front of us right now.

David J.

---

From: Chao Li <[email-masked]>
Date: Tue, 13 Jan 2026 14:27:51 +0800

On Jan 13, 2026, at 08:20, David G. Johnston <[email-masked]>
wrote:

* Identify all ALTER TABLE actions involved in these inconsistencies.
* Update the ALTER TABLE and CREATE TABLE documentation to clearly describe
the current behavior for partitioned tables, and (where appropriate) the
intended or ideal behavior.
* Explicitly document the meaning of ONLY for partitioned tables, and note
that some actions may behave differently, with details described in each
action’s section.

I have removed all “newly created” from "alter table” doc, and added a
paragraph in “create table” doc for those settings a new partition doesn’t
inherit from the parent.

Absolutely.

I went through all sub-commands and added ONLY back.

Let’s leave the discussion to separate threads.

Hi David, I have squashed all commits into one. As you have contributed a
lot of work, I marked you as an author as well as a reviewer. Thanks a lot.
Please take a look at v3 again.

Best regards,

---

From: "David G. Johnston" <[email-masked]>
Date: Sat, 17 Jan 2026 09:15:26 -0700

diff --git a/doc/src/sgml/ref/alter_table.sgml
b/doc/src/sgml/ref/alter_table.sgml
index 8577e2cdcdd..188f8f3e04b 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -746,11 +746,8 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       When this command is applied to a partitioned table, the states of
-      corresponding clone triggers in existing partitions are updated too,
-      unless <literal>ONLY</literal> is specified. Triggers in partitions
-      created afterwards inherit the trigger state from the partitioned
-      table, while individual partitions may configure trigger states
-      independently.
+      corresponding clone triggers are updated too, unless
<literal>ONLY</literal>
+      is specified.
      </para>
      <para>
       This command acquires a <literal>SHARE ROW EXCLUSIVE</literal> lock.

"existing partitions" is implied here; and the rest is material for create
table or implied by the optional ONLY (as we rely upon elsewhere):
<para>
For partitioned tables, this action applies to the partitioned table
and all of its partitions unless <literal>ONLY</literal> is specified.
</para>

@@ -882,14 +879,11 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
       See <xref linkend="tableam"/> for more information.
      </para>
      <para>
-      When applied to a partitioned table, there is no data to rewrite.
-      Partitions created afterwards will use the access method specified
-      on the partitioned table, if any, unless overridden by a
-      <literal>USING</literal> clause; otherwise they default to
-      <varname>default_table_access_method</varname>. Specifying
-      <literal>DEFAULT</literal> removes a previously set access method,
-      causing future partitions to use
-      <varname>default_table_access_method</varname>.
+      When applied to a partitioned table, there is no data to rewrite,
+      only the default for newly created partitions is changed.
+      Specifying <literal>DEFAULT</literal> removes a previously set
access method,
+      causing future partitions to use
<varname>default_table_access_method</varname>.
+      Individual partitions are affected just like any other regular table.
      </para>
     </listitem>
    </varlistentry>

The wording of 'changes the default' adequately condenses the existing
wording.  I'm 50/50 on removing mention of default_table_access_method.

@@ -902,10 +896,8 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
       moves the data file(s) associated with the table to the new
tablespace.
       Indexes on the table, if any, are not moved; but they can be moved
       separately with additional <literal>SET TABLESPACE</literal>
commands.
-      When applied to a partitioned table, no data is moved. Existing
-      partitions are not affected, but partitions created afterwards with
-      <command>CREATE TABLE PARTITION OF</command> will use the specified
-      tablespace unless overridden by a <literal>TABLESPACE</literal>
clause.
+      When applied to a partitioned table, no data is moved, only the
default
+      for newly created partitions is changed.
      </para>
      <para>
       All tables in the current database in a tablespace can be moved by
using

Again, 'default' can carry a lot of implied meaning here.

@@ -984,7 +976,7 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       When applied to a partitioned table, this form is accepted but has no
-      effect.  It can be used on individual partitions, where it
+      practical effect.  It can be used on individual partitions, where it
       behaves as for a regular table.
      </para>
     </listitem>

I don't quite like saying 'no effect' since the command does function; and
explaining why it is useless seemed a bit much, so just added the word
'practical' and left it to the reader to infer that the lack of storage and
inheritance makes any such property on the partitioned table itself useless.

diff --git a/doc/src/sgml/ref/create_table.sgml
b/doc/src/sgml/ref/create_table.sgml
index 780e4f0799f..835f609e2a6 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -635,9 +635,9 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM

      <para>
       When a new partition is created, it generally inherits the current
-      definition-level settings of the parent partitioned table. However,
+      definition-level properties of the parent partitioned table. However,
       some table properties are not inherited automatically. In particular,
-      settings related to ownership, schema, replica identity, row-level
+      properties related to ownership, schema, replica identity, row-level
       security configuration, per-attribute statistics targets, and
       per-attribute options are not inherited unless explicitly specified
       for the partition.

diff --git a/doc/src/sgml/ref/create_table.sgml
b/doc/src/sgml/ref/create_table.sgml
index 780e4f0799f..835f609e2a6 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -635,9 +635,9 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM

      <para>
       When a new partition is created, it generally inherits the current
-      definition-level settings of the parent partitioned table. However,
+      definition-level properties of the parent partitioned table. However,
       some table properties are not inherited automatically. In particular,
-      settings related to ownership, schema, replica identity, row-level
+      properties related to ownership, schema, replica identity, row-level
       security configuration, per-attribute statistics targets, and
       per-attribute options are not inherited unless explicitly specified
       for the partition.

Dislike the word "setting" here as it clashes with GUC.  Was going to use
"attribute" but its used for column.  Settled on "property".
"Definition-level" seems redundant, consider removing it.

Attached patch as text.

David J.
From 35b04e964289ac049907bdc19f36328d2d6c4770 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <[email-masked]>
Date: Sat, 17 Jan 2026 09:12:25 -0700
Subject: [PATCH] v3 edits

---
 doc/src/sgml/ref/alter_table.sgml  | 28 ++++++++++------------------
 doc/src/sgml/ref/create_table.sgml |  4 ++--
 2 files changed, 12 insertions(+), 20 deletions(-)

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 8577e2cdcdd..6131632d20b 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -746,11 +746,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       When this command is applied to a partitioned table, the states of
-      corresponding clone triggers in existing partitions are updated too,
-      unless <literal>ONLY</literal> is specified. Triggers in partitions
-      created afterwards inherit the trigger state from the partitioned
-      table, while individual partitions may configure trigger states
-      independently.
+      corresponding clone triggers are updated too, unless <literal>ONLY</literal>
+      is specified.
      </para>
      <para>
       This command acquires a <literal>SHARE ROW EXCLUSIVE</literal> lock.
@@ -882,14 +879,11 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       See <xref linkend="tableam"/> for more information.
      </para>
      <para>
-      When applied to a partitioned table, there is no data to rewrite.
-      Partitions created afterwards will use the access method specified
-      on the partitioned table, if any, unless overridden by a
-      <literal>USING</literal> clause; otherwise they default to
-      <varname>default_table_access_method</varname>. Specifying
-      <literal>DEFAULT</literal> removes a previously set access method,
-      causing future partitions to use
-      <varname>default_table_access_method</varname>.
+      When applied to a partitioned table, there is no data to rewrite,
+      only the default for newly created partitions is changed.
+      Specifying <literal>DEFAULT</literal> removes a previously set access method,
+      causing future partitions to use <varname>default_table_access_method</varname>.
+      Individual partitions are affected just like any other regular table.
      </para>
     </listitem>
    </varlistentry>
@@ -902,10 +896,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
       moves the data file(s) associated with the table to the new tablespace.
       Indexes on the table, if any, are not moved; but they can be moved
       separately with additional <literal>SET TABLESPACE</literal> commands.
-      When applied to a partitioned table, no data is moved. Existing
-      partitions are not affected, but partitions created afterwards with
-      <command>CREATE TABLE PARTITION OF</command> will use the specified
-      tablespace unless overridden by a <literal>TABLESPACE</literal> clause.
+      When applied to a partitioned table, no data is moved, only the default
+      for newly created partitions is changed.
      </para>
      <para>
       All tables in the current database in a tablespace can be moved by using
@@ -984,7 +976,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
      </para>
      <para>
       When applied to a partitioned table, this form is accepted but has no
-      effect.  It can be used on individual partitions, where it
+      practical effect.  It can be used on individual partitions, where it
       behaves as for a regular table.
      </para>
     </listitem>
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index 780e4f0799f..835f609e2a6 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -635,9 +635,9 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
 
      <para>
       When a new partition is created, it generally inherits the current
-      definition-level settings of the parent partitioned table. However,
+      definition-level properties of the parent partitioned table. However,
       some table properties are not inherited automatically. In particular,
-      settings related to ownership, schema, replica identity, row-level
+      properties related to ownership, schema, replica identity, row-level
       security configuration, per-attribute statistics targets, and
       per-attribute options are not inherited unless explicitly specified
       for the partition.
-- 
2.43.0

---

From: Chao Li <[email-masked]>
Date: Mon, 19 Jan 2026 16:20:06 +0800

On Jan 18, 2026, at 00:15, David G. Johnston <[email-masked]>
wrote:

Agreed.

Updated to your version.

Agreed.

Agreed.

      <para>

      <para>

Updated.

Hi David,

Thanks again for your review. I have integrated all your edits to v4. Once
you consider the changes are okay, can you please mark the CF entry [1] as
Ready for Committer?

[1] https://commitfest.postgresql.org/patch/6379/

Best regards,