Skip to content

SYSTEM Cited by 1 source

pgjdbc (PostgreSQL JDBC Driver)

What it is

pgjdbc is the official open-source Type-4 JDBC driver for PostgreSQL. It implements the Postgres wire protocol directly in Java and is the canonical Java-ecosystem entry point to a Postgres server — every Java/JVM application talking to Postgres (Spring, Hibernate, JOOQ, Debezium, …) either uses pgjdbc directly or has it as a transitive dependency.

Maven coordinate: org.postgresql:postgresql.

Why it shows up on this wiki

pgjdbc sits below every JVM consumer of Postgres — including Debezium's Postgres source connector and Debezium Engine embedded-mode deployments. That makes driver-layer behaviour a universal lever: a single pgjdbc change propagates to every downstream Java client.

The KeepAlive-LSN-advancement fix (2023)

Historically, pgjdbc did not respond to Postgres KeepAlive messages received on a logical replication slot connection, even though those messages carry the current server WAL LSN. This meant the client-side logical- replication code could never advance the slot from the KeepAlive — the slot only advanced on explicit Replication message acks. An idle slot for a low-write-traffic table on a busy Postgres server would therefore pin WAL indefinitely → the well-known runaway WAL growth failure mode.

Zalando's 2023-11-08 post (sources/2023-11-08-zalando-patching-the-postgresql-jdbc-driver) documents the fix Zalando upstreamed: PR #2941, merged on 2023-08-31 and shipped in pgjdbc 42.7.0. The fix has the driver track two LSNs — last Replication message received and latest confirmed — and, when a KeepAlive arrives with a higher LSN and all seen messages are flushed, ack the higher LSN back to the server. The server-side slot advances; Postgres can reclaim older WAL. See concepts/keepalive-message-lsn-advancement for the mechanism in detail.

Because pgjdbc is a transitive dependency of Debezium, the fix benefits every Java Debezium deployment automatically when they pick up pgjdbc 42.7.0+ — a canonical patterns/upstream-the-fix / patterns/client-driver-fix-over-application-workaround instance.

Typical deployment shape

In a Debezium / Debezium-Engine CDC pipeline:

Postgres server ──(logical replication protocol)──▶
    pgjdbc driver ──(Java API: PGReplicationStream)──▶
    Debezium Postgres connector or Debezium Engine ──▶
    downstream sink (Kafka / Lambda / custom)

pgjdbc owns the wire-protocol layer (including the KeepAlive-response behaviour fixed in 42.7.0).

Seen in

  • sources/2023-11-08-zalando-patching-the-postgresql-jdbc-driver — canonical wiki introduction of pgjdbc. Zalando diagnose a runaway-WAL-growth failure mode stemming from pgjdbc's never-responding-to-KeepAlive behaviour; upstream the fix as PR #2941; package a locally-built 42.6.1-patched variant into a production rollout using parallel prod-vs-test Docker images while waiting for downstream Debezium-transitive uptake. Names pgjdbc as the load-bearing client-side actor in the Postgres-JVM CDC stack and as the right architectural layer to fix a bug that affects all downstream consumers.
Last updated · 501 distilled / 1,218 read