agora inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedFrom: Euler Taveira <euler@eulerto.com>
To: Fujii Masao <masao.fujii@gmail.com>
To: Peter Eisentraut <peter@eisentraut.org>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Make pgoutput documentation easier to find
Date: Thu, 07 Aug 2025 10:35:23 -0300
Message-ID: <2fc50bf9-d6bf-4318-bf3f-72d883f95ce9@app.fastmail.com> (raw)
In-Reply-To: <CAHGQGwH0pU08aEX7ahvmAZih3V5yT4QgMU0VuJyRYqvarFn0GQ@mail.gmail.com>
References: <CAHGQGwFJTbygdhhjR_iP4Oem=Lo1xsptWWOq825uoW+hG_Lfnw@mail.gmail.com>
<900b7421-1f32-47c7-9ad2-4144dfd7b679@eisentraut.org>
<CAHGQGwH0pU08aEX7ahvmAZih3V5yT4QgMU0VuJyRYqvarFn0GQ@mail.gmail.com>
On Wed, Aug 6, 2025, at 10:48 AM, Fujii Masao wrote:
> On Wed, Aug 6, 2025 at 8:36 PM Peter Eisentraut <peter@eisentraut.org> wrote:
>>
>> On 03.08.25 03:32, Fujii Masao wrote:
>> > The current documentation for pgoutput is buried in the logical streaming
>> > replication protocol section (in protocol.sgml), and there's no index entry
>> > for it. This makes it hard to discover and access, for example, when trying
>> > to look up the options it supports.
>> >
>> > I've often struggled to locate this information myself, so I'd like to
>> > propose moving the pgoutput documentation to the logical decoding section
>> > and adding an index entry. The attached patch does that. I think this change
>> > will make it much easier for users to find the relevant details.
>>
>> This would move the documentation of pgoutput from "Internals" to
>> "Server Programming". So it's a question of whether this is something
>> we want to advertise that people can use directly. In the past,
>> pgoutput was an implementation detail of logical replication. But I
>> gather people are using it for other things now?
>
> I've heard that Debezium users, a tool for change data capture, can use
> pgoutput as the logical decoding plugin. I also know users, including
> some of my colleagues, who use pgoutput with pg_recvlogical to capture
> messages inserted via pg_logical_emit_message().
>
pgoutput is our defacto output plugin and I think we consider it a mature piece
of code. If you are worried about compatibility, version 18 added the
pg_get_loaded_modules() function to find the loadable module version -- see
commit 55527368bd07.
There might be cases where you need to debug logical replication (conflicts?)
and you need to pass the exact output plugin options via SQL
(pg_logical_slot_*_changes) to obtain the changes.
If we keep it in the "Internals" chapter, it seems it is something to
PostgreSQL developers (as the chapter description says); it is not. Advanced
users can make good use of this. The new links will help users to find the
moved information if you are searching it into the "Internals" section.
Since you are proposing this change, I'm wondering if we shouldn't move
"Writing Logical Decoding Output Plugins" to "Internals" chapter. It contains
information to PostgreSQL developers. It is a bit off-topic for this thread but
we can also move part of the "Background Worker Processes", part of the
"Archive Modules" and part of the "OAuth Validator Modules" section (2
subsections that describe the API) into "Internals" chapter.
--
Euler Taveira
EDB https://www.enterprisedb.com/
view thread (13+ messages) latest in thread
Message-ID: <2fc50bf9-d6bf-4318-bf3f-72d883f95ce9@app.fastmail.com>
Permalink: ../2fc50bf9-d6bf-4318-bf3f-72d883f95ce9@app.fastmail.com/
Also on: postgresql.org/message-id/2fc50bf9-d6bf-4318-bf3f-72d883f95ce9@app.fastmail.com
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: euler@eulerto.com, masao.fujii@gmail.com, peter@eisentraut.org, pgsql-docs@lists.postgresql.org
Subject: Re: Make pgoutput documentation easier to find
In-Reply-To: <2fc50bf9-d6bf-4318-bf3f-72d883f95ce9@app.fastmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox