doc: should pg_createsubscriber be grouped as a client application?

Dear Peter,

Note that the latter includes pg_basebackup, pg_receivewal, and
pg_recvlogical, which feel generally similar to pg_createsubscriber.

Hmm, but similar command pg_upgrade was included in the server app page.

The page [1]https://www.postgresql.org/docs/devel/reference-server.html defined that server commands are the command can be run on the same
server with the postgres server process. IIRC, the command was categorized as
"Server Application" because it assumed standby is running on the same machine.

But... I think the command is located on the border between the server and the client.
We should hear other opinions too.

[1]: https://www.postgresql.org/docs/devel/reference-server.html

Best regards,
Hayato Kuroda
FUJITSU LIMITED

At Mon, 22 Jun 2026 06:56:45 +0000, "Hayato Kuroda (Fujitsu)" <kuroda.hayato@fujitsu.com> wrote in

Dear Peter,

Note that the latter includes pg_basebackup, pg_receivewal, and
pg_recvlogical, which feel generally similar to pg_createsubscriber.

Hmm, but similar command pg_upgrade was included in the server app page.

The page [1] defined that server commands are the command can be run on the same
server with the postgres server process. IIRC, the command was categorized as
"Server Application" because it assumed standby is running on the same machine.

But... I think the command is located on the border between the server and the client.
We should hear other opinions too.

[1]: https://www.postgresql.org/docs/devel/reference-server.html

I also agree that pg_createsubscriber sits somewhere on the boundary
between server and client applications. If we were to draw a
distinction, one possible interpretation would be that server
applications are tools that access server resources beyond what a
regular client connection normally does. That seems broadly consistent
with the current classification, although pg_basebackup still feels
somewhat borderline under that interpretation.

I also wonder whether the server/client distinction is particularly
important here. A number of utilities seem to fall somewhere between
the two categories, and I'm not sure users pay much attention to that
classification when looking up commands.

Regards,

--
Kyotaro Horiguchi
NTT Open Source Software Center

On 22.06.26 09:46, Kyotaro Horiguchi wrote:

At Mon, 22 Jun 2026 06:56:45 +0000, "Hayato Kuroda (Fujitsu)" <kuroda.hayato@fujitsu.com> wrote in

Dear Peter,

Note that the latter includes pg_basebackup, pg_receivewal, and
pg_recvlogical, which feel generally similar to pg_createsubscriber.

Hmm, but similar command pg_upgrade was included in the server app page.

The page [1] defined that server commands are the command can be run on the same
server with the postgres server process. IIRC, the command was categorized as
"Server Application" because it assumed standby is running on the same machine.

But... I think the command is located on the border between the server and the client.
We should hear other opinions too.

[1]: https://www.postgresql.org/docs/devel/reference-server.html

I also agree that pg_createsubscriber sits somewhere on the boundary
between server and client applications. If we were to draw a
distinction, one possible interpretation would be that server
applications are tools that access server resources beyond what a
regular client connection normally does. That seems broadly consistent
with the current classification, although pg_basebackup still feels
somewhat borderline under that interpretation.

I agree it is borderline (otherwise this discussion would probably be
unnecessary ;-) ), but I also think it should be one the same side of
the grouping as the likes of pg_basebackup.

I also wonder whether the server/client distinction is particularly
important here. A number of utilities seem to fall somewhere between
the two categories, and I'm not sure users pay much attention to that
classification when looking up commands.

Maybe we don't need to have this distinction at all, but as long as we
have it, it would be good to maintain it. Also, as I mentioned in the
previous message, this is indirectly related to packaging. What "bin"
programs would you expect in a postgresql-server and a postgresql-client
package?

On Tue, Jun 23, 2026 at 3:26 PM Peter Eisentraut <peter@eisentraut.org> wrote:

On 22.06.26 09:46, Kyotaro Horiguchi wrote:

At Mon, 22 Jun 2026 06:56:45 +0000, "Hayato Kuroda (Fujitsu)" <kuroda.hayato@fujitsu.com> wrote in

Dear Peter,

Note that the latter includes pg_basebackup, pg_receivewal, and
pg_recvlogical, which feel generally similar to pg_createsubscriber.

Hmm, but similar command pg_upgrade was included in the server app page.

The page [1] defined that server commands are the command can be run on the same
server with the postgres server process. IIRC, the command was categorized as
"Server Application" because it assumed standby is running on the same machine.

But... I think the command is located on the border between the server and the client.
We should hear other opinions too.

[1]: https://www.postgresql.org/docs/devel/reference-server.html

I also agree that pg_createsubscriber sits somewhere on the boundary
between server and client applications. If we were to draw a
distinction, one possible interpretation would be that server
applications are tools that access server resources beyond what a
regular client connection normally does. That seems broadly consistent
with the current classification, although pg_basebackup still feels
somewhat borderline under that interpretation.

I agree it is borderline (otherwise this discussion would probably be
unnecessary ;-) ), but I also think it should be one the same side of
the grouping as the likes of pg_basebackup.

If we go by the definition of Client/Server from the docs at
doc/src/sgml/reference.sgml:
- Client: "The common feature of these applications is that they can
be run on any host, independent of where the database server resides."
- Server: "These commands can only be run usefully on the host where
the database server resides."

So the documented discriminator is locality of the data directory, not
libpq. By that rule pg_createsubscriber is a server application as
it takes -D pgdata of the target, and requires that target (a physical
standby) to run recovery on it. BTW, pg_rewind also takes a remote
--source-server libpq connection to a live server, yet it's a server
app, because it rewrites a local data directory. So I think "makes a
libpq connection" is not the right discriminator; if it were,
pg_rewind would have to move too.

Now, the other client tools like pg_basebackup, pg_receivewal /
pg_recvlogical don't need local data-dir access, so they are correctly
classified as Client tools.

--
With Regards,
Amit Kapila.

On Tue, Jun 23, 2026, at 7:39 AM, Amit Kapila wrote:

If we go by the definition of Client/Server from the docs at
doc/src/sgml/reference.sgml:
- Client: "The common feature of these applications is that they can
be run on any host, independent of where the database server resides."
- Server: "These commands can only be run usefully on the host where
the database server resides."

So the documented discriminator is locality of the data directory, not
libpq. By that rule pg_createsubscriber is a server application as
it takes -D pgdata of the target, and requires that target (a physical
standby) to run recovery on it. BTW, pg_rewind also takes a remote
--source-server libpq connection to a live server, yet it's a server
app, because it rewrites a local data directory. So I think "makes a
libpq connection" is not the right discriminator; if it were,
pg_rewind would have to move too.

That's my interpretation too. BTW we had this discussion during development [1]/messages/by-id/aabc91d2-505b-4412-af08-7dae2df1d437@app.fastmail.com.

[1]: /messages/by-id/aabc91d2-505b-4412-af08-7dae2df1d437@app.fastmail.com

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