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


> On Jan 10, 2026, at 00:12, David G. Johnston =
<david.g.johnston@gmail.com> wrote:
>=20
> On Fri, Jan 9, 2026 at 1:11=E2=80=AFAM Chao Li =
<li.evan.chao@gmail.com> wrote:
> >=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.
>=20
> Maybe the original phrasing =E2=80=9Chas no effect=E2=80=9D wasn=E2=80=99=
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.
>=20
> 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.
>=20
> 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.
>=20
> 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.
>=20
> 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 =E2=80=9Chas no effect=E2=80=9D to =E2=80=9Cimplicitly=
=E2=80=9D looks good to me. ONLY is implicit on the following =
sub-commands:

 * SET/RESET (attribute_option =3D 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 =E2=80=9CONLY=E2=80=9D statement from some of them and =
changing =E2=80=9Chas no effect=E2=80=9D to =E2=80=9Cimplicit=E2=80=9D =
on rests. So, I just want to confirm if you intentionally removed those =
or just missed changing them?

>=20
> 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.
>=20
>=20
> 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=E2=80=99s setting is =
an expected behavior, and most of sub-commands meet the expectation. So =
I=E2=80=99m fine to remove the =E2=80=9Cnewly created=E2=80=9D material =
from these =E2=80=9Cgood" sub-commands.

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

 * SET STATISTICS
 * SET/RESET (attribute_option =3D 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=E2=80=99s =
intended or =E2=80=9Cbugs=E2=80=9D. So, how about only retain the =
=E2=80=9Cnewly created=E2=80=9D material for these sub-commands and =
remove from the rests? In this case, I don=E2=80=99t think we need to =
update 5.12. =20

What I am thinking is that, we will eventually remove the =E2=80=9Cnewly =
created=E2=80=9D 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 =E2=80=9Cinherit the parent=E2=80=99s setting=E2=80=9D, =
then we can add a paragraph/section to 5.12 to describe that.

>=20
> 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.
>=20
> David J.
>=20
>=20
> =
<v2-0001-docs-Clarify-ALTER-TABLE-v1.patch><v2-0003-docs-ONLY-tweaks-and-b=
ulk-note-removal.patch><v2-0002-docs-Clarify-ALTER-TABLE-v1-edits.patch>

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