Horton

Thread

Commits

Same data as JSON: GET /api/v1/messages/:b64id/commits the thread's linked commits as JSON, with link sources. API reference →

  1. doc: Improve description of publish_via_partition_root

  1. DOCS - Clarify the publication 'publish_via_partition_root' default value.

    Peter Smith <smithpb2250@gmail.com> — 2025-12-11T07:51:47Z

    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

  2. Re: DOCS - Clarify the publication 'publish_via_partition_root' default value.

    Peter Smith <smithpb2250@gmail.com> — 2025-12-11T20:22:07Z

    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

  3. Re: DOCS - Clarify the publication 'publish_via_partition_root' default value.

    Jacob Champion <jacob.champion@enterprisedb.com> — 2025-12-11T23:12:52Z

    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

  4. Re: DOCS - Clarify the publication 'publish_via_partition_root' default value.

    Chao Li <li.evan.chao@gmail.com> — 2025-12-12T01:31:19Z

    
> 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, 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), changes are 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 table or 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/

  5. Re: DOCS - Clarify the publication 'publish_via_partition_root' default value.

    Peter Smith <smithpb2250@gmail.com> — 2025-12-15T00:25:55Z

    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), changes are 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 table 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
~~~

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

  6. Re: DOCS - Clarify the publication 'publish_via_partition_root' default value.

    Chao Li <li.evan.chao@gmail.com> — 2025-12-16T08:39:10Z

    
> 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), changes are 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 table 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”.

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

  7. Re: DOCS - Clarify the publication 'publish_via_partition_root' default value.

    Peter Smith <smithpb2250@gmail.com> — 2025-12-16T20:58:50Z

    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), changes are 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 table 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.

  8. Re: DOCS - Clarify the publication 'publish_via_partition_root' default value.

    Amit Kapila <amit.kapila16@gmail.com> — 2025-12-17T12:04:15Z

    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.

  9. Re: DOCS - Clarify the publication 'publish_via_partition_root' default value.

    Jacob Champion <jacob.champion@enterprisedb.com> — 2025-12-17T20:12:19Z

    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

  10. Re: DOCS - Clarify the publication 'publish_via_partition_root' default value.

    David G. Johnston <david.g.johnston@gmail.com> — 2025-12-17T21:08:53Z

    On Wednesday, December 17, 2025, 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.
>

Presently it’s the same criteria as for the code - things deemed bug fixes
get back-patched; pure enhancements do not.

I doubt we’d want to push them back beyond the latest stable release but
there is definitely an argument for new efforts to be dropped into there
and not just master.

David J.

  11. Re: DOCS - Clarify the publication 'publish_via_partition_root' default value.

    Amit Kapila <amit.kapila16@gmail.com> — 2025-12-18T04:18:01Z

    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.

  12. Re: DOCS - Clarify the publication 'publish_via_partition_root' default value.

    Jacob Champion <jacob.champion@enterprisedb.com> — 2025-12-18T18:10:52Z

    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

  13. Re: DOCS - Clarify the publication 'publish_via_partition_root' default value.

    Peter Smith <smithpb2250@gmail.com> — 2025-12-18T23:21:55Z

    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

  14. Re: DOCS - Clarify the publication 'publish_via_partition_root' default value.

    Amit Kapila <amit.kapila16@gmail.com> — 2025-12-19T04:01:36Z

    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.

  15. Re: DOCS - Clarify the publication 'publish_via_partition_root' default value.

    Bruce Momjian <bruce@momjian.us> — 2025-12-24T19:58:20Z

    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.