Horton

Thread

Commits

  1. Doc: Make logical replication examples executable in bulk.

  1. doc: Make logical replication examples executable in bulk and legal sgml.

    David G. Johnston <david.g.johnston@gmail.com> — 2025-05-03T16:02:36Z

    While responding to a "our documentation is buggy" complaint I got annoyed
in my attempt to reproduce the behavior by having to surgically copy
line-by-line the DDL and DML code involved.  Let's strive for a more
copy-paste friendly example setup.  No prompts and no interspersed command
tags (they are ok if the script is one block and the output is another).

In passing, the examples use < 5 and >= 5 in expressions - which in theory
are supposed to require the use of &lt; and &gt; entities...or enclosure in
a CDATA construct.  The latter seems preferable.

David J.

  2. Re: doc: Make logical replication examples executable in bulk and legal sgml.

    Peter Smith <smithpb2250@gmail.com> — 2025-05-16T01:28:28Z

    On Sun, May 4, 2025 at 2:03 AM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> While responding to a "our documentation is buggy" complaint I got annoyed in my attempt to reproduce the behavior by having to surgically copy line-by-line the DDL and DML code involved.  Let's strive for a more copy-paste friendly example setup.  No prompts and no interspersed command tags (they are ok if the script is one block and the output is another).
>

Hi David,

I think I was the author of most of these examples, so I feel obliged
to post my 2c.

For the logical replication examples it is really important to be
aware if the psql is executing at the publisher or subscriber side;
that is the main reason why I had kept prompts in the examples (e.g.
it avoided having to say "On the publisher:" or "On the subscriber:"
for every example).

OTOH, I understand your issue that those prompts made it difficult to
simply cut/paste slabs of psql directly from the examples -- I've
heard this complaint a few times before from other people.

So, your patch which still keeps my prompts albeit as "comments", but
that now allows the execution of the bulk copy/paste, seems like a
reasonable compromise to me.

~~

BTW, I can understand the commented prompt for the bulk fragments like:
/* sub # */ CREATE SUBSCRIPTION sub1
/* sub - */ CONNECTION 'host=localhost dbname=test_pub application_name=sub1'
/* sub - */ PUBLICATION pub1;
/* sub # */ CREATE SUBSCRIPTION sub2
/* sub - */ CONNECTION 'host=localhost dbname=test_pub application_name=sub2'
/* sub - */ PUBLICATION pub2;
/* sub # */ CREATE SUBSCRIPTION sub3
/* sub - */ CONNECTION 'host=localhost dbname=test_pub application_name=sub3'
/* sub - */ PUBLICATION pub3a, pub3b;

~

But, for the SELECT statements, commenting the prompt like:
/* sub # */ SELECT * FROM t1;
 a |   b
---+-------
 1 | one
 2 | two
 3 | three
(3 rows)

doesn't help bulk execution at all because the result gets in the way
so you'll still end up surgically copying each SELECT. Since it fixes
nothing I assumed you just commented the SELECT prompts for
consistency with the other ones, right?

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

  3. Re: doc: Make logical replication examples executable in bulk and legal sgml.

    David G. Johnston <david.g.johnston@gmail.com> — 2025-05-16T01:40:55Z

    On Thu, May 15, 2025, 19:28 Peter Smith <smithpb2250@gmail.com> wrote:

>
>
> doesn't help bulk execution at all because the result gets in the way
> so you'll still end up surgically copying each SELECT. Since it fixes
> nothing I assumed you just commented the SELECT prompts for
> consistency with the other ones, right?
>

Only mostly for consistency.  Being able to select entire lines and not
have to precision place the cursor at column 7 to avoid the prompt means
the comment for select has a usability aspect.

David J.

  4. Re: doc: Make logical replication examples executable in bulk and legal sgml.

    Amit Kapila <amit.kapila16@gmail.com> — 2025-05-23T05:19:05Z

    On Sat, May 3, 2025 at 9:33 PM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> While responding to a "our documentation is buggy" complaint I got annoyed in my attempt to reproduce the behavior by having to surgically copy line-by-line the DDL and DML code involved.  Let's strive for a more copy-paste friendly example setup.  No prompts and no interspersed command tags (they are ok if the script is one block and the output is another).
>

That's a valid point. Since this is not a correctness issue, I am less
inclined to backpatch. What do you or others think?

-- 
With Regards,
Amit Kapila.

  5. doc: Make logical replication examples executable in bulk and legal sgml.

    David G. Johnston <david.g.johnston@gmail.com> — 2025-05-23T05:22:51Z

    On Thursday, May 22, 2025, Amit Kapila <amit.kapila16@gmail.com> wrote:

> On Sat, May 3, 2025 at 9:33 PM David G. Johnston
> <david.g.johnston@gmail.com> wrote:
> >
> > While responding to a "our documentation is buggy" complaint I got
> annoyed in my attempt to reproduce the behavior by having to surgically
> copy line-by-line the DDL and DML code involved.  Let's strive for a more
> copy-paste friendly example setup.  No prompts and no interspersed command
> tags (they are ok if the script is one block and the output is another).
> >
>
> That's a valid point. Since this is not a correctness issue, I am less
> inclined to backpatch. What do you or others think?
>

Agreed, this would not be back-patched.

David J.

  6. Re: doc: Make logical replication examples executable in bulk and legal sgml.

    Amit Kapila <amit.kapila16@gmail.com> — 2025-05-27T03:21:01Z

    On Fri, May 23, 2025 at 10:52 AM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> On Thursday, May 22, 2025, Amit Kapila <amit.kapila16@gmail.com> wrote:
>>
>> On Sat, May 3, 2025 at 9:33 PM David G. Johnston
>> <david.g.johnston@gmail.com> wrote:
>> >
>> > While responding to a "our documentation is buggy" complaint I got annoyed in my attempt to reproduce the behavior by having to surgically copy line-by-line the DDL and DML code involved.  Let's strive for a more copy-paste friendly example setup.  No prompts and no interspersed command tags (they are ok if the script is one block and the output is another).
>> >
>>
>> That's a valid point. Since this is not a correctness issue, I am less
>> inclined to backpatch. What do you or others think?
>
>
> Agreed, this would not be back-patched.
>

Yesterday, I pushed the patch. Thanks for working on this.

-- 
With Regards,
Amit Kapila.