Content-Type: text/plain;
	charset=utf-8
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3826.700.81\))
Subject: Re: docs: clarify ALTER TABLE behavior on partitioned tables
From: Chao Li <li.evan.chao@gmail.com>
In-Reply-To: <CAKFQuwbWNCX1M1e9_-3P9RVGo10huPjuqdL74FJ+-a5EW791KA@mail.gmail.com>
Date: Fri, 9 Jan 2026 16:11:09 +0800
Cc: Postgres hackers <pgsql-hackers@lists.postgresql.org>,
 Amit Kapila <amit.kapila16@gmail.com>
Content-Transfer-Encoding: quoted-printable
Message-Id: <D559C6FA-E101-47F3-BCDF-CEA7FFDF6154@gmail.com>
References: <CAEoWx2=mYhCfsnHaN96Qqwq5b0GVS2YgO3zpVqPPRd_iO52wRw@mail.gmail.com>
 <90F9169D-135C-45E5-8221-4F79DAED98E2@gmail.com>
 <CAKFQuwbWNCX1M1e9_-3P9RVGo10huPjuqdL74FJ+-a5EW791KA@mail.gmail.com>
To: "David G. Johnston" <david.g.johnston@gmail.com>
Archived-At: <https://www.postgresql.org/message-id/D559C6FA-E101-47F3-BCDF-CEA7FFDF6154%40gmail.com>
Precedence: bulk


> On Jan 8, 2026, at 06:17, David G. Johnston =
<david.g.johnston@gmail.com> wrote:
>=20
> On Wed, Jan 7, 2026 at 1:29=E2=80=AFAM Chao Li =
<li.evan.chao@gmail.com> wrote:
>=20
> >=20
> >=20
> > [1] =
https://postgr.es/m/CAEoWx2nJ71hy8R614HQr7vQhkBReO9AANPODPg0aSQs74eOdLQ@ma=
il.gmail.com
> >
> > <v1-0001-docs-clarify-ALTER-TABLE-behavior-on-partitioned-.patch>
>=20
> Added to CF: https://commitfest.postgresql.org/patch/6379/
>=20
>=20
> Fairly easy to review in its current form.
>=20
> 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 most of your =
suggestions.

>=20
> The main points of interest:
>=20
> 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 =E2=80=9Chas no effect=E2=80=9D wasn=E2=80=99t=
 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. =46rom 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=E2=80=99d like to keep the statement for now, but I=E2=80=99m very =
happy to adjust the wording if you have a clearer phrasing to suggest.

I saw you removed such =E2=80=9Chas no effect=E2=80=9D from =
=E2=80=9CDISABLE/ENABLE RULE=E2=80=9D, =E2=80=9CDISABLE/ENABLE ROW LEVEL =
SECURITY=E2=80=9D, =E2=80=9CNO FORCE ROW LEVEL SECURITY=E2=80=9D,  and , =
and retained some.

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

Agreed.

>=20
> "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.

>=20
> I did mentally note at the end of this review session that quite a bit =
of text is spent saying how "create table" works in 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 given access 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 PARTITION OF will use =
that tablespace, unless overridden by a TABLESPACE clause.
```

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

>=20
> You were using "can be applied independently" when in fact one "must" =
specify all desired tables to be acted upon in those sub-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.
>=20

I saw you changed =E2=80=9Cindependently=E2=80=9D to =E2=80=9Cseparately=E2=
=80=9D, I agree with that part. For ONLY, as explained above, I want to =
retain the 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.
>=20

Agreed.

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

That=E2=80=99s true. Agreed.

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

Agreed.

>=20
> Overall it looks good.  The mentions of "newly created ... do [not] =
inherit" is my only place of doubt.  I'd be inclined to 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=E2=80=99m happy to wait =
for more opinions.

Before I integrate your edits and prepare v3, I=E2=80=99d appreciate =
hearing your thoughts on the points about ONLY and =E2=80=9Cnewly =
created=E2=80=9D.

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