Обсуждение: DOCS - Clarify the publication 'publish_via_partition_root' default value.

Hi,

When reading the docs for the publication parameter
'publish_via_partition_root' [1], I felt there was too much mental
gymnastics required to understand the meaning of "the latter is the
default."

Why not just say clearly what the default value is?

PSA: a patch to do that.

======
[1]
https://www.postgresql.org/docs/current/sql-createpublication.html#SQL-CREATEPUBLICATION-PARAMS-WITH-PUBLISH-VIA-PARTITION-ROOT

Kind Regards,
Peter Smith.
Fujitsu Australia

On Thu, Dec 11, 2025 at 6:51 PM Peter Smith <smithpb2250@gmail.com> wrote:
>
> Hi,
>
> When reading the docs for the publication parameter
> 'publish_via_partition_root' [1], I felt there was too much mental
> gymnastics required to understand the meaning of "the latter is the
> default."
>
> Why not just say clearly what the default value is?
>
> PSA: a patch to do that.

Here is the patch accidentally omitted from the last post.

>
> ======
> [1]
https://www.postgresql.org/docs/current/sql-createpublication.html#SQL-CREATEPUBLICATION-PARAMS-WITH-PUBLISH-VIA-PARTITION-ROOT
>
> Kind Regards,
> Peter Smith.
> Fujitsu Australia

On Thu, Dec 11, 2025 at 12:22 PM Peter Smith <smithpb2250@gmail.com> wrote:
> > Why not just say clearly what the default value is?
> >
> > PSA: a patch to do that.

LGTM. (In fact I've read that paragraph three times and still cannot
get it to stick in my head, despite having done a fair amount of
thinking about publish_via_partition_root, so if you have further
improvement ideas I'm all ears.)

--Jacob

> On Dec 12, 2025, at 07:12, Jacob Champion <jacob.champion@enterprisedb.com> wrote:
>
> On Thu, Dec 11, 2025 at 12:22 PM Peter Smith <smithpb2250@gmail.com> wrote:
>>> Why not just say clearly what the default value is?
>>>
>>> PSA: a patch to do that.
>
> LGTM. (In fact I've read that paragraph three times and still cannot
> get it to stick in my head, despite having done a fair amount of
> thinking about publish_via_partition_root, so if you have further
> improvement ideas I'm all ears.)
>
> --Jacob
>
>

My feeling is that the preceding long sentence has described both sides expect explicitly mentioning true and false,
whichmakes the following sentence, no matter the original version and the patched version sounds slightly redundant. So
Ithink maybe we can rework the entire paragraph like: 

```
This parameter controls how changes to a partitioned table (or any of its partitions) are published. When set to true,
changesare published using the identity and schema of the partitioned table. When set to false (the default), changes
arepublished using the identity and schema of the individual partitions 
where the changes actually occurred. Enabling this option allows the changes to be replicated into a non-partitioned
tableor into a partitioned table whose 
partition structure differs from that of the publisher.
```

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

On Fri, Dec 12, 2025 at 12:32 PM Chao Li <li.evan.chao@gmail.com> wrote:
>
>
>
> > On Dec 12, 2025, at 07:12, Jacob Champion <jacob.champion@enterprisedb.com> wrote:
> >
> > On Thu, Dec 11, 2025 at 12:22 PM Peter Smith <smithpb2250@gmail.com> wrote:
> >>> Why not just say clearly what the default value is?
> >>>
> >>> PSA: a patch to do that.
> >
> > LGTM. (In fact I've read that paragraph three times and still cannot
> > get it to stick in my head, despite having done a fair amount of
> > thinking about publish_via_partition_root, so if you have further
> > improvement ideas I'm all ears.)
> >

Yeah, I proposed only a very small patch instead of a rewrite only
because I thought it would have a better chance of acceptance, not
because I had any love for the rest of that paragraph.

>
> My feeling is that the preceding long sentence has described both sides expect explicitly mentioning true and false,
whichmakes the following sentence, no matter the original version and the patched version sounds slightly redundant. So
Ithink maybe we can rework the entire paragraph like: 
>
> ```
> This parameter controls how changes to a partitioned table (or any of its partitions) are published. When set to
true,changes are published using the identity and schema of the partitioned table. When set to false (the default),
changesare published using the identity and schema of the individual partitions 
> where the changes actually occurred. Enabling this option allows the changes to be replicated into a non-partitioned
tableor into a partitioned table whose 
> partition structure differs from that of the publisher.
> ```
>

AFAIK, Chao's improved text is mostly good, except I think there might
be some nuances when there are multiple levels of partitioning.

For example, maybe you need to make this change?
BEFORE
When set to true, changes are published using the identity and schema
of the partitioned table
AFTER
When set to true, changes are published using the identity and schema
of the root partitioned table
~~~

Experiment:

CREATE TABLE t1(a int) PARTITION BY RANGE(a);
|
+-- CREATE TABLE t1_p1 PARTITION OF t1 FOR VALUES FROM (0) TO (5)
PARTITION BY RANGE(a);
|   |
|   + CREATE TABLE t1_p1_p1 PARTITION OF t1_p1 FOR VALUES FROM (0) TO (3);
| + CREATE TABLE t1_p1_p2 PARTITION OF t1_p1 FOR VALUES FROM (3) TO (5);
|
+-- CREATE TABLE t1_p2 PARTITION OF t1 FOR VALUES FROM (5) TO (10);


CREATE PUBLICATION pub1 FOR ALL TABLES WITH (publish_via_partition_root = true);


Subscriber:
CREATE SUBSCRIPTION sub1 CONNECTION 'dbname=test_pub' PUBLICATION pub1;
test_sub=# CREATE TABLE t1(a  int);
test_sub=# CREATE TABLE t1_p1(a  int);
test_sub=# CREATE TABLE t1_p2(a  int);
test_sub=# CREATE TABLE t1_p1_p1(a  int);
test_sub=# CREATE TABLE t1_p1_p2(a  int);

Publisher:
Here we are inserting into a sub-partitioned table.

INSERT INTO t1_p1 VALUES (2);

Result (subscriber)
test_sub=#
test_sub=# select * from t1;
 a
---
 2
(1 row)

test_sub=# select * from t1_p1;
 a
---
(0 rows)

Notice the data writes using the *root* partitioned table. Not just
the nearest partitioned table.

======
Kind Regards,
Peter Smith.
Fujitsu Australia

> On Dec 15, 2025, at 08:25, Peter Smith <smithpb2250@gmail.com> wrote:
>
> On Fri, Dec 12, 2025 at 12:32 PM Chao Li <li.evan.chao@gmail.com> wrote:
>>
>>
>>
>>> On Dec 12, 2025, at 07:12, Jacob Champion <jacob.champion@enterprisedb.com> wrote:
>>>
>>> On Thu, Dec 11, 2025 at 12:22 PM Peter Smith <smithpb2250@gmail.com> wrote:
>>>>> Why not just say clearly what the default value is?
>>>>>
>>>>> PSA: a patch to do that.
>>>
>>> LGTM. (In fact I've read that paragraph three times and still cannot
>>> get it to stick in my head, despite having done a fair amount of
>>> thinking about publish_via_partition_root, so if you have further
>>> improvement ideas I'm all ears.)
>>>
>
> Yeah, I proposed only a very small patch instead of a rewrite only
> because I thought it would have a better chance of acceptance, not
> because I had any love for the rest of that paragraph.
>
>>
>> My feeling is that the preceding long sentence has described both sides expect explicitly mentioning true and false,
whichmakes the following sentence, no matter the original version and the patched version sounds slightly redundant. So
Ithink maybe we can rework the entire paragraph like: 
>>
>> ```
>> This parameter controls how changes to a partitioned table (or any of its partitions) are published. When set to
true,changes are published using the identity and schema of the partitioned table. When set to false (the default),
changesare published using the identity and schema of the individual partitions 
>> where the changes actually occurred. Enabling this option allows the changes to be replicated into a non-partitioned
tableor into a partitioned table whose 
>> partition structure differs from that of the publisher.
>> ```
>>
>
> AFAIK, Chao's improved text is mostly good, except I think there might
> be some nuances when there are multiple levels of partitioning.
>
> For example, maybe you need to make this change?
> BEFORE
> When set to true, changes are published using the identity and schema
> of the partitioned table
> AFTER
> When set to true, changes are published using the identity and schema
> of the root partitioned table
> ~~~

Agreed to add “root”.

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

On Tue, Dec 16, 2025 at 7:39 PM Chao Li <li.evan.chao@gmail.com> wrote:
>
>
>
> > On Dec 15, 2025, at 08:25, Peter Smith <smithpb2250@gmail.com> wrote:
> >
> > On Fri, Dec 12, 2025 at 12:32 PM Chao Li <li.evan.chao@gmail.com> wrote:
> >>
> >>
> >>
> >>> On Dec 12, 2025, at 07:12, Jacob Champion <jacob.champion@enterprisedb.com> wrote:
> >>>
> >>> On Thu, Dec 11, 2025 at 12:22 PM Peter Smith <smithpb2250@gmail.com> wrote:
> >>>>> Why not just say clearly what the default value is?
> >>>>>
> >>>>> PSA: a patch to do that.
> >>>
> >>> LGTM. (In fact I've read that paragraph three times and still cannot
> >>> get it to stick in my head, despite having done a fair amount of
> >>> thinking about publish_via_partition_root, so if you have further
> >>> improvement ideas I'm all ears.)
> >>>
> >
> > Yeah, I proposed only a very small patch instead of a rewrite only
> > because I thought it would have a better chance of acceptance, not
> > because I had any love for the rest of that paragraph.
> >
> >>
> >> My feeling is that the preceding long sentence has described both sides expect explicitly mentioning true and
false,which makes the following sentence, no matter the original version and the patched version sounds slightly
redundant.So I think maybe we can rework the entire paragraph like: 
> >>
> >> ```
> >> This parameter controls how changes to a partitioned table (or any of its partitions) are published. When set to
true,changes are published using the identity and schema of the partitioned table. When set to false (the default),
changesare published using the identity and schema of the individual partitions 
> >> where the changes actually occurred. Enabling this option allows the changes to be replicated into a
non-partitionedtable or into a partitioned table whose 
> >> partition structure differs from that of the publisher.
> >> ```
> >>
> >
> > AFAIK, Chao's improved text is mostly good, except I think there might
> > be some nuances when there are multiple levels of partitioning.
> >
> > For example, maybe you need to make this change?
> > BEFORE
> > When set to true, changes are published using the identity and schema
> > of the partitioned table
> > AFTER
> > When set to true, changes are published using the identity and schema
> > of the root partitioned table
> > ~~~
>
> Agreed to add “root”.
>

PSA v2 done that way.

======
Kind Regards,
Peter Smith.
Fujitsu Australia.

On Wed, Dec 17, 2025 at 2:29 AM Peter Smith <smithpb2250@gmail.com> wrote:
>
> On Tue, Dec 16, 2025 at 7:39 PM Chao Li <li.evan.chao@gmail.com> wrote:
> >
> > >
> > > AFAIK, Chao's improved text is mostly good, except I think there might
> > > be some nuances when there are multiple levels of partitioning.
> > >
> > > For example, maybe you need to make this change?
> > > BEFORE
> > > When set to true, changes are published using the identity and schema
> > > of the partitioned table
> > > AFTER
> > > When set to true, changes are published using the identity and schema
> > > of the root partitioned table
> > > ~~~
> >
> > Agreed to add “root”.
> >
>
> PSA v2 done that way.
>

LGTM. As this is not any bug fix rather a text improvement, so it is
good to fix this in HEAD only.

--
With Regards,
Amit Kapila.

On Wed, Dec 17, 2025 at 4:04 AM Amit Kapila <amit.kapila16@gmail.com> wrote:
> LGTM. As this is not any bug fix rather a text improvement, so it is
> good to fix this in HEAD only.

Don't we typically backpatch documentation improvements? Otherwise no
one gets the better docs for a year.

--Jacob

On Wed, Dec 17, 2025 at 4:04 AM Amit Kapila <amit.kapila16@gmail.com> wrote:
> LGTM. As this is not any bug fix rather a text improvement, so it is
> good to fix this in HEAD only.

Don't we typically backpatch documentation improvements? Otherwise no
one gets the better docs for a year.

On Thu, Dec 18, 2025 at 1:42 AM Jacob Champion
<jacob.champion@enterprisedb.com> wrote:
>
> On Wed, Dec 17, 2025 at 4:04 AM Amit Kapila <amit.kapila16@gmail.com> wrote:
> > LGTM. As this is not any bug fix rather a text improvement, so it is
> > good to fix this in HEAD only.
>
> Don't we typically backpatch documentation improvements? Otherwise no
> one gets the better docs for a year.
>

It depends if there is a wrong explanation then it makes sense to
backpatch but as this is a wording improvement, it should be okay to
commit it as HEAD-only patch. Would you like to take care of this?

--
With Regards,
Amit Kapila.

On Wed, Dec 17, 2025 at 1:08 PM David G. Johnston
<david.g.johnston@gmail.com> wrote:
> Presently it’s the same criteria as for the code - things deemed bug fixes get back-patched; pure enhancements do
not.

Well, okay. Bear with me a moment because I need to calibrate to the
community norms.

Is the consensus that this is not a "bug fix"? Because I know what the
feature does, but I cannot understand the current paragraph without
rereading it several times.

On Wed, Dec 17, 2025 at 8:18 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
> It depends if there is a wrong explanation then it makes sense to
> backpatch but as this is a wording improvement, it should be okay to
> commit it as HEAD-only patch.

I know it's okay, but I *want* to backpatch, and I would have
yesterday except for your email. Does that raise concerns or cause
problems in practice? (Should I drop this as not a battle really worth
having? Clearly nothing is exploding; I just don't get why docs
contributors have to wait ten months for improvements to land if
everyone says "oh yeah, that's better.")

> Would you like to take care of this?

Yes.

Thanks,
--Jacob

On Fri, Dec 19, 2025 at 5:11 AM Jacob Champion
<jacob.champion@enterprisedb.com> wrote:
>
> On Wed, Dec 17, 2025 at 1:08 PM David G. Johnston
> <david.g.johnston@gmail.com> wrote:
> > Presently it’s the same criteria as for the code - things deemed bug fixes get back-patched; pure enhancements do
not.
>
> Well, okay. Bear with me a moment because I need to calibrate to the
> community norms.
>
> Is the consensus that this is not a "bug fix"? Because I know what the
> feature does, but I cannot understand the current paragraph without
> rereading it several times.
>

As OP, do I get a vote?

FWIW, I think that the purpose of documentation is surely to convey
information *clearly* to users.
And, the original text fails the clarity test because it was simply
too hard to understand what it was trying to say without reading it
multiple times.
And, things that fail tests are called "bugs".

======
Kind Regards,
Peter Smith.
Fujitsu Australia

On Thu, Dec 18, 2025 at 11:41 PM Jacob Champion
<jacob.champion@enterprisedb.com> wrote:
>
> On Wed, Dec 17, 2025 at 1:08 PM David G. Johnston
> <david.g.johnston@gmail.com> wrote:
> > Presently it’s the same criteria as for the code - things deemed bug fixes get back-patched; pure enhancements do
not.
>
> Well, okay. Bear with me a moment because I need to calibrate to the
> community norms.
>
> Is the consensus that this is not a "bug fix"? Because I know what the
> feature does, but I cannot understand the current paragraph without
> rereading it several times.
>
> On Wed, Dec 17, 2025 at 8:18 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
> > It depends if there is a wrong explanation then it makes sense to
> > backpatch but as this is a wording improvement, it should be okay to
> > commit it as HEAD-only patch.
>
> I know it's okay, but I *want* to backpatch, and I would have
> yesterday except for your email. Does that raise concerns or cause
> problems in practice?
>

As far as I understand it shouldn't break community norms either way.
Also, as per my knowledge there is no clear guidance for such patches.
It would be good if other committer also shares their view so we can
also learn and take same action in future. This feature is present
since PostgreSQL-13 and no real user has reported this problem. It is
possible that people using this feature are already use to it using
this feature that it doesn't matter much to them either way. Unless
someone else responds, I think you can do what you see good to deal
with this case.

--
With Regards,
Amit Kapila.

On Fri, Dec 19, 2025 at 09:31:36AM +0530, Amit Kapila wrote:
> On Thu, Dec 18, 2025 at 11:41 PM Jacob Champion
> <jacob.champion@enterprisedb.com> wrote:
> > I know it's okay, but I *want* to backpatch, and I would have
> > yesterday except for your email. Does that raise concerns or cause
> > problems in practice?
> 
> As far as I understand it shouldn't break community norms either way.
> Also, as per my knowledge there is no clear guidance for such patches.
> It would be good if other committer also shares their view so we can
> also learn and take same action in future. This feature is present
> since PostgreSQL-13 and no real user has reported this problem. It is
> possible that people using this feature are already use to it using
> this feature that it doesn't matter much to them either way. Unless
> someone else responds, I think you can do what you see good to deal
> with this case.

If it is just a wording improvement, I usually do master only.  If it is
inaccurate/unclear/not-understandable, I would backpatch to all
releases.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Do not let urgent matters crowd out time for investment in the future.

On Thu, Dec 25, 2025 at 1:28 AM Bruce Momjian <bruce@momjian.us> wrote:
>
> On Fri, Dec 19, 2025 at 09:31:36AM +0530, Amit Kapila wrote:
> > On Thu, Dec 18, 2025 at 11:41 PM Jacob Champion
> > <jacob.champion@enterprisedb.com> wrote:
> > > I know it's okay, but I *want* to backpatch, and I would have
> > > yesterday except for your email. Does that raise concerns or cause
> > > problems in practice?
> >
> > As far as I understand it shouldn't break community norms either way.
> > Also, as per my knowledge there is no clear guidance for such patches.
> > It would be good if other committer also shares their view so we can
> > also learn and take same action in future. This feature is present
> > since PostgreSQL-13 and no real user has reported this problem. It is
> > possible that people using this feature are already use to it using
> > this feature that it doesn't matter much to them either way. Unless
> > someone else responds, I think you can do what you see good to deal
> > with this case.
>
> If it is just a wording improvement, I usually do master only.  If it is
> inaccurate/unclear/not-understandable, I would backpatch to all
> releases.
>

IIUC, multiple people in this thread felt that it is a wording
improvement because current text is unclear. So, if we have to follow
what you do, it should be backpatched.

Jacob, would you like to take care of this still?

--
With Regards,
Amit Kapila.

On Mon, Jan 5, 2026 at 4:18 AM Amit Kapila <amit.kapila16@gmail.com> wrote:
> IIUC, multiple people in this thread felt that it is a wording
> improvement because current text is unclear. So, if we have to follow
> what you do, it should be backpatched.
>
> Jacob, would you like to take care of this still?

Yep, I'll backpatch this week. Getting back up to speed after the holidays...

Thanks,
--Jacob