Feedback-ID: i0c21471d:Fastmail
MIME-Version: 1.0
Date: Thu, 07 Aug 2025 10:35:23 -0300
From: "Euler Taveira" <euler@eulerto.com>
To: "Fujii Masao" <masao.fujii@gmail.com>,
 "Peter Eisentraut" <peter@eisentraut.org>
Cc: pgsql-docs@lists.postgresql.org
Message-Id: <2fc50bf9-d6bf-4318-bf3f-72d883f95ce9@app.fastmail.com>
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>
Subject: Re: Make pgoutput documentation easier to find
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Archived-At: 
 <https://www.postgresql.org/message-id/2fc50bf9-d6bf-4318-bf3f-72d883f95ce9%40app.fastmail.com>
Precedence: bulk

On Wed, Aug 6, 2025, at 10:48 AM, Fujii Masao wrote:
> On Wed, Aug 6, 2025 at 8:36=E2=80=AFPM Peter Eisentraut <peter@eisentr=
aut.org> wrote:
>>
>> On 03.08.25 03:32, Fujii Masao wrote:
>> > The current documentation for pgoutput is buried in the logical str=
eaming
>> > replication protocol section (in protocol.sgml), and there's no ind=
ex entry
>> > for it. This makes it hard to discover and access, for example, whe=
n 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 s=
ection
>> > and adding an index entry. The attached patch does that. I think th=
is 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 matur=
e 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 (confli=
cts?)
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. Adva=
nced
users can make good use of this. The new links will help users to find t=
he
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 con=
tains
information to PostgreSQL developers. It is a bit off-topic for this thr=
ead 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.


--=20
Euler Taveira
EDB   https://www.enterprisedb.com/