[Draft] Remote query cache plugin #1531

QuChen88 · 2025-09-12T19:12:00Z

Summary

Remote caching plugin implementation. The goal of the plugin is to cache query result in a remote cache server for certain read-only queries that are deemed to be cacheable. All incoming queries that contain a query hint with caching parameter settings specified will have their responses cached with the defined TTL. Further requests with the same query get their result served from the cache instead of from the backend database. The remote cache server runs on Redis / Valkey and is assumed to be able to scale and handle eviction of data when the cache is full, so the size limitation is no longer an issue on the client side.

Basic walkthrough of code:

The entry point for the code is DataRemoteCachePlugin.java. It contains the core logic for the remote caching on both the query read path and write path. It will call into CacheConnection.java to handle reading and writing to the remote cache server.
CacheConnection.java mainly handles interaction between the client and the cache server via a connection pool. On the write path, the query result gets serialized into raw bytes which gets stored in the cache server. On the read path, the query result gets fetched from the cache server, de-serialized into Java objects and returned back to the driver application for consumption.
The logic to handle cached query result is CachedResultSet.java. getXXX APIs there for supported for various data types (e.g. String, boolean, int, double, float, Date, Timestamp, etc) along with serialization and de-serialization logic for CachedResultSet.
Supports plain username/password authentication to the cache server
Supports IAM authentication for cache connections to AWS Elasticache
The existing DataCacheConnectionPlugin.java has been re-factored into DataLocalCacheConnectionPluginFactory.java to have a more descriptive name indicating it is storing cached results locally.
Unit testing for the new logic is included
Example program is added to indicate how to use the new DataRemoteCachePlugin. Specifically a few additional properties are required for the plugin to work.

TODOs

Caching failure handling
Integration tests

examples/AWSDriverExample/src/main/java/software/amazon/DatabaseConnectionWithCacheExample.java

wrapper/src/main/java/software/amazon/jdbc/plugin/cache/CacheConnection.java

wrapper/src/main/java/software/amazon/jdbc/plugin/cache/DataRemoteCachePlugin.java

QuChen88 · 2025-10-11T20:01:59Z

Updated with support for authentication.

…on code for CachedResultSet.

Signed-off-by: Nihal Mehta <[email protected]>

…ined as a comment that prefixes the actual SQL query string. It can be in a case-insensitive form of "/* cacheTTL=60s */" to indicate that the query should be cached with 60 seconds of TTL. Or it can indicate the query should not be cached via "/* no cache */". Allow reading cache query result from replica in cluster mode enabled Redis/Valkey, and support cluster mode disabled setting. Re-factored all the caching logic into its own directory, and removed unnecessary code and logging. Fix several issues with caching results: - Handle failure in cache connection initialization as a cache miss - Support getString(), getInt(), getDouble(), getFloat(), getBigDecimal(), getBoolean(), getDate(), getTime(), getTimestamp(), getShort() and getByte() APIs for CachedResultSet - Fix a bug with converting ResultSet into CachedResultSet, and populate basic info for ResultSetMetaData.

Signed-off-by: Nihal Mehta <[email protected]>

…saction. Add unit test for CacheConnection logic.

--------- Co-authored-by: Roberto Luna Rojas <[email protected]>

…ample file to reflect database-agnostic functionality --------- Co-authored-by: Roberto Luna Rojas <[email protected]>

…emetry.

…mple program

…ic to rely on standard Java object serialization instead of custom JacksonMapper logic. Namely removed custom serialization logic for several special data types that are returned by the underlying SQL driver. Handle conversion from Number for getBigDecimal() and added unit tests for it.

…s (pull request #1) - Replace /* cacheTTL=300s */ with /*+ CACHE_PARAM(ttl=300s) */ format - Add case-insensitive CACHE_PARAM parsing with flexible placement - Implement malformed hint detection with JdbcCacheMalformedQueryHint telemetry - Add comprehensive test coverage for valid/invalid/malformed cases - Support multiple parameters for future extensibility Fixes: Query hint parsing to follow Oracle SQL hint standards feat: add TTL validation for cache query hints - Reject TTL values <= 0 as malformed hints - Allow large TTL values (no upper limit) - Increment malformed hint counter for invalid TTL values - Add comprehensive test coverage for TTL edge cases Validates: ttl=0s, ttl=-10s → not cacheable Allows: ttl=999999s → cache with large TTL updated test cases to reflect new implementation

…improve the caching performance. Renamed DataCacheConnectionPlugin to DataLocalCacheConnectionPlugin for clarity

… support to CachedResultSet (PR #2) fix: Add Timestamp support to CachedResultSet getTime() and getDate() - Implement missing instanceof Timestamp cases in convertToTime() and convertToDate() - Use new Time(timestamp.getTime()) and new Date(timestamp.getTime()) for standard JDBC behavior - Add comprehensive test coverage for Timestamp conversion scenarios - Fix object equality issues in tests by using consistent constructors Resolves missing Timestamp handling that previously fell through to string parsing. added more tests and cleaned up debug logs removed uncessary imports, fixed testing logic for getTime() and getDate() and fixed implementation error for getBytes() and getBoolean() in the original codebase updated future timestamp testing to make it more robust intead of hardcoding the future timestamp updated convertToTime() to use static timezone offset -- functionality unchanged

…etter error logging.

…ssCount, and JdbcCachedQueryAfterUpdate (PR #3) JdbcCachedQueryAfterUpdate feature removed Add OpenTelemetry integration for cache latency monitoring fixed variable naming, added one more context for latency tracking took out cacheMissContext and removed dbContext setSuccess logging removed redundant variables handled closing cacheContext for SQLException and removed dbContext error handling minor syntax fix updated unit tests for the latest telemetry metrics

The postgres test table contains 11 columns containing different data types. The example program populates the table with 400K records, each record has > 1KB of data, for a total of ~520MB of data in the table. It then performs SELECT queries continuously across all 400K rows. postgres=# CREATE TABLE test (id SERIAL PRIMARY KEY, int_col INTEGER, varchar_col varchar(50) NOT NULL, text_col TEXT, num_col DOUBLE PRECISION, date_col date, time_col TIME WITHOUT TIME ZONE, time_tz TIME WITH TIME ZONE, ts_col TIMESTAMP WITHOUT TIME ZONE, ts_tz TIMESTAMP WITH TIME ZONE), description TEXT; CREATE TABLE postgres=# select * from test; id | int_col | varchar_col | text_col | num_col | date_col | time_col | time_tz | ts_col | ts_tz | description ----+---------+-------------+----------+---------+----------+----------+---------+--------+-------+-------------- (0 rows) Suppress debug logs and only log at INFO level and above for example program.

- Add ElastiCacheIamTokenUtility for token generation - Extend DataRemoteCachePlugin with IAM auth detection - Support serverless and regular ElastiCache endpoints - Implement 15-minute token refresh and 12-hour re-auth cycles - Add cacheIamAuthEnabled configuration property

…ion pool

Caching: Allow user to configure cache connection timeout and max cache connection count

…tSet objects

alexey-amazon reviewed Sep 12, 2025

View reviewed changes

QuChen88 force-pushed the caching branch 2 times, most recently from 0ebf8b3 to 2abea77 Compare October 7, 2025 18:35

QuChen88 and others added 11 commits October 17, 2025 09:52

Initial prototype for remote query cache plugin. Re-factored the comm…

792dc19

…on code for CachedResultSet.

Add Cache Connection pool support

9ab2f67

Signed-off-by: Nihal Mehta <[email protected]>

Make write operation to the cache async

8c4f65d

Signed-off-by: Nihal Mehta <[email protected]>

Caching - don't cache queries that are part of a multi-statement tran…

213d89f

…saction. Add unit test for CacheConnection logic.

Customize TLS connection parameter for DB remote caching

699c5e5

--------- Co-authored-by: Roberto Luna Rojas <[email protected]>

Read properties definition from a separate config file, and rename ex…

51e0bd6

…ample file to reflect database-agnostic functionality --------- Co-authored-by: Roberto Luna Rojas <[email protected]>

Caching - minor fixes after rebase including doing null check for tel…

98a5038

…emetry.

Create connection pool without relying on Lettuce methods

90e3d05

Add Multi-threaded concurrent environment to DBConnectionWithCacheExa…

6fe29b3

…mple program

QuChen88 force-pushed the caching branch from acf1c7d to df1b27c Compare October 17, 2025 17:17

Frank-Gu-81 and others added 6 commits October 17, 2025 10:20

Caching - fetch and store the schema name for local session state to …

b8d3db4

…improve the caching performance. Renamed DataCacheConnectionPlugin to DataLocalCacheConnectionPlugin for clarity

Support getSQLXML() for CachedResultSet. Update CacheConnection for b…

5409868

…etter error logging.

QuChen88 force-pushed the caching branch 2 times, most recently from 0515db4 to 27433c5 Compare October 17, 2025 18:21

QuChen88 and others added 3 commits October 17, 2025 12:40

Address some review comments. Fix perf testing program.

de27d6f

Not de-serialize cached responses until the column field gets accessed.

e96c476

QuChen88 force-pushed the caching branch from 27433c5 to 57551d4 Compare October 17, 2025 19:41

Arunsarma07 and others added 2 commits October 29, 2025 20:03

Caching: Allow user to configure cache connection timeout and connect…

b7cd939

…ion pool

Merge pull request #6 from Arunsarma07/arunorgn

d568839

Caching: Allow user to configure cache connection timeout and max cache connection count

Caching - properly bypass the cache for queries that return non Resul…

c12d3ed

…tSet objects

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Draft] Remote query cache plugin #1531

[Draft] Remote query cache plugin #1531

Uh oh!

QuChen88 commented Sep 12, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

QuChen88 commented Oct 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

[Draft] Remote query cache plugin #1531

Are you sure you want to change the base?

[Draft] Remote query cache plugin #1531

Uh oh!

Conversation

QuChen88 commented Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Basic walkthrough of code:

TODOs

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

QuChen88 commented Oct 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

QuChen88 commented Sep 12, 2025 •

edited

Loading