datasource-proxy intercepts JDBC calls through a proxy DataSource

A proxy in front of the DataSource, not a driver

datasource-proxy provides proxy classes for the JDBC API, allowing you to intercept query execution and JDBC method calls. The repository description calls it a listener framework for JDBC interactions and query executions via proxy.

The mechanism is the standard Java proxy pattern applied to the JDBC interfaces. A proxy class implements the DataSource, Connection, Statement, PreparedStatement and ResultSet interfaces, holds a real implementation behind it, and forwards every call. Along the way it hands the call to a set of listeners, which are your extension point. The query-metrics and logging topics on the repository, and the listener classes the README mentions, all sit on that seam.

What that buys you is visibility at a level that a JDBC driver does not offer. A driver's own logging tells you about statements; a proxy sees the statement execution and the JDBC method calls around it, including the ones that fail, and it sees them from inside your process rather than from a separate agent.

The project is by the jdbc-observations organisation, hosted under the net.ttddyy group id on Maven Central, and is MIT licensed with a license.txt at the root. The last push was on 2026-10-13 and the repository is not archived.

The audience is application teams and library authors who need to instrument database access from inside the JVM: teams adding structured query logging, teams collecting per-query metrics, and framework authors who want a hook that their users can switch on without changing application code.

Listeners, and integrations that are optional

The listener model is where the library earns its place, and the README is clear about how much it brings with it.

The library has no required third-party dependencies, and integrations are optional. The example given is SLF4JQueryLoggingListener, which requires the SLF4J library. That is the whole contract: the proxy classes and the listener interfaces are the library, and anything that connects to a logging framework or a metrics system is an integration you add.

That is a good design for a library that gets dropped into an existing application. A team that already logs through SLF4J adds one binding and one listener; a team that does not, does not, and nothing about the proxy is tied to a particular logging backend. It also means the artifact is small enough to put on the classpath of a library rather than only an application, which matters if you are writing a framework and want to expose a query hook to your users.

The README is less detailed about the listener interfaces themselves than an adopter might want, which is where the user guide comes in. There are three sets of documentation links, and the distinction between them is useful. There is a user guide for the current release version and one for the snapshot version, plus a user guide for older versions in the repository wiki. The same pattern repeats for the Javadoc, with current and snapshot API documentation and an older set in the wiki.

So the documentation follows the release cadence. Whatever you pin, there is a user guide and a Javadoc set for that version, and the wiki holds what is no longer published.

Adding it to a Maven build, and the snapshot channel

The Maven coordinates are the first thing you need, and the README gives them with a placeholder for the version:

<dependency>
  <groupId>net.ttddyy</groupId>
  <artifactId>datasource-proxy</artifactId>
  <version>[LATEST_VERSION]</version>
</dependency>

The latest version is behind the Maven Central badge, which points at the artifact page on central.sonatype.com. You resolve the version yourself, and the placeholder in the snippet is the project telling you that it does not pin a version for you.

Snapshot releases are available from Maven Central as well. The README points at the official Sonatype documentation on consuming snapshot releases from the publish portal for the instructions, which matters because a snapshot repository needs declaring in your settings and the coordinates for it are not the same as the release ones.

The build requirements are unusually permissive. The library requires JDK 6 or later, and Java 8 and later are supported. The distinction is worth noting: it compiles and runs on an old runtime, which matters if you are shipping into a legacy environment, and it is supported on the modern ones.

The repository is a Maven project with a wrapper, mvnw and mvnw.bat, a pom.xml, a src directory and a CHANGELOG.md. There is also a jitpack.yml at the root, which means the project can be built from a commit hash through JitPack, which is occasionally useful when you need a specific snapshot of the library rather than a release.

What the proxy sees, and what it misses

The design has a clear consequence that any adopter should understand before wiring it up, and it is worth stating directly.

The proxy intercepts at the DataSource layer. Every connection, statement and result set that flows through the proxied DataSource is visible, and everything that does not flow through it is not. A second pool, a connection opened by a migration tool, a reporting job that uses a different driver, and any library that resolves its own DataSource are all outside the picture.

That is the trade the project makes, and it is a reasonable one. Intercepting inside the driver would cover everything the driver does, but it would mean modifying a third-party artifact rather than wrapping one, and it would tie you to a specific driver implementation. Wrapping the DataSource keeps the library independent of which JDBC driver you use, at the cost of only seeing the traffic that goes through your wrapped object.

For most instrumentation use cases that is the right boundary. Query logging and per-query metrics are usually wanted for the application's own traffic, not for every tool in the estate. But it does mean that a claim of complete database visibility is only true if the application is disciplined about where its connections come from, and the README does not document a mechanism for catching connections that bypass the proxy.

There is a second, smaller boundary. The proxy sits in the request path, so it adds a layer of indirection to every call. For a system that issues thousands of statements a second, that cost is small but it is not zero, and it is the price of the visibility.

Releases, versions and what to check before you depend on it

The release history shows a project with a long-lived 1.x line and a recent change of pace.

The recent releases are datasource-proxy-1.11.1 on 2026-10-13, datasource-proxy-1.11.0 on 2025-07-14, and datasource-proxy-1.10.1 on 2024-11-11. Read that as roughly eight months between 1.10.1 and 1.11.0, then fifteen months to 1.11.1, with the newest release landing on the same day as the last push.

That is the profile of a library that changes when its users need it to change, not on a fixed schedule. For an adopter it means two things. There is no release train to plan around, so you pin a version and read the changelog when you move. And the gap between the 2025-07-14 release and the 2026-10-13 one is worth a look, because a long gap on a JDBC library usually means either a quiet period or a large change, and the CHANGELOG.md at the repository root is where that would be recorded.

The documentation structure helps here. The user guide and the Javadoc are published per version, with a current set and a snapshot set, and older material in the wiki. When you evaluate the library, read the user guide that matches the version you would actually pin, not the snapshot one, because the snapshot is where unreleased changes are described.

There is a companion repository of examples, the datasource-proxy-examples project, which is usually the fastest way to see a working listener rather than reading the API documentation first. The MIT licence is permissive enough that a listener of your own can be published without obligation beyond the notice.

Editorial conclusion

Java teams that need query logging, metrics or audit trails around their JDBC access should evaluate datasource-proxy, because intercepting at the DataSource layer catches statement execution and the JDBC calls around it, and the library itself has no required dependencies so it adds nothing to your dependency graph. It is the wrong tool if your application does not use the proxied DataSource, because anything that connects by another path is invisible to it, and it is the wrong tool if you need centralised aggregation across processes. Before adopting, check that every datasource in your application can be routed through the proxy, and note the release pattern, where 1.10.1 to 1.11.0 took about eight months and 1.11.1 followed in October 2026.

Frequently asked questions

Official sources

1. Issues
2. jdbc-observations/datasource-proxy on GitHub
3. License: MIT
4. README
5. Releases