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]From: https://www.postgresql.org/docs/15/libpq-status.html#LIBPQ-PQTRANSACTIONSTATUS 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]https://github.com/postgres/postgres/blob/d69cd3a2e29c68a3fdfd4e97167f9a7c6ad29e80/src/interfaces/libpq/fe-connect.c#L6729. 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]The psql documentation below shows that a `*` character is present when a transaction is active:.
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
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
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:
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.
On Wed, Mar 8, 2023 at 8:28 AM PG Bug reporting form <noreply@postgresql.org>
wrote:
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.
It is not possible for the server to execute a command without there being
an active transaction in progress.
…but a `*` character is also technically used if the transaction status is
PQTRANS_ACTIVE, which does not necessarily happen during a transaction.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.
Right, it is difficult to report on/see the implicit transaction that
occurs if you send a command to the server without constructing an explicit
transaction block, since it goes away as the command execution ends.
David J.
PG Bug reporting form <noreply@postgresql.org> writes:
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.
The existing documentation defines it as "a command is in progress",
which seems perfectly clear to me --- adding more words would just
muddy the waters.
Also, if a command is running then the server *does* have a transaction
open -- it might be an auto-started, auto-committed one, but there's
always a transaction. You seem to be using that word in a way that does
not correspond with common Postgres usage. (Note that the definitions for
PQTRANS_INTRANS and PQTRANS_INERROR say "transaction block" not
"transaction", to comport with our usual terminology.)
regards, tom lane