Cache with Oracle Database

[Davide-Cocco]

Adds a new Oracle-backed Micronaut cache implementation with database persistence, scheduler-driven cleanup, and schema bootstrap support:

• new cache-oracle module with SyncCache beans for configured cache names
• Oracle table/procedure schema initialization on startup
• non-blocking (default) and Oracle-managed blocking write paths
• expiry cleanup via Oracle scheduler jobs (plus direct cleanup support)
• timezone-safe expiry handling
• lightweight asynchronous cache stats persistence
• shared sync TCK wiring and expanded Testcontainers integration coverage

Key implementation points

• configured caches are created as SyncCache beans
• cache entries are persisted in Oracle tables and serialized as JSON payloads
• cleanup is performed in bounded batches and can enforce expiry, maximum size, and maximum weight
• scheduler registration (and schema initialization) is idempotent and updates existing Oracle jobs in place
• stats updates are best-effort, async, and operation-driven

Verification

• full :micronaut-cache-oracle:test suite passes
• shared Oracle sync TCK passes (both for blocking and non-blocking mode)
• integration tests cover real Oracle schema init, cleanup, scheduling, timezone behavior, and stats updates
• manual testing on small test application follows expected behaviors

NOTE: this is a subsequent iteration of another closed PR. This one was re-created with squashed history and correct commit author attribution (previous one was using a placeholder git config).

[Copilot]

Pull request overview

Adds a new Oracle-backed Micronaut SyncCache implementation with schema bootstrap, scheduler-driven cleanup, and expanded testing/docs to support Oracle database persistence.

Changes:

• Introduces new cache-oracle module with Oracle schema DDL/PLSQL, cache implementation, repositories, and bean factory wiring.
• Adds Oracle-specific documentation and links it into the guide TOC.
• Expands automated testing via Testcontainers-based Oracle integration tests and shared sync TCK coverage.

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/main/docs/guide/toc.yml	Adds Oracle docs entry to the guide TOC.
src/main/docs/guide/oracle.adoc	New documentation for Oracle cache usage and configuration.
settings.gradle	Includes new cache-oracle module; imports Micronaut Data/SQL BOM catalogs.
gradle/libs.versions.toml	Adds Oracle JDBC + Testcontainers Oracle and Micronaut Data/SQL version/bom entries.
cache-oracle/build.gradle	Configures the new module dependencies and Testcontainers-related test settings.
cache-oracle/src/main/resources/db/oracle-cache.sql	Defines Oracle tables, indexes, and stored procedures for cache persistence, cleanup, scheduling, and blocking puts.
cache-oracle/src/main/java/io/micronaut/cache/oracle/OracleCacheFactory.java	Wires OracleSyncCache + shared OracleKeySerializer as Micronaut beans.
cache-oracle/src/main/java/io/micronaut/cache/oracle/OracleSyncCache.java	Implements Oracle-backed SyncCache operations, blocking/non-blocking writes, cleanup, and async stats updates.
cache-oracle/src/main/java/io/micronaut/cache/oracle/configuration/OracleCacheConfiguration.java	Adds Oracle-specific per-cache configuration (blocking, cleanup interval/batch, lock timeout).
cache-oracle/src/main/java/io/micronaut/cache/oracle/schema/OracleCacheSchemaInitializer.java	Bootstraps schema and upserts per-cache config + registers cleanup jobs at startup.
cache-oracle/src/main/java/io/micronaut/cache/oracle/serialization/OracleKeySerializer.java	Canonicalizes keys to stable JSON payload + SHA-256 hash.
cache-oracle/src/main/java/io/micronaut/cache/oracle/serialization/OracleCacheKey.java	Holds key hash + key payload bytes (value object).
cache-oracle/src/main/java/io/micronaut/cache/oracle/persistence/OracleCacheEntryRepository.java	Micronaut Data repository for entries + stored procedure binding.
cache-oracle/src/main/java/io/micronaut/cache/oracle/persistence/OracleCacheStatsRepository.java	Micronaut Data repository for stats updates via stored procedure.
cache-oracle/src/main/java/io/micronaut/cache/oracle/persistence/CacheEntryEntity.java	Entity mapping for MN_CACHE_ENTRY.
cache-oracle/src/main/java/io/micronaut/cache/oracle/persistence/CacheEntryId.java	Composite ID mapping for cache entries.
cache-oracle/src/main/java/io/micronaut/cache/oracle/persistence/CacheStatsEntity.java	Entity mapping for MN_CACHE_STATS.
cache-oracle/src/main/java/io/micronaut/cache/oracle/persistence/CacheConfigEntity.java	Entity mapping for MN_CACHE_CONFIG.
cache-oracle/src/main/java/io/micronaut/cache/oracle/package-info.java	Package-level Javadoc for the new module.
cache-oracle/src/test/resources/oracle-init/grant-cleanup-job-privileges.sql	Test-only SQL script to grant scheduler permissions to the test user.
cache-oracle/src/test/resources/logback.xml	Test logging configuration for the new module.
cache-oracle/src/test/groovy/io/micronaut/cache/oracle/OracleTestSupport.groovy	Testcontainers Oracle bootstrapping + schema init + privilege grants helper.
cache-oracle/src/test/groovy/io/micronaut/cache/oracle/OracleIntegrationSupport.groovy	Shared base for Oracle integration tests.
cache-oracle/src/test/groovy/io/micronaut/cache/oracle/OracleKeySerializerTest.groovy	Unit tests for canonical cache key serialization.
cache-oracle/src/test/groovy/io/micronaut/cache/oracle/OracleSyncCacheTest.groovy	Unit tests for core OracleSyncCache semantics and edge cases.
cache-oracle/src/test/groovy/io/micronaut/cache/oracle/OracleSyncCacheIntegrationTest.groovy	Integration tests exercising real Oracle persistence and async stats.
cache-oracle/src/test/groovy/io/micronaut/cache/oracle/OracleCleanupIntegrationTest.groovy	Integration tests verifying cleanup behavior including timezone handling and limits.
cache-oracle/src/test/groovy/io/micronaut/cache/oracle/OracleCleanupScheduleIntegrationTest.groovy	Integration test verifying Oracle Scheduler-based cleanup job registration and execution.
cache-oracle/src/test/groovy/io/micronaut/cache/oracle/OracleCacheRepositoryTest.groovy	Integration tests covering repository-level persistence/invalidation behaviors.
cache-oracle/src/test/groovy/io/micronaut/cache/oracle/OracleCacheConfigurationTest.groovy	Unit tests validating property binding + validation for Oracle cache configuration.
cache-oracle/src/test/groovy/io/micronaut/cache/oracle/schema/OracleCacheSchemaInitializerIntegrationTest.groovy	Integration tests validating schema init, procedures, and job registration.
cache-oracle/src/test/groovy/io/micronaut/cache/oracle/tck/OracleTckSupport.groovy	Shared TCK support context for Oracle-backed sync cache.
cache-oracle/src/test/groovy/io/micronaut/cache/oracle/tck/OracleSyncCacheSpec.groovy	Sync cache TCK spec for non-blocking mode.
cache-oracle/src/test/groovy/io/micronaut/cache/oracle/tck/OracleBlockingSyncCacheSpec.groovy	Sync cache TCK spec for blocking mode.
cache-core/src/main/java/io/micronaut/cache/interceptor/ParametersKey.java	Adds getParameters() accessor to support key serialization.

[ericsedlar]

Are you using OSON for serializing JSON?

[Davide-Cocco]

Are you using OSON for serializing JSON?

@ericsedlar Answering here as I do not seem to have the option to answer on thread. I am using Micronaut's JsonMapper, can switch to OSON if necessary.

[ericsedlar]

I think we should also have an OSON option

[ericsedlar]

We have OSON support in https://github.com/micronaut-projects/micronaut-serialization/tree/3.0.x/serde-oracle-jdbc-json If you are using Micronaut Data with JSON columns it is used automatically Graeme

[Davide-Cocco]

@radovanradic @alvarosanchez
Completed all tasks (added prefix support, Flyway, OSON).
Also added validation through tests and tested manually all flows (including migration) on a mock consumer app.
Asking for another round of review, and thanks again for the suggestions.

[Davide-Cocco]

@ericsedlar @graemerocher
Switched to Micronat Data with JSON columns as io.micronaut.serde.oracle.jdbc.json.OracleJdbcJsonBinaryObjectMapper
as requested

[alvarosanchez]

This is overall looking in the right direction, few minor changes requested.

The only thing I'm wondering is: how well is this design prepared to support other databases in the future?

[graemerocher]

do we want a hard dependency on Flyway for this?

[Davide-Cocco]

Made optional. Now there is a default migrator and a Flyway one, which the user can decide to toggle by adding flyway dep. Documentation edited.

[graemerocher]

@copilot resolve the merge conflicts in this pull request