Обсуждение: docs: clarify ALTER TABLE behavior on partitioned tables

> On Jan 7, 2026, at 13:59, Chao Li <li.evan.chao@gmail.com> wrote:
>
> Hi Hackers,
>
> This task is derived from [1], as “ALTER TABLE” is considered to exhibit “inconsistent” behaviors with partitioned
tables.From the current documentation of “ALTER TABLE”, readers won’t get enough information to form a clear
understandingof how these commands behave with partitioned tables, and this gap needs to be addressed. 
>
> I have spent several days verifying sub-commands of “ALTER TABLE” one by one against partitioned tables from the
followingpoints: 
>
> 1) Does an action on a parent partitioned table propagate to child partitions?
> 2) Does a value set on a parent partitioned table get automatically inherited by newly created partitions?
> 3) Does “ONLY partitioned-table” work as the documentation states (preventing propagation)?
> 4) Can an action be performed on a partitioned table and its children independently?
>
> From these four criteria, sub-commands fall into the following categories:
>
> C1 - Sub-commands that can only be used with a partitioned table; ONLY will lead to an error; using them with a child
partitionwill lead to an error. 
>
>  * ADD COLUMN
>  * DROP COLUMN
>  * SET DATA TYPE
>  * DROP EXPRESSION
>  * ADD GENERATED AS IDENTITY
>  * ADD GENERATED
>  * DROP IDENTITY
>  * SET sequence_option
>  * RESTART
>  * ALTER CONSTRAINT
>
>
> C2 - Sub-commands where using them with a partitioned table will automatically propagate to child partitions; ONLY
preventspropagation; new partitions 
> inherit the parent’s new setting; and child partitions can be set to different values than the parent.
>
>  * SET DEFAULT
>  * DROP DEFAULT
>  * SET EXPRESSION AS
>  * SET STORAGE
>  * DROP CONSTRAINT
>  * ENABLE/DISABLE [ REPLICA | ALWAYS] TRIGGER
>
> C3 - Slightly different from C2: new partitions will not inherit the parent’s setting.
>
>  * SET STATISTICS
>
> C4 - Sub-commands that can be used on a partitioned table and child partitions independently; actions on the parent
willnot propagate to children; children 
> can have different settings than the parent; new partitions will not inherit the parent’s setting; ONLY can be used
buthas no effect. 
>
>  * 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
>
> C5 - Slightly different from C4: new partitions will automatically inherit the parent’s setting.
>
>  * SET COMPRESSION
>
> C6 - Slightly different from C2: ONLY cannot be used with a parent partitioned table, meaning the setting must be
propagatedto child partitions. 
>
>  * ADD table_constraint
>
> C7 - Sub-commands that cannot be used with a partitioned table, but can only be used with a leaf partition.
>
>  * ADD table_constraint_with_index
>  * ALTER CONSTRAINT … INHERIT / NO INHERIT
>  * CLUSTER ON
>  * SET WITHOUT CLUSTER
>  * SET { LOGGED | UNLOGGED }
>  * SET (storage_parameter)
>
>
> C8 - Slightly different from C1: child partitions can set different values than the parent.
>
>  * VALIDATE CONSTRAINT
>
> C9 - Slightly different from C2: if the parent has a value, then new partitions will inherit that value; otherwise,
theyuse the default from the GUC. 
>
>  * SET ACCESS METHOD
>
> C10 - Sub-commands used with a parent partitioned table will NOT propagate to child partitions; but new partitions
willautomatically inherit the parent’s setting; partitions can be set to different values than the parent; ONLY can be
usedbut has no effect. 
>
> * SET TABLESPACE
>
> C11 - Sub-commands used with a parent partitioned table won’t fail but do nothing; using them with a leaf partition
worksas with a normal table. 
>
>  * RESET (storage_parameter)  # this appears questionable, because SET (storage_parameter) is not allowed on a
partitionedtable 
>
> C12 - Sub-commands that don’t support partitioned tables; neither parent partitioned tables nor child partitions.
>
>  * INHERIT parent_table
>  * NO INHERIT parent_table
>
> C13 - Sub-commands that support only parent partitioned tables; ONLY can be used but has no effect; using them with a
childpartition will fail. 
>   * OF type
>  * NOT OF
>
> C14 - Sub-commands that treat partitioned tables, either parent partitioned tables or child partitions, as normal
tables,so no propagation occurs; ONLY can be used but has no effect. 
>
>  * RENAME
>
> C15 - Sub-commands that operate on partitioned tables.
>
>  * ATTACH PARTITION
>  * DETACH PARTITION
>  * MERGE PARTITIONS
>  * SPLIT PARTITION
>
> — End of categories —
>
> With these categories, we can clearly see where “inconsistencies” exist, and measure whether future changes mitigate
these“inconsistencies” or make them worse. Some categories include only one or two sub-commands; maybe they can be
adjustedto other categories so that some categories are eliminated and the overall “inconsistency” situation is
improved.
>
> In this patch, I just want to add clarifications to the “ALTER TABLE” documentation, without changing any existing
behaviors.
>
> This patch is pretty massive. Although I have done a self-review, I may still have missed things. I know this patch
isa challenge for reviewers, so I’m open to any suggestions to make it easier to review and commit, such as splitting
itin some way. 
>
>
> [1] https://postgr.es/m/CAEoWx2nJ71hy8R614HQr7vQhkBReO9AANPODPg0aSQs74eOdLQ@mail.gmail.com
>
> --
> Chao Li (Evan)
> HighGo Software Co., Ltd.
> https://www.highgo.com/
>
>
>
>
> <v1-0001-docs-clarify-ALTER-TABLE-behavior-on-partitioned-.patch>

Added to CF: https://commitfest.postgresql.org/patch/6379/

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

> On Jan 8, 2026, at 06:17, David G. Johnston <david.g.johnston@gmail.com> wrote:
>
> On Wed, Jan 7, 2026 at 1:29 AM Chao Li <li.evan.chao@gmail.com> wrote:
>
> >
> >
> > [1] https://postgr.es/m/CAEoWx2nJ71hy8R614HQr7vQhkBReO9AANPODPg0aSQs74eOdLQ@mail.gmail.com
> >
> > <v1-0001-docs-clarify-ALTER-TABLE-behavior-on-partitioned-.patch>
>
> Added to CF: https://commitfest.postgresql.org/patch/6379/
>
>
> Fairly easy to review in its current form.
>
> I've included my changes as a patch over your version 1.

Hi David,

Thank you very much for the careful review. Your edits make the documentation clearer and more fluent, and I agree with
mostof your suggestions. 

>
> 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'veremoved 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
intendedto 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.
Froma 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
errorinstead. 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 saw you removed such “has no effect” from “DISABLE/ENABLE RULE”, “DISABLE/ENABLE ROW LEVEL SECURITY”, “NO FORCE ROW
LEVELSECURITY”,  and , and retained some. 

>
> I tried to keep the "and 'is implicitly <actioned>" verbiage consistent throughout.  "Implicitly present" just seems
offregardless of consistency. 

Agreed.

>
> "new partitions created in the future" - this is wordy given that "new" implies "created in the future".  Went with a
simple"Newly created partitions". 

Agreed.

>
> I did mentally note at the end of this review session that quite a bit of text is spent saying how "create table"
worksin this "alter table" reference.  I didn't try to address it though. 

The current documentation already mentions the behavior of newly created partitions in some sections. For example:

SET ACCESS METHOD
```
When applied to a partitioned table, there is no data to rewrite, but partitions created afterwards will default to the
givenaccess method unless overridden by a USING clause. 
```

SET TABLESPACE
```
When applied to a partitioned table, nothing is moved, but any partitions created afterwards with CREATE TABLE
PARTITIONOF will use that tablespace, unless overridden by a TABLESPACE clause. 
```

I think this helps users quickly understand the important implications for future partitions.

>
> You were using "can be applied independently" when in fact one "must" specify all desired tables to be acted upon in
thosesub-commands.  And, in that case in particular, if ONLY is accepted it would just do what the command already
does. I removed the mention of ONLY in these "must" cases. 
>

I saw you changed “independently” to “separately”, I agree with that part. For ONLY, as explained above, I want to
retainthe statement. 

> The majority of additions you made and existing mentions of "individual partitions" do not include the clarification
of"(leaf)".  I removed those that did - it seems like an unnecessary clarification. 
>

Agreed.

> If one has dropped a constraint from a partitioned table there would be no reason to expect that future newly created
partitionsmight somehow have it.  I removed the wording that stated that this was the case. 

That’s true. Agreed.

>
> It didn't seem necessary to point out that the obsolete backward compatible syntax for OIDS doesn't apply to
partition-relatedtables. 

Agreed.

>
> Overall it looks good.  The mentions of "newly created ... do [not] inherit" is my only place of doubt.  I'd be
inclinedto remove them all, and if they are not covered elsewhere, introduce a section to cover them in the DDL
chapter.

As mentioned above, the current documentation already describes the behavior of newly created partitions in some
sections,so I would prefer to retain these mentions for now. That said, I’m happy to wait for more opinions. 

Before I integrate your edits and prepare v3, I’d appreciate hearing your thoughts on the points about ONLY and “newly
created”.

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