Re: docs: clarify ALTER TABLE behavior on partitioned tables - Mailing list pgsql-hackers

> 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/