BUG #17824: PQTRANS_ACTIVE misleading

The following bug has been logged on the website:

Bug reference:      17824
Logged by:          Andy Schoenberger
Email address:      akschoenberger@gmail.com
PostgreSQL version: 15.2
Operating system:   All
Description:

The documentation for PQTRANS_ACTIVE [1] does not make explicitly clear that
it is returned in *all* cases where there is a command in progress on an
okay connection, and not just in the case that there is a command in
progress inside of a transaction [2]. With a name like PQTRANS_ACTIVE, I
believe it is worth making clear that it can happen when a transaction is
not active. I believe this has led to multiple bugs in other programs that
attempt to display the current status of a transaction, including a possible
one in psql [3].

Assuming I am understanding everything correctly, I think the documentation
should probably be updated to make clear that PQTRANS_ACTIVE does not mean
that a transaction is active.

Best,
Andy


[1]
From:
https://www.postgresql.org/docs/15/libpq-status.html#LIBPQ-PQTRANSACTIONSTATUS

> Returns the current in-transaction status of the server.

> The status can be PQTRANS_IDLE (currently idle), PQTRANS_ACTIVE (a command
is in progress), PQTRANS_INTRANS (idle, in a valid transaction block), or
PQTRANS_INERROR (idle, in a failed transaction block). PQTRANS_UNKNOWN is
reported if the connection is bad. PQTRANS_ACTIVE is reported only when a
query has been sent to the server and not yet completed.

[2]

https://github.com/postgres/postgres/blob/d69cd3a2e29c68a3fdfd4e97167f9a7c6ad29e80/src/interfaces/libpq/fe-connect.c#L6729

[3]
The psql documentation below shows that a `*` character is present when a
transaction is active:

From:
https://www.postgresql.org/docs/current/app-psql.html#APP-PSQL-PROMPTING

> Transaction status: an empty string when not in a transaction block, or *
when in a transaction block, or ! when in a failed transaction block, or ?
when the transaction state is indeterminate (for example, because there is
no connection).

…but a `*` character is also technically used if the transaction status is
PQTRANS_ACTIVE, which does not necessarily happen during a transaction.
https://github.com/postgres/postgres/blob/46d490ac19a7ca93a5c0f47e5a0e759b5385a8ae/src/bin/psql/prompt.c#L236

I’m not sure if this is actually considered a bug or not since I don’t think
psql displays a new prompt until after the command completes, but the logic
in the code being misleading does not help.