pg.ddx.io  GitHub: pgjdbc/pgjdbc (issues + PRs as email threads)  
help / color / mirror / Atom feed
From: vlsi (@vlsi) <noreply+vlsi@github.com>
To: pgjdbc/pgjdbc <noreply+pgjdbc-pgjdbc@github.com>
Subject: Re: [pgjdbc/pgjdbc] PR #3964 (changes requested): feat: add tcpKeepAliveCount, tcpKeepAliveIdle and tcpKeepAliveInterval connection properties
Date: Wed, 09 Sep 2026 20:20:23 +0000
Message-ID: <gh-pgjdbc-pgjdbc-3964-r5159448478@github.com> (raw)
In-Reply-To: <gh-pgjdbc-pgjdbc-3964@github.com>
References: <gh-pgjdbc-pgjdbc-3964@github.com>

Thanks for the patience on this one, and sorry it sat for so long. I reviewed the branch at 1d9b3a8f3 and ran it against a PostgreSQL 17 container on JDK 8, 11 and 21 (macOS). The feature does work on Linux and macOS with JDK 11+: I confirmed that `tcpKeepAliveCount=80`, `tcpKeepAliveIdle=900`, `tcpKeepAliveInterval=1000` reach the socket, and that they survive the SSL upgrade. The multi-release packaging is right too — `Multi-Release: true` is on every jar and the class lands in `META-INF/versions/11`. `checkstyleMain`, `checkstyleJava11`, `autostyleJavaCheck`, `forbiddenApisMain`, `forbiddenApisJava11`, `ConnectionTest` and `PGPropertyTest` are all green, and the branch still merges cleanly with master.

What blocks it is the capability check. `isSupported()` asks whether the JDK *declares* the field, and that is not the same question as whether the socket accepts the option — which means the driver breaks on platforms it silently assumes are fine, including for users who set none of the new properties.

## Blockers

### 1. `isSupported()` reports field presence, not option support

`SocketOptionReference.isSupported()` returns `socketOption != null`, i.e. "the reflective lookup of `jdk.net.ExtendedSocketOptions.TCP_KEEPCOUNT` succeeded". The JDK creates those three constants unconditionally and gates only their *registration*:

```java
// jdk/src/jdk.net/share/classes/jdk/net/ExtendedSocketOptions.java
public static final SocketOption<Integer> TCP_KEEPCOUNT = new ExtSocketOption<>("TCP_KEEPCOUNT", Integer.class);
...
if (keepAliveOptSupported) {
    options.addAll(Set.of(TCP_KEEPCOUNT, TCP_KEEPIDLE, TCP_KEEPINTERVAL));
}
```

`Socket.setOption`/`getOption` then throw `UnsupportedOperationException` for anything outside `supportedOptions()`. I proved the shape with `TCP_QUICKACK`, whose field resolves on macOS while the option is unsupported there:

```
field resolved reflectively: TCP_QUICKACK
supportedOptions contains TCP_QUICKACK = false
get THREW java.lang.UnsupportedOperationException: 'TCP_QUICKACK' not supported
set THREW java.lang.UnsupportedOperationException: 'TCP_QUICKACK' not supported
```

Two populations hit exactly this:

* **Windows on JDK 11–21.** Keep-alive extended socket options arrived on Windows only in JDK 22 — `jdk-21+35:src/jdk.net/windows/classes/jdk/net/WindowsSocketOptions.java` implements `IP_DONTFRAGMENT` and nothing else; `keepAliveOptionsSupported0()` was added by `f3ade388dac` ("8308593: Add Keepalive Extended Socket Options Support for Windows"), first released in `jdk-22+8`. So on windows-latest with JDK 11, 17 or 21 all three `is*Supported()` methods return `true` and every `setOption` throws.
* **Any `socketFactory` whose `Socket` is backed by a custom `SocketImpl`** — junixsocket for Unix-domain sockets, tunnelling factories. This is platform-independent; `java.net.SocketImpl`'s default `supportedOptions()` is empty:

```
supportedOptions=[]
get TCP_KEEPCOUNT THREW java.lang.UnsupportedOperationException: 'TCP_KEEPCOUNT' not supported
```

The check has to be `socket.supportedOptions().contains(option)`, which means the predicate needs the socket: `isTcpKeepCountSupported(Socket)`.

### 2. The `PGStream(PGStream, int)` copy constructor now breaks for users who set none of these properties

```java
keepCount = ExtendedSocketOptionAccessorImpl.INSTANCE.getTcpKeepCount(pgStream.getSocket());
keepIdle = ExtendedSocketOptionAccessorImpl.INSTANCE.getTcpKeepIdle(pgStream.getSocket());
keepInterval = ExtendedSocketOptionAccessorImpl.INSTANCE.getTcpKeepInterval(pgStream.getSocket());
```

These reads are unconditional, and they sit inside `try { ... } catch (SocketException ex)`. `UnsupportedOperationException` is not a `SocketException`, so on either population above it escapes the constructor. That constructor is the SSL fallback (`enableSSL`, server answers `'E'` to `SSLRequest`) and the `gssEncMode=prefer` fallback — paths a user reaches without ever having heard of `tcpKeepAliveIdle`. Note the getters also return the *system* default rather than null when the user set nothing, so the setters below always fire as well.

Please also move the reads behind a "did the user actually configure anything" check rather than reading and re-applying OS defaults on every stream rebuild.

(I checked the leak question: `tryConnect`'s `catch (Exception e) { closeStream(newStream, e); throw e; }` does close the old stream, since `newStream` is not reassigned when `enableSSL` throws. No leak.)

### 3. Error model: a configuration problem is reported as a driver bug or as a network failure

**JDK 8, any of the three set** — measured against a live server with the built jar:

```
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)
```

SQLState `99999`. We ask the user to file a bug report for a limitation we documented ourselves. Same outcome on a runtime without the `jdk.net` module (`--limit-modules`), and the same would happen on Windows/JDK 11–21. `openConnectionImpl` catches only `ConnectException`, `IOException` and `SQLException`, so the unchecked exception goes straight to `Driver.connect`'s catch-all.

**Out-of-range values** take the opposite wrong turn — `Socket.setOption` rejects them with a `SocketException`, which is an `IOException`, so the driver reports a network failure and marks the host dead:

```
tcpKeepAliveCount=-1        -> PSQLException [The connection attempt failed.] root=java.net.SocketException: Invalid argument
tcpKeepAliveIdle=-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)
```

`GlobalHostStatusTracker.hostStatusMap` is a static map, so one misconfigured DataSource marks those hosts `ConnectFail` for every other connection in the JVM until `hostRecheckSeconds` elapses. Note `tcpKeepAliveCount=abc` is already handled correctly, by `PGProperty.getInteger`, with `INVALID_PARAMETER_VALUE` — that is the shape the rest should have.

Whatever the outcome of point 4 below, the messages themselves need `GT.tr` (see AGENTS.md) and should name the connection property the user set, not the JDK constant.

### 4. Decide the contract, and follow libpq

libpq is the reference for this exact feature and it promises two things we do not:

> 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.

`fe-connect.c` applies `setKeepalivesIdle/Interval/Count` only inside the `usekeepalives != 0` branch, after `SO_KEEPALIVE` succeeded. This PR applies all three regardless of `tcpKeepAlive` (whose default is `false`, so the default configuration is the one where the three properties are set on the socket and change nothing), and turns an unsupported platform into a failed connection instead of a no-op.

I would like us to match libpq: apply only when `tcpKeepAlive=true`, and where the option is unsupported log a warning and carry on. That removes most of point 3 and all of point 1's user-visible damage. If you would rather fail loudly, that is defensible too — but then it has to be a `PSQLException` naming the property, and the docs have to say so.

### 5. The new CI axis will fail on Windows

`-DtcpKeepAliveCount=9` and friends do reach the driver — `TestUtil.mergeDefaultProperties` hands `System.getProperties()` to `DriverManager.getConnection` wholesale, no allow-list. Combined with point 1, every windows-latest job with JDK 11–21 and `keep_alive=yes` fails at connect. Over 40 matrix generations that combination was 7.1% of jobs (17 of 240). The axis itself is right, and this failure is it doing its job: running the whole suite with the properties set answers "does the mere presence of the setting break anything", which is the question that matters here. Keep it, and split `yes` into `on` (just `tcpKeepAlive=true`, which works on every JDK and every OS — today a Java 8 job titled `keep_alive` sets nothing at all) and `tuned` (the three new properties). Raise `-DtcpKeepAliveInterval=1` to `10`: with `count=9` the current value gives a nine-second death window, and a nine-second stall is not exotic on a loaded runner with a containerised server doing `fsync`. Whether `tuned` needs gating depends on point 4 — if an unsupported option is ignored with a warning, it can run everywhere and the axis covers the ignore path too; if it stays fatal, `tuned` has to exclude windows-latest below JDK 22. Details in the inline comment.

## Tests

* Every new assertion is behind `if (…isTcpKeepCountSupported())`. On the Java 8 matrix rows the java11 classes are not on the test classpath (`pgjdbc/build.gradle.kts` prepends `java11.output` only when `testJdkVersion >= 11`), the no-op accessor returns `false`, and **all nine assertions are skipped while both tests report green**. Please use `assumeTrue(..., "reason")` so a skip is visible in the report, and gate on `supportedOptions()` rather than on `isSupported()`.
* Both tests read the expected value back through the accessor that wrote it, so the most likely real defect — a name-to-option mapping that swaps `TCP_KEEPCOUNT` and `TCP_KEEPIDLE` — survives them. The oracle should be `java.net.Socket.getOption(...)` directly. Test sources compile with `--release 8`, so that needs a small reflective helper; it works, I checked. Please also pick three values that differ from each other *and* from the platform defaults (8 / 7200 / 75).
* Nothing covers: the JDK 8 refusal (the `UnsupportedOperationException` in the java8 accessor is dead code today); an unsupported option on a JDK 11+ platform; `tcpKeepAlive=false` with the three set; negative, zero, `Integer.MAX_VALUE` and non-numeric values; `PGProperty.setInteger(props, null)` removing the key.
* Most of that needs no server. `ExtendedSocketOptionAccessorImpl` is fully observable against a loopback `ServerSocket` in one process, and `pgjdbc/src/test/java/org/postgresql/core/` already hosts server-free tests. An `ExtendedSocketOptionAccessorImplTest` there would be the right home.
* `assertEquals(80, ...)` with no message: three failures in one test print `expected: <80> but was: <8>` with nothing naming the option. Add the operand name as the message.
* `socketSettings` names a topic rather than a claim; something like `aConnectionAppliesTheKeepAliveProbeSettingsToTheSocket` says what a failure means.

## Documentation

* "Only supported from JDK 11 onwards and only when `jdk.net.ExtendedSocketOptions` is available" is not the condition the code tests, and not the condition that holds: the class itself is `@since 1.8`, the three fields are `@since 11`, and support is per platform on top of that. Say what actually decides it — Linux and macOS from JDK 11, Windows from JDK 22 — and say what happens when it does not hold.
* Nowhere do we say the three have no effect unless `tcpKeepAlive=true`. That is the single most important sentence for a reader, and it belongs on the `tcpKeepAlive` entry too.
* "The default value for this keep-alive probe retransmit limit is system dependent, but is typically 8" is copied from the JDK javadoc but reads as our claim once it is in `PGProperty`, and it is wrong on Linux, where `tcp_keepalive_probes` defaults to 9. I would drop all three "typically N" sentences: we do not set the default, and "the value the operating system applies" is the fact a user can act on.
* Please state the unit (seconds) for `tcpKeepAliveIdle` and `tcpKeepAliveInterval` in every place they are documented, including the `BaseDataSource` setters.
* `CHANGELOG.md` needs an `### Added` entry under `[Unreleased]`, the way `classLoaderStrategy`, `connectExecutor`, `flushCacheOnDdl` and `reWriteBatchedInsertsSize` have one.

## Smaller things

* `BaseDataSource.getTcpKeepAliveCount()` and its two siblings catch `PSQLException` and return `null`, so a malformed value reads back as "unset" while the connection still fails later. Every other integer getter in that class uses `getIntNoCheck` and lets the error out.
* `org.postgresql.core.ExtendedSocketOptionAccessor` is public in an exported package and is never used as a type — all call sites go through the concrete `ExtendedSocketOptionAccessorImpl.INSTANCE`, and the three `is*Supported()` methods have only test callers. Either use the interface as the declared type (the way `LazyCleanerImpl implements LazyCleaner` does in the same source set) or drop it. The two variants also disagree on `throws IOException`.
* `ClassUtils.forName(..., ClassLoaderStrategy.DRIVER, ClassLoader.getPlatformClassLoader())` is documented as loading "a class named by a connection property", and passing the platform loader as `driverClassLoader` with `expectedClass = Object.class` defeats the type check it exists for. A plain `Class.forName(name, false, ClassLoader.getPlatformClassLoader())` says what is happening.
* `createIntegerSocketOption` catches `NoSuchFieldException | ClassNotFoundException | IllegalAccessException`. `SecurityException`, `NoClassDefFoundError` and `ExceptionInInitializerError` (the `ExtendedSocketOptions` static initialiser runs on the `Field.get(null)`, and it loads the `extnet` native library) escape into the connect path.
* Class comments: the two `ExtendedSocketOptionAccessorImpl` variants carry byte-identical `Internal class, it is not a part of public API.` and neither says which JDK loads it. `LazyCleanerImpl` in the same source set is the precedent to follow. The `ExtendedSocketOptionAccessor` methods have no documentation at all, and `isTcpKeepCountSupported()` is exactly the one whose contract a reader cannot guess.
* `PGProperty.setInteger`'s javadoc is a verbatim copy of `set(Properties, String)`'s and omits the only thing that distinguishes it — a `null` value removes the key.
* `ConnectionFactoryImpl:619` (the GSS `'E'` reconnect) builds a fresh `PGStream` with the four-argument constructor, so it drops the three new options along with `keepAlive`, `tcpNoDelay` and both buffer sizes. Pre-existing for the old settings; worth a follow-up issue rather than fixing here.
* `// Enable TCP keep-alive probe if required.` in `tryConnect` now heads four statements, three of which run whatever `tcpKeepAlive` is.
* `matrix.mjs`: the new axis is indented three and four spaces where its neighbours use two, and `-DtcpKeepAliveInterval=1` is the most aggressive value the option takes — `5` costs nothing on a loaded runner.
* README table padding on the three new rows, and `use.md` writes `*integer*` where its neighbours write `*int*`.

Happy to help with any of this — the core of the change is right and the feature is worth having.

view thread (85+ messages)  latest in thread

Message-ID: <gh-pgjdbc-pgjdbc-3964-r5159448478@github.com>
Permalink:  ../gh-pgjdbc-pgjdbc-3964-r5159448478@github.com/

 · 


This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox