From: vlsi (@vlsi) <noreply+vlsi@github.com>
To: pgjdbc/pgjdbc <noreply+pgjdbc-pgjdbc@github.com>
Subject: Re: [pgjdbc/pgjdbc] PR #3964: feat: add tcpKeepAliveCount, tcpKeepAliveIdle and tcpKeepAliveInterval connection properties
Date: Wed, 09 Sep 2026 20:20:22 +0000
Message-ID: <gh-pgjdbc-pgjdbc-3964-rc3972654722@github.com> (raw)
In-Reply-To: <gh-pgjdbc-pgjdbc-3964@github.com>
References: <gh-pgjdbc-pgjdbc-3964@github.com>
(on pgjdbc/src/main/java/org/postgresql/core/v3/ConnectionFactoryImpl.java)
**Blocker, and a contract question.** Three problems in this block.
1. The options are applied regardless of `tcpKeepAlive`, whose default is `false` — so the default configuration is the one where all three are written to the socket and change nothing. libpq does the opposite: `fe-connect.c` applies `setKeepalivesIdle/Interval/Count` only inside the `usekeepalives != 0` branch, and documents it: *"This parameter is ignored for connections made via a Unix-domain socket, or if keepalives are disabled. It is only supported on systems where `TCP_KEEPCNT` or an equivalent socket option is available; on other systems, it has no effect."*
2. On JDK 8 the setter throws a bare `UnsupportedOperationException`, and `openConnectionImpl` catches only `ConnectException`/`IOException`/`SQLException`, so `Driver.connect`'s catch-all turns it into SQLState `99999`. Measured against a live server with the jar built from this branch:
```
FAILED with org.postgresql.util.PSQLException: Something unusual has occurred to cause the driver to fail. Please report this exception.
caused by java.lang.UnsupportedOperationException: Tuning TCP_KEEPCOUNT is only supported from JDK 11 onwards
at org.postgresql.core.ExtendedSocketOptionAccessorImpl.setTcpKeepCount(ExtendedSocketOptionAccessorImpl.java:29)
at org.postgresql.core.v3.ConnectionFactoryImpl.tryConnect(ConnectionFactoryImpl.java:239)
```
We ask the user to file a bug report for a limitation we documented ourselves.
3. Out-of-range values go the other way — `setOption` rejects them with a `SocketException`, which is an `IOException`, so the driver reports a network failure *and* marks the host dead in the static `GlobalHostStatusTracker.hostStatusMap`, for every other connection in the JVM until `hostRecheckSeconds` elapses:
```
tcpKeepAliveCount=-1 -> PSQLException [The connection attempt failed.] root=java.net.SocketException: Invalid argument
tcpKeepAliveIdle=2147483647 -> PSQLException [The connection attempt failed.] root=java.net.SocketException: Invalid argument
tcpKeepAliveCount=0 -> CONNECTED (silently ignored, socket keeps the default)
```
`tcpKeepAliveCount=abc` is already handled well, by `PGProperty.getInteger`, with `INVALID_PARAMETER_VALUE` — that is the shape the rest should have.
My preference is to match libpq: apply only when `tcpKeepAlive=true`, and where the option is unsupported log a warning and carry on. That removes most of this. If you would rather fail loudly, it has to be a `PSQLException` through `GT.tr` naming the connection property, and the docs have to say so.