Documented lock_timeout in client.mdx

[bitifet]

Added 'lock_timeout' option in Config object documentation since it's explicitly declared in node-postgres (packages/pg/lib/connection-parameters.js)

I also checked it works as documented in PostgreSQL Docs:

https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-LOCK-TIMEOUT

[brianc]

Thank you!

[bitifet]

Don't mention it.

By the way I also took a few notes while experimenting with timeouts and their interaction with connection failures (simulated trough firewall techniques) that, from my perspective, include some details that could be worth to mention in node-postgres documentation.

As is, they contain even text from official PostgreSQL documentation (that is pointless to duplicate here) but there are some application development nuances that, at least for me, would have been so useful If I had found them there at first instance.

If you agree, I could try to incorporate that knowledge into the current documentation in a way that does not excessively bloat it.

Just in case you're curious I paste below those notes (translated by ChatGPT since they weren't originally in english, but after a small glance they don't look so bad):

Timeouts

connectionTimeoutMillis

Error Message: Error: timeout expired

Timeout on acquiring the connection via client.connect().

Once the connection is established, it is not recomputed: If the connection is lost (without closing), it is still considered open and an error will only be triggered if other timeouts occur on the client side. If connectivity is restored without any other timeouts occurring, the connection is transparently recovered, and ongoing operations are completed.

query_timeout

Error Message: Error: Query read timeout

Timeout when launching a query (from the client side) by the node-postgres library.

If the query is not completed (or an error occurs) after this time, this timeout will be triggered (if set).

statement_timeout

Error Message: canceling statement due to statement timeout

Timeout on the execution of an SQL statement by PostgreSQL.

⚠️ WARNING: It can occur on both the client and server sides since part of the work can be executed on the client once the necessary information is transferred to it.

This means that if we lose the connection with the server and it happens on the server side, the error will not be generated until we restore the connection (or a query_timeout occurs), whereas if it happens when the query is being completed on the client, even if the connection is lost, this timeout may occur (or even the query may complete successfully without a connection).

📖 Official Postgres Documentation

idle_in_transaction_session_timeout

Error Message: error: terminating connection due to idle-in-transaction timeout

Occurs when we open a transaction and spend too much time without executing more queries within it.

Useful in case a process that initiated a transaction could get blocked (or delayed too much) due to external circumstances.

📖 Official Postgres Documentation

lock_timeout

Error Message: error: canceling statement due to lock timeout

Occurs when a query is waiting due to an external lock for too long.

NOT IN NODE_PG

idle_session_timeout (integer)

Terminate any session that has been idle (that is, waiting for a client query), but not within an open transaction, for longer than the specified amount of time. If this value is specified without units, it is taken as milliseconds. A value of zero (the default) disables the timeout.

Unlike the case with an open transaction, an idle session without a transaction imposes no large costs on the server, so there is less need to enable this timeout than idle_in_transaction_session_timeout.

Be wary of enforcing this timeout on connections made through connection-pooling software or other middleware, as such a layer may not react well to unexpected connection closure. It may be helpful to enable this timeout only for interactive sessions, perhaps by applying it only to particular users.