Ask your AI assistant a question about your data, and let it inspect the schema, write SQL, and run the query against Oracle AI Database.

In this walkthrough, we’ll connect Claude Code or Codex to Oracle AI Database Free through the Model Context Protocol (MCP) endpoint in Oracle REST Data Services (ORDS). Docker Compose starts the local lab, with Keycloak providing authentication.

By the end, you’ll be querying a sample dataset in plain English. Oracle’s configuration guide covers the endpoint and authentication settings used in the setup.

Download and start the sample

Check out the sample repository on GitHub. You need Docker Compose, curl, jq, and a coding assistant like Claude Code or Codex.

Once you have the sample downloaded, change into the ords-docker-compose directory and start the containers using the mcp profile:

cd ords-docker-compose
docker compose --profile mcp up -d --wait

The profile starts Keycloak in development mode and imports the lab’s realm configuration. The configure-mcp.sh script is run during startup to set ORDS MCP settings to point to Keycloak, and to configure a separate database pool for MCP.

The database startup script, ords_init.sql, creates the sales schema, seeds the data, and creates the MCP_READER user. The mcp-config service waits for Keycloak and the initialized schema, then configures ORDS.

The sales schema has four related tables in TESTUSER and four read-only views with the same names in MCP_READER:

Table / view  Rows  Contents
────────────  ────  ─────────────────────────────────
CUSTOMERS       6  Names, emails, cities, and
                   country codes
PRODUCTS        8  Product categories, current unit
                   prices, and stock quantities
ORDERS         12  Customer, order date, and status
ORDER_ITEMS    24  Order, product, quantity, and
                   purchase unit price

Orders reference customers, and order items reference orders and products through foreign keys.

MCP_READER has CREATE SESSION and SELECT on the four base tables.

Inspect a token from Keycloak

Fetch a token from Keycloak using the helper script:

export ORDS_MCP_TOKEN=$(./scripts/get-token.sh)

This token can be used to authenticate against ORDS MCP, and contains the following metadata:

Setting   Value
────────  ─────────────────────────────────────────
Realm     ords-lab
Issuer    http://localhost:8081/realms/ords-lab
Audience  http://localhost:8888/mcp
Scope     urn:oracle:dbtools:ords:mcpserver:all
Grant     client_credentials

ORDS fetches public signing keys from http://keycloak:8080/realms/ords-lab/protocol/openid-connect/certs over the Compose network. The issuer is the public localhost URL. Keycloak’s realm import and hostname configuration documentation describe these mechanisms.

Connect Codex desktop or CLI

Add or update ords in ~/.codex/config.toml, replacing the token helper script path with the absolute path to your checkout:

[mcp_servers.ords]
url = "http://localhost:8888/mcp"
http_headers_helper = "/bin/bash /absolute/path/to/oracle-database-java-samples/ords-docker-compose/scripts/get-token.sh --headers"

The token script returns a raw token by default or authorization-header JSON with --headers. Restart Codex once to load the configuration. See the official Codex MCP documentation for additional details on configuring MCP.

Connect Claude Code

Merge this entry into .mcp.json in this lab directory, replacing the script path with the absolute path to your checkout:

{
  "mcpServers": {
    "ords": {
      "type": "http",
      "url": "http://localhost:8888/mcp",
      "headersHelper": "/bin/bash /absolute/path/to/oracle-database-java-samples/ords-docker-compose/scripts/get-token.sh --headers"
    }
  }
}

The same helper supplies fresh authorization headers at connection time. After a tool call returns HTTP 401 or 403, Claude Code re-runs the helper, reconnects, and retries once.

See the official Claude Code dynamic-header documentation.

Try a query

In either client, ask:

Use the ORDS MCP server to discover the mcp-lab database, inspect its schema, and report the total order value by status.

The sample returns CANCELLED = 99.93, DELIVERED = 709.82, PENDING = 821.78, and SHIPPED = 584.38. Try some other prompts to experiment:

• Which customers have the highest order value, excluding cancelled orders?
• What is the order value by product category and customer country?
• How does October order value compare with November, excluding cancelled orders?
• Which products appear in pending orders, and how much stock is available?

For example, the category and country question can use this SQL through sql_run:

select c.country, p.category, sum(i.quantity * i.unit_price) as total
from customers c
join orders o on o.customer_id = c.id
join order_items i on i.order_id = o.id
join products p on p.id = i.product_id
where o.status <> 'CANCELLED'
group by c.country, p.category
order by c.country, p.category;

Both Codex and Claude Code renew expired tokens through the helper above. See Oracle’s MCP configuration guide and MCP developer guide for the authentication and tool interfaces.

Customization

• Add database initialization scripts to oracle/ (e.g., modify ords_init.sql or add your own scripts).
• Environment variables can be adjusted in docker-compose.yml (e.g., change passwords or ports).

Notes

• The database has no persistent data volume in this sample; recreating ordsdb discards its data. Back up any work before switching images.
• ORDS uses container-registry.oracle.com/database/ords:latest.
• Volumes persist configuration and downloaded APEX files; remove them with docker-compose down -v if needed.
• If you first started the database without APEX and later enable APEX, use docker-compose down -v before restarting so the Oracle AI Database container initializes cleanly with APEX.
• For more details on ORDS, visit the official documentation.

If you encounter issues, check container logs:

docker logs ords
docker logs ordsdb

Oracle REST Data Services (ORDS) is a great addition to your Oracle AI Database stack. But, do you know how to configure ORDS observability?

In this article, we’ll demonstrate how to collect telemetry data from ORDS that shows what happens during HTTP request processing, which SQL operations ran, what ORDS logged, and the state of the ORDS connection pool.

This lab builds on the Full-Stack Oracle Observability Lab, using OpenTelemetry to collect observability data from ORDS with Oracle AI Database Free. You can check out the code on GitHub; if you like the lab, give the repo a star!

ORDS Observability with OpenTelemetry and Grafana

In the lab, ORDS runs as a container with the OpenTelemetry Java Agent attached. The agent sends telemetry to the OpenTelemetry Collector inside Grafana LGTM. Tempo stores traces, Loki stores logs, and Prometheus stores metrics.

Installing the OpenTelemetry agent and configuring ORDS in the Dockerfile. Always use the latest agent version:

FROM container-registry.oracle.com/database/ords:latest
# Pin the agent and verify the release artifact at build time.
RUN curl -fsSL https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.33.1/opentelemetry-javaagent.jar \
        -o /opt/oracle/ords/opentelemetry-javaagent.jar \
    && echo 'e43a270df53c6f423e0ab157be9c27ccc01d5dc3232e162fe54777573db2f149  /opt/oracle/ords/opentelemetry-javaagent.jar' | sha256sum -c -
# Keep installation and SQLcl commands free of instrumentation.
RUN mv /opt/oracle/ords/bin/ords /opt/oracle/ords/bin/ords-original
COPY --chown=oracle:oinstall serve-with-agent.sh /opt/oracle/ords/bin/ords
RUN chmod +x /opt/oracle/ords/bin/ords
COPY setup-schema.sh /ords-entrypoint.d/10-setup-schema.sh
COPY schema.sql /opt/oracle/lab-schema.sql

The lab attaches the Java agent when starting ords serve, following the approach described in the ORDS OpenTelemetry documentation.

Agent attachment uses the serve-with-agent.sh script:

if [[ "${1:-}" == "serve" ]]; then
    set -- --java-options "-javaagent:/opt/oracle/ords/opentelemetry-javaagent.jar" "$@"
fi
exec /opt/oracle/ords/bin/ords-original "$@"

The environment variables configured in the lab look like this:

OTEL_SERVICE_NAME: ords
OTEL_EXPORTER_OTLP_ENDPOINT: http://grafana-lgtm:4318
OTEL_EXPORTER_OTLP_PROTOCOL: http/protobuf
OTEL_TRACES_EXPORTER: otlp
OTEL_METRICS_EXPORTER: otlp
OTEL_LOGS_EXPORTER: otlp
OTEL_METRIC_EXPORT_INTERVAL: "15000"
OTEL_TRACES_SAMPLER: always_on
OTEL_INSTRUMENTATION_JAVA_UTIL_LOGGING_ENABLED: "true"

The service name identifies ORDS across the telemetry signals. The collector endpoint uses its Compose service address because ORDS runs inside the container network.

The Oracle AI Database Metrics Exporter runs separately, adding complementary database metrics.

Start the lab with ORDS enabled

You’ll need Docker with Compose v2 and at least 8 GB of memory allocated to Docker. From the lab directory, enable the ords profile with Docker Compose:

docker compose --profile ords up \
  -d --build --wait --wait-timeout 900

This starts ORDS alongside the database and observability services. On its first start, ORDS installs its metadata and enables the lab’s REST endpoint.

Follow a request through ORDS

First, generate some continuous traffic with the workload.sh script:

ORDS_URL=http://localhost:8888/ords/lab/readings/ ./workload.sh

Metrics export every 15 seconds; allow about a minute of traffic for rate and p95 panels to populate.

Open Grafana and select Dashboards → Oracle AI Database → ORDS observability.

Use the ORDS traces link, or select Tempo in Explore and search:

{ resource.service.name = "ords" }

Open a request to /ords/lab/readings/. Its trace connects the HTTP request with operations beneath it, including connection acquisition, dispatch, and JDBC work against LAB_READINGS_REST.

The ORDS dashboard brings together HTTP request rate and p95 latency, UCP connection usage and pending requests, JVM memory and CPU, and runtime logs.

ORDS metrics come from the Java agent. Database metrics come from the Oracle AI Database Metrics Exporter.

When you’re done with the lab, stop the workload and shut down the containers:

docker compose --profile ords down

References

• ORDS deployment, monitoring, and OpenTelemetry integration.
• OpenTelemetry Java Util Logging instrumentation.
• Lab README.
• Compose configuration.
• REST schema and read-only view.
• ORDS Grafana dashboard.
• Oracle AI Database Metrics Exporter documentation.

A production request slows down. Was it waiting for a connection or executing SQL? Was the database busy, and which logs belong to that request?

Open-source observability tools help connect the evidence across the application and Oracle AI Database. Trace spans capture operation timing, attributes, and errors. Correlated logs add request-specific details, while metrics show how latency, errors, and resource usage changed over time.

We’ll explore these signals with a simple Spring Boot application that queries Oracle AI Database Free through Universal Connection Pool (UCP) and exports telemetry to Grafana LGTM. We’ll follow a request through its JDBC calls and matching logs, then examine pool and database metrics to see what was happening around it.

End-to-end tracing, metrics, and logs

The sample Spring Boot app connects to Oracle AI Database Free, returns its trace ID, and sends telemetry to Grafana LGTM. A separate metrics exporter adds database context. OpenTelemetry is used to push data into Grafana LGTM: Tempo stores traces, Loki stores logs, and Prometheus stores metrics, with Grafana providing the interface for exploring them.

The lab uses Docker Compose for Oracle AI Database Free, Grafana LGTM, the metrics exporter, and an NGINX HTTPS proxy. The Spring Boot application runs on your host through Maven.

From the sample directory, start the infrastructure:

docker compose up -d --wait --wait-timeout 900

Then start the application in another terminal:

mvn spring-boot:run

Call the endpoint:

curl --fail \
  -H 'X-Client-Id: blog-demo' \
  http://localhost:8081/api/readings

For continuous traffic, run:

./workload.sh

The response contains a trace ID and session information observed by the database: module, action, client identifier, and session ID. Use the trace ID to find the request in Tempo and the session fields to identify its database context.

Open Grafana and select Dashboards → Oracle AI Database → Oracle AI Database end-to-end observability. Allow about a minute of traffic for rate and percentile panels to populate.

In Tempo, paste trace IDs to view end-to-end spans on database work: from the HTTP request to the database server.

From the trace in Tempo, follow the link to Loki and find the application log with the same trace ID. The “Read 2 readings…” message belongs to this request, so you can inspect its application context without searching through unrelated messages.

Diagnostic context for database apps

Traces describe a single request, metrics help us understand the state of the system around that request.

The Oracle AI Database Metrics Exporter provides database metrics. In the lab, it collects database metrics every 15 seconds and pushes them to Grafana LGTM over OTLP/gRPC. The dashboard brings database sessions and PDB tablespace utilization alongside application latency, errors, and UCP connection-pool metrics.

If a request is slow, inspect its JDBC spans, then check connection-pool acquisition time, pending requests, and database metrics over the same window. Those trends can reveal pressure that helps explain the request’s timing.

The exporter includes default database metrics and supports custom metrics defined with SQL queries in YAML or TOML. It can expose metrics for Prometheus collection, push them through OTLP/gRPC, or support both paths.

See the exporter documentation for setup and customization, and the OTLP publishing guide for configuration details.

Putting it all together

Observability brings the application and database into the same investigation. You can follow a request through its JDBC calls and database execution, read the logs that belong to it, and check what the connection pool and database were doing at the time. Together, those details help explain where the request spent its time and what might have affected it.

A forthcoming post will explore ORDS metrics, logs, and traces using the same stack. If you want to try it now, enable the optional ords profile in the lab.

References

• Oracle AI Database Metrics Exporter: GitHub repository and documentation.
• Database server-side tracing: Database Observability and OpenTelemetry and the DBMS_OBSERVABILITY reference.
• UCP metrics: Connection-pool runtime statistics.
• UCP Spring Boot integration: Data source configuration and Micrometer metrics.

Lab source code

• Lab README — setup, walkthrough, optional ORDS profile, and troubleshooting.
• Docker Compose stack — infrastructure services and their connections.
• Application configuration — UCP, JDBC observability, and telemetry export.
• Readings controller — SQL execution, request observation, and correlated logging.
• Connection decorator — session identity and JDBC server-telemetry settings.
• Database observability setup — native tracing service and export endpoint.
• Metrics exporter configuration — database connection, collection interval, and OTLP destination.
• Grafana dashboard — application, connection-pool, and database panels.

Publish a message, save it in a relational table, and follow the trace from producer to consumer with Oracle Kafka APIs. In this article, we’ll combine events, transactions, relational data, and OpenTelemetry metrics, logs, and traces with a small Java app and Oracle AI Database Free.

You can run the entire lab on your laptop, provided you have a docker-compatible environment. Oracle AI Database Free is available at no cost under Oracle’s free use terms.

If you’d like to skip the article and jump to the lab, download the lab from GitHub, and give it a star if it was useful!

Oracle Kafka APIs

Oracle’s Kafka Java client, OKafka, uses familiar kafka-clients APIs to create topics, produce events, and consume events. Under the hood, it’s backed by Oracle AI Database Transactional Event Queues (TxEventQ), a high-throughput messaging system built into the database.

The really cool part about TxEventQ is the ability to combine messaging (pub/sub of events) with database transactions. E.g., a producer publishes an event and inserts a SQL row using the same database connection; both commit together.

Why is this useful? When events describe business data, failures must not leave events published while the corresponding SQL change is missing (or vice versa, and corollary to consumers).

Adding Observability with OpenTelemetry

If you’ve ever run a messaging system in production, you know it needs telemetry. We can monitor the database server side easily with the Oracle AI Database Metrics Exporter (which includes a TxEventQ addon), but what about the client side?

OpenTelemetry gives us three ways to see how data flows in the client:

SignalWhat it tells usMetricsHow the clients behave over time: transaction timings, consumer throughput, and more.LogsWhat happened: a reading was published, processed, or included in a batch that committed or rolled back.TracesHow a reading moves from producer to consumer, with related spans and correlated logs.

In the lab, Spring Boot and Micrometer export all three through the OpenTelemetry Protocol (OTLP). Sender and receiver observations let Spring’s tracing handlers propagate context through Kafka record headers.

That said, let’s get started with the lab.

1. Download the sample

To run the sample, you’ll need Java 21, Maven, Git, and a running Docker-compatible environment with Docker Compose.

Download the sample from GitHub. The README contains the configuration reference and additional tests.

git clone https://github.com/anders-swanson/oracle-database-java-samples.git
cd oracle-database-java-samples/oracle-database-kafka-apis

2. Start Oracle AI Database Free and Grafana LGTM

docker compose up -d --wait

Compose starts an Oracle AI Database Free container and Grafana’s LGTM stack, which includes an OpenTelemetry Collector and backends for metrics, logs, and traces.

During startup, a SQL script is automatically run to create the lab user, apply grants, and create tables. First-time startup will include image downloads.

3. Run the Java application

From the same directory, run

mvn spring-boot:run

The application publishes an event every 500 milliseconds and continuously consumes events. Regular readings are inserted into the table; consumption updates their consumed_at timestamps. Occasionally, the producer publishes a failure marker. The consumer rolls back a batch containing that marker once, then processes it again and commits.

Watch for Published, Processed, Rolled back, and Committed messages. A Processed message describes work before the batch commits; the SQL table shows committed results.

4. Explore metrics, logs, and traces

Open Grafana to view the OKafka Metrics Sample dashboard, which shows producer transaction timings, consumer throughput, polling activity, JVM memory, and CPU usage.

Allow about a minute for panels to fully populate with metric data.

Traces can be viewed in the Traces Drilldown. Each traces should propagate from the producer to consumer. You may also view logs in the Logs Drilldown.

You can also check Spring Boot Actuator for health and metrics data:

curl http://localhost:8080/actuator/health
curl http://localhost:8080/actuator/metrics

5. Stop and clean up

When you’re done, stop the Java process with Ctrl+C. Remove the lab containers with docker compose:

docker compose down

Articles and lab overview

• Oracle AI Database Free
• Lab source code
• Lab instructions: OKafka metrics, tracing, and logs
• Lab video
• Authenticate to Oracle AI Database Like It’s a Kafka Cluster
• Pub/Sub in Your DB: Oracle AI Database TxEventQ
• Oracle AI Database Metrics Exporter

Relevant lab files

• MetricsSample.java — transactional producer, consumer, and trace propagation
• MetricsApplication.java — application startup, metric binders, and log export wiring
• MetricsClientConfiguration.java — OKafka producer and consumer configuration
• application.yaml — telemetry endpoints and trace sampling
• docker-compose.yml — Oracle AI Database Free and Grafana LGTM
• init.sql — database user and startup configuration
• Grafana dashboard JSON
• pom.xml — lab dependencies and build configuration

Local endpoints — available while the lab is running

• Grafana
• OKafka Metrics Sample dashboard
• Actuator health
• Actuator metrics

When an agent finishes a task, the next session usually starts from zero. A transcript may exist somewhere, but no useful handoffs, preferences, or decisions make it into persistent, searchable memory.

A transcript records what happened. Durable memory is a smaller, curated set of information selected for a purpose, with a source, an access scope, and rules for correction and deletion. For example, a user-approved decision is likely to be useful in future sessions, while an incidental tool result or sensitive detail probably isn’t.

Memory curation and selection can take time. For agents using Oracle AI Database, OKafka and Transactional Event Queues (TxEventQ) enable asynchronous processing of memory candidates. A worker can extract memory candidates, apply filters and rules, and then store memories for retrieval. The invoking agent is able to respond without waiting for the asynchronous work to finish.

Just looking for code? Check out companion lab on GitHub.

Context, transcripts, and memory are distinct

Agents have a few, general types of state, working context, transcript history, and durable memory.

Three kinds of agent stateCurrent conversation, recorded history, selected knowledge.Working contextBounded chat windowHelps this conversationTranscript historyUser, agent, and toolsAudit and reviewDurable memorySelected factsDecisions and handoffsReusable later

Transcripts are evidence of what the agent did: promoting transcripts to durable memory requires curation, ownership, retention, and governance rules.

For example, append-only conversation logs can be kept separate from curated JSON document memory and associated embeddings. An agent can query durable memory with vector similarity and full-text search, while its write-back tool stores handoffs/decisions as requested.

Add an event path for memory work

Asynchronous, event-driven design moves expensive work away from the main agent. An agent can finish its work while an asynchronous event consumer handles long-running work in the background, complete with retries, idempotency, and callbacks.

A possible event-driven memory flow looks like this:

1. Capture an agent interaction: Create an event for a distinct unit of work, including identifiers like conversation ID, event ID, source transcript, timestamp, and other metadata. Apply access-control or redaction rules before publish.
2. Publish the event: A producer (OKafka) writes the event to a TxEventQ topic, alongside related database operations in the same transaction.
3. Process/extract memory candidates asynchronously: A consumer group reads agent events and applies filtering, extraction, deduplication, and conflict handling. LLMs and other controls can help identify facts, coupled with deterministic scope and policy validation. Depending on the type of processing you use, this step can use one or more consumers, with distributed routing and retries/idempotency.
4. Store memory: Save approved memory documents with their metadata, including embedding and search index updates.
5. Retrieve during a later conversation: Search the memory store using semantic and exact-match signals, apply authorization and scope filters, and return the supporting memory references to the agent.

From event to agent memory01Captureevent + IDpolicy02PublishOKafkaTxEventQ03Curateasync extractvalidate04Storeembed + indexprovenance05Retrievescoped searchreferences

Oracle OKafka allows the event stream and memory data to live in the same database. Each processing stage can commit event consumption, related database writes, and publish of the next event together on the consumer’s database connection. Failed transactions roll everything back back together.

Async fan-out for sub-agents

Event streaming decouples the agent from post-processing: sub-agents can subscribe and process the data while the main agent responds to the caller.

An initial agent can create an artifact (like a transcript record), publish that event to a TxEventQ topic in the database, and have one or more sub-agents asynchronously process the record. For example, sub-agent can be used to asynchronously extract candidates, deduplicate memories, and produce vector embeddings.

Fan out to three sub-agentsSeparate consumer groups, separate tasks.OKafkaProducerTxEventQ topicGroup AAgent: analyzeGroup BAgent: enrichGroup CAgent: notify

Reference Implementations

OKafka Agent Memory

The companion lab implements a simple agent memory flow with Oracle AI Database, OKafka, and OCI Generative AI.

From transcripts to memoryOnly selected facts become reusable memory.TranscriptCaptureCurateExtract · judgeMemoryEmbed · searchOKafka + TxEventQ · Oracle AI Databaseokafka-agent-memory lab

Three event consumers handle transcript intake, memory extraction and admission, and embedding generation. Source transcripts remain separate from selected memories, which can be retrieved through an owner-scoped search API. An accepted transcript can finish without producing any memory.

OKafka Basics

These OKafka code samples cover the building blocks of this architecture, providing building blocks for memory processing:

• The migrate-kafka-to-oracle walkthrough starts with a plain Kafka Java producer and consumer, then switches to OKafka and TxEventQ. Later steps add OSON serialization and database work in the consumer transaction.
• The support-ticket-intelligence sample demonstrates an event-driven enrichment path. It inserts a ticket and publishes a TicketOpened event atomically; a consumer then creates searchable chunks and embeddings. The same event-and-consumer structure could trigger memory extraction after an agent interaction.
• The txeventq-fraud-detection sample shows transactional production of OSON events and a consumer that uses its database connection while scoring and persisting decisions.
• The oracle-database-kafka-apis integration tests exercise topic creation, production, consumption, and transactional producer and consumer behavior with Oracle AI Database Free and Testcontainers.

If you like the samples, star the repository!

When does event-streaming fit agent workflows?

Event-streaming fits agent workloads when follow-up work is required on the generated transcripts, especially when this work is time consuming and requires stateful, durable execution.

For event-driven agent workflows, TxEventQ provides durable streaming: Oracle AI Database persists transcript data, curated memory documents, metadata, and vectors. OKafka gives familiar Java APIs to your agents to publish and consume events in the database, using database transactions.

Async work also means consistency tradeoffs: a background work might finish its work after the next agent begins a new task.

Further reading

Multi-model database and OKafka

• Companion Lab: OKafka Agent Memory
• An app that keeps its data in one place: multi-model database pattern
• No separate database required: real-time, multi-model data processing
• Migrate Apache Kafka applications to Oracle AI Database: Part I
• Pub/Sub in your DB? Oracle AI Database TxEventQ
• Oracle’s OKafka project

Event streaming for agents

• Event-Driven Architecture for AI Agents: Patterns and Benefits — Atlan
• Oracle AI Database for agent memory

This article demonstrates how to run Oracle True Cache locally with docker-compose for testing, local development, and experimentation. We’ll also enable the True Cache Redis API and verify it with redis-cli.

In the compose script, one container serves as the primary database, while the second is the True Cache read-only replica. Both the primary and True Cache databases use the container-registry.oracle.com/database/free:latest image.

If you’d like to skip the article and jump to the code sample, Start Here. If you like the sample, give the repo a star!

Prerequisites

• Docker and Docker Compose.
• Optional: redis-cli to run the separate Redis API test.

Background: Oracle True Cache

Oracle True Cache is a mostly-diskless, in-memory, read-only cache integrated into Oracle AI Database. True Cache is configured to replicate data from a primary database through redo apply.

Note that True Cache is Oracle AI Database, and is not a separate database/caching platform.

Start the Docker environment

Optionally, set an admin password with the ORACLE_PWD environment variable (defaults to Welcome12345), and then run the compose script:

export ORACLE_PWD='<local-admin-password>'
docker compose up -d

You should see the containers start up like so:

Wait for oracle-free and true-cache containers to become healthy, and for true-cache-configure to exit successfully. That one-shot service registers FREEPDB1_TC on the primary, creates the TRUE_CACHE_DEMO user and demo schema objects there, then configures a TCPS endpoint and Redis dispatcher on True Cache.

On startup, a demo user is created in the FREEPDB1 database with ORACLE_PWD as its password. The exposed database ports are:

• Primary: localhost:1522/FREEPDB1
• True Cache: localhost:1523/FREEPDB1_TC
• True Cache Redis API: 127.0.0.1:6379 (TLS, local certificate)

Verify True Cache replication

How True Cache stays currentWrites land on the primary. The cache serves reads.WRITEredo applyREADOracle AI DatabaseTrue CacheIn-memory replica · read-only

Once true-cache is healthy and true-cache-configure has completed, run the test-true-cache.sh script:

./test-true-cache.sh

The script adds two records in the primary database, and waits until True Cache replicates the data.

The data is then updated in the primary database, and True Cache is read again to verify the update.

Verify the Redis API

On container startup, the True Cache Redis API is enabled over port 6379, served over TLS with a self-signed certificate. This is a read-only, wire-compatible API for Redis clients to read data from True Cache as if it were a Redis server.

Read from True Cache with redis-cliredo applyread requestresultOracle AIDatabase> redis-cliread clientTrue CacheRedis protocol over TCPS · localhost:6379

The test-redis-cli.sh script verifies the Redis API against the container setup:

./test-redis-cli.sh

It checks for redis-cli before doing any database work, runs the SQL insert, read, update, read test with two new inventory lots, then authenticates over TLS and uses HGET to check both final stock counts through True Cache. It prints the Redis results as a table and exits with an error if the counts do not match.

Run redis-cli directly against the database schema

A simple coffee inventory is created on startup, and populated with data by the test scripts. We can directly connect redis-cli to the True Cache endpoint and query this data.

ColumnTypePurposelot_idNUMBERAutomatically generated primary key for a coffee lotcoffee_nameVARCHAR2(100)Coffee varietybags_in_stockNUMBER(6)Available bags, never negativeroasted_onDATERoast date, defaulting to today

Read lot ID 1 with HGET:

REDISCLI_AUTH="$ORACLE_PWD" redis-cli --tls --insecure \
  -h 127.0.0.1 -p 6379 --user TRUE_CACHE_DEMO \
  HGET "true_cache_demo.coffee_inventory:lot_id=1" bags_in_stock

Note that the Redis API is read-only. Writes must still be made to the primary database; writes made with a Redis client will fail.

Stop the environment

When you’re done, tear down the docker compose environment:

docker compose down

The databases use container-local storage and are removed with their containers.

Optional: Detailed Redis API Configuration

The true-cache-configure service creates a local self-signed TCPS certificate and adds a PRE=REDIS dispatcher for the FREEPDB1 PDB service on port 6379. The helper also sets SHARED_SERVERS=1, which is required for the dispatcher to accept Redis connections.

The SQL client still uses the FREEPDB1_TC True Cache service. Oracle True Cache authenticates Redis connections as a database user and looks up rows with SQL keys. It does not provide a general Redis key-value store. Commands such as HGET and GET read database rows, while Redis write commands do not update the database. See Oracle’s True Cache Redis Server guide for supported commands and key syntax.

The helper runs read-only bind-mounted SQL*Plus scripts after True Cache starts: primary demo schema setup and cache Redis dispatcher setup.

Oracle Redis Server also works on an Oracle Active Data Guard standby, where it serves read-only standby data while redo apply runs. This is supported starting with Oracle AI Database 26ai Release Update 23.26.3; see Oracle’s Active Data Guard Redis Server documentation.

The Redis test script uses redis-cli --tls --insecure because the local endpoint uses the self-signed certificate. Do not use --insecure for a remotely exposed endpoint.

References

More about True Cache

• For more information on how True Cache works for database read paths, see True Cache: in-memory reads for Oracle AI Database.
• For Java integration tests, Spring Cloud Oracle provides TrueCacheContainer Testcontainers support for starting a primary and True Cache on a shared Testcontainers network.

Files

• Compose configuration
• Primary password-file startup script
• Primary demo schema setup script
• True Cache Redis dispatcher script
• Primary-to-cache test script
• Redis API test script

UCP metrics are database-client metrics from Oracle UCP (Universal Connection Pool), Oracle’s JDBC connection pool. Like HikariCP, UCP exposes pool-specific metrics: current and maximum connections, callers waiting for a connection, acquisition time, and pool lifecycle activity.

These metrics help separate a slow query from a slow path to a query. When an application exhausts its pool, waits to acquire connections, or accumulates latency before calls reach Oracle AI Database, UCP metrics show where to investigate.

Configure and use UCP metrics

To start collecting metrics, add the oracle-spring-boot-ucp-micrometer dependency to your project. spring-boot-starter-actuator should be included to manage and scrape metrics:

<dependency>
  <groupId>cm.oracle.database.spring</groupId>
  <artifactId>oracle-spring-boot-ucp-micrometer</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Then, configure your project to export metrics via application properties. For Spring Actuator expose the /actuator/metrics endpoint:

management:
  endpoints:
    web:
      exposure:
        include: metrics

For push-based collection, configure Spring Boot’s OTLP metrics exporter:

management:
  otlp:
    metrics:
      export:
        enabled: true
        url: http://your-otel-endpoint:4318/v1/metrics
        step: 5s

Try it out with our UCP Spring Boot sample

If you’d like to experiment with metrics using Oracle AI Database Free, I built an all-in-one Docker Compose sample that spins up Oracle AI Database, a Spring Boot app, and Grafana LGTM for testing.

To test the sample, check out the code here and run:

export ORACLE_PWD="${ORACLE_PWD:-Welcome12345}"
docker compose up --build -d

Then, check out the Grafana dashboard at http://localhost:3000.

A sample load-generator script is provided to utilize the connection pool.

Sample Grafana Dashboard

To help you visualize statistics from UCP, I built a sample Grafana dashboard that uses these metrics. You can adopt this dashboard out of the box, or use it as a starting point for customization.

The dashboard includes information about the selected connection pool, like active connections, utilization rate, latency:

What kind of UCP metrics are collected?

OpenTelemetry database client metrics are exposed under the db.client namespace with the db.client.connection.pool.name attribute set to the configured spring.datasource.oracleucp.connection-pool-name. Otherwise, he Spring DataSource bean name is used as the pool name.

The module also includes UCP-specific metrics under the ucp.connections namespace, which describe the connection pool in detail.

References

• Check out the UCP metrics documentation for metric reference and setup details.
• See How to tune Oracle UCP for details on tuning UCP in Spring Boot applications.
• For more practical work on Oracle AI Database telemetry, browse my other observability posts.

Before you can finish evaluating a library or framework, an AI coding assistant can reinvent a custom implementation for you.

In the moment, that can be astonishingly productive.

LLMs are exceptional at reproducing prior art, which creates a tendency to favor bespoke software. Generating a new tool can feel faster than understanding, adopting, and configuring an existing one.

This is a version of the greenfield trap: Starting with a clean slate is psychologically and structurally satisfying. Reinventing feels clean because constraints are hidden.

The economics of creating software changed

Software used to be incredibly expensive to create.

Even small software components required engineering time for design, programming, catching edge cases, testing, and documentation. The high cost of software drove developers to use existing libraries or frameworks whenever possible.

When you use an agent harness for coding, really anyone, including non-developers, can create a custom cache, scheduler, auth wrapper, or deployment script, in minutes. It may even work as intended in the first draft.

So Generative AI has reduced the cost of generating code.

But what about the cost of owning software?

Ownership means comprehension: is the implementation understood? Are real failure paths tested? Is production behavior adequately monitored? Are vulnerabilities patched, users supported, upgrades implemented, and future migrations considered?

From experience, ownership isn’t as exciting as creating. Ownership introduces a sort of drudgery: fickle users, tricky bugs, and a never-ending parade of CVEs to patch, test, and validate.

Fast output vs. slow work

With a decent agent harness and model, you can crank out code at a volume that wouldn’t otherwise be possible.

So Generative AI makes coding progress visible very quickly. The crux is that perceived speed isn’t sufficient evidence of delivered value. METR’s randomized study found that experienced developers took longer on real tasks, despite believing they were faster.

It’s true that most established software components are reproducible by coding tools, as we’ve seen with the “rewrote project X in Y days” flavor of AI coding announcements.

But, the value of established software often comes from the years of testing, battle scars, and accumulated community trust.

Thus, the hidden work is:

• Which assumptions did the generated implementation make?
• What happens under concurrency or partial failure?
• Were architecture decisions copied from outdated examples?
• Who will understand the code six months from now? Will anyone need to?
• Who owns the next version, patching, and software lifecycle?

Technical debt and reinvention

Custom implementations will have fewer users, fewer deployments, and less accumulated knowledge. This doesn’t mean custom implementations aren’t useful; they definitely are. It means custom implementations require their own validation, which must be owned by creators. Reuse is associated with less maintenance effort.

ownership debt

As with any project, someone must maintain it: someone who can explain the behavior, patch vulnerabilities, and respond to change requests. This includes practices like tracking security requirements, design decisions, supply chain/BOM verification, and so forth. If you don’t accept this debt, your project is likely to face severe security challenges and much more painful debugging.

organizational fragmentation

If you give five teams a similar problem, you’ll likely get five generated wrappers, clients, validation frameworks, and deployment tools. This is inexpensive at the beginning, but complex in the long tail: You get duplicated documentation, inconsistent behavior, and repeated security vulnerabilities.

Adopt, adapt, invent

Before jumping to AI generation, consider your options.

Adopt

Existing tools/components are great. Use them when you can. However, remember that dependencies bring their own risks:

• abandoned maintainers;
• vulnerable transitive dependencies;
• incompatible licenses;
• oversized APIs;
• poor operational behavior;
• upgrade pressure;

Adapt or Contribute

Small adapters can extend existing components: something like a custom plugin or integration. If you have a need that isn’t represented in an open-source project, consider contributing back (but only after testing, vetting, understanding your change).

Invent

If you have domain-specific needs, build something new. Existing tools may either not meet your constraints, or the need is important enough to justify long-term ownership.

Notice that “AI can generate it” is not one of those reasons. AI tools are excellent at helping you discover, evaluate, and use existing tools. However, sometimes they introduce their own biases: For example, I wouldn’t ask Claude for opinions on competing products.

Final Thoughts

Implementation is both easy and abundant, which changes the calculus of assessing engineering effort.

Judgement becomes more valuable, changing the question from “Can we build this?” to “Should we build this?”

Strong teams will use generation selectively, and retain judgement on reuse, standards, and ownership. Knowing both what not to build and what efficient design looks like is still valuable.

Oracle True Cache is a mostly diskless, read-only cache and replica that stays synchronized through redo apply: Only frequently accessed blocks reside in memory. With True Cache, read-heavy queries can be offloaded to the cache replica, improving performance on the primary.

The cache keeps the same client, database model, and SQL interface as your primary database, allowing you to serve cache-friendly reads without another system or translating cache-specific objects.

In this article, we’ll explore how True Cache works, then describe how to test it with Oracle AI Database Free and Testcontainers.

True Cache is Oracle AI Database

External caches generally developers to serialize or map database data into a separate representation..True Cache isn’t limited by external semantics, instead acting as a read-only replica of the primary database. It caches Oracle AI Database objects and data types, and applies the same database security policies.

If your application already has a relational model, SQL queries, constraints, joins, JSON, or other Oracle data types — you can add an in-memory read path without changing the way data is accessed. There’s no cache-specific object shape or serialization layer. the same SQL can run unchanged on in-memory replica.

I’ve written a True Cache integration test that demonstrates this: It creates a table with a NUMBER key and a VARCHAR2 column on the primary, inserts a row, and later runs a normal SQL SELECT against the cache to retrieve the data.

Both the primary database and replica database clients use the Oracle JDBC driver (ojdbc17). The application still decides primary or cache endpoint, but doesn’t need a secondary database client or platform to read cached data.

Mostly diskless, in-memory caching

True Cache satisfies queries from its buffer cache — a small amount of storage is required for standby redo log files, config files, and temp files. It’s a smaller persistent storage footprint than a full database replica.

The cache starts empty. On a miss, it fetches data from the primary, and it can read larger chunks while warming up. Once a block is cached, changes are applied through redo from the primary database. The frequently read part of the database ends up in memory without the application copying rows into a second schema or cache format.

The primary must run in ARCHIVELOG mode so redo can be shipped to the True Cache node. That prerequisite shows up directly in the test setup:

private static final OracleContainer PRIMARY = new OracleContainer(OracleContainer.IMAGE_NAME + ":latest")
        .withNetwork(NETWORK)
        .withNetworkAliases(PRIMARY_ALIAS)
        .withOracleSecrets(SECRETS)
        .withArchiveLog(true)
        .withForceLogging(true);

Cache freshness

With True Cache, applications must still write to the primary database.

True Cache uses “redo apply” from the primary database, and then serves that data from memory. This is very high throughput, but If read-after-write consistency is required, I recommend reading from the primary.

I would use True Cache when:

• the workload has many more reads than writes;
• the read path can tolerate a very small amount of redo-apply lag
• the application benefits from keeping its Oracle SQL and data types instead of maintaining a second cache representation.

Semantically, this is really no different than another read-cache. I just want to spell this out here to be clear about redo apply.

One client doesn’t mean one endpoint

The True Cache application model includes two physical connections: a connection to the primary and a connection to True Cache. The application must choose its connection based on whether the operation needs to write new data, requires the latest data, or if it can use a cached read. This model is compatible with existing client drivers and programming languages.

For something like a Spring application, that could mean two DataSource instances, two JdbcClient instances, or a routing layer that selects the right one for each operation.

Oracle 26ai also supports one logical JDBC Thin connection that routes based on read-only state, plus OCI session-pool integration (Oracle connection methods). With JDBC, you can configure this with oracle.jdbc.useTrueCacheDriverConnection=true and Connection.setReadOnly(boolean).

Try it out with Testcontainers

TrueCacheContainer.java joins primary and cache database containers with a shared network in TrueCacheContainerIntegrationTest.java:

1. The primary and cache are started on the same Testcontainers Network.
2. The cache uses the primary’s connection string
3. Tell the cache which Pluggable Database (PDB) service maps to which True Cache service.
4. Give the cache the primary password file it needs during startup.

The integration test wires those pieces together like this:

private
 static final Network NETWORK = Network.newNetwork();
private static final OracleContainerSecrets SECRETS = 
OracleContainerSecrets.withOraclePassword(OracleContainer.DEFAULT_PASSWORD);

private static final OracleContainer PRIMARY = new 
OracleContainer(OracleContainer.IMAGE_NAME + ":latest")
        .withStartupTimeout(Duration.ofMinutes(5))
        .withNetwork(NETWORK)
        .withNetworkAliases(PRIMARY_ALIAS)
        .withOracleSecrets(SECRETS)
        .withArchiveLog(true)
        .withForceLogging(true);
private static final TrueCacheContainer CACHE = new TrueCacheContainer()
        .withNetwork(NETWORK)
        .withNetworkAliases(CACHE_ALIAS)
        .withOracleSecrets(SECRETS)
        .withPrimaryDatabase(PRIMARY_ALIAS, OracleContainer.ORACLE_PORT,
 "FREE")
        .withPdbService("FREEPDB1", "FREEPDB1", "FREEPDB1_TC");

The cache endpoint has to exist before the primary can advertise the corresponding service, and service registration changes the primary’s state, so the wrapper leaves it to the test or application owner.

The test waits for a row to arrive

Once both containers are running, the test confirms if a row committed to the primary can be read through the cache:

try (Connection primaryConnection = PRIMARY.createConnection("");
     Statement statement = primaryConnection.createStatement()) {
    primaryConnection.setAutoCommit(false);
    statement.execute("CREATE TABLE true_cache_test (id NUMBER PRIMARY KEY, name VARCHAR2(30))");
    statement.execute("INSERT INTO true_cache_test VALUES (1, 'Ada')");
    primaryConnection.commit();
}

assertTrue(awaitCachedRow(), "Expected True Cache to apply the committed primary row");

awaitCachedRow() opens a connection to the cache and retries the query for up to two minutes. It catches SQL exceptions while the service is being created and redo is being applied, then waits one second before trying again.

The test passes only after the committed row became visible through the True Cache service.

References

• configuration details: True Cache Testcontainers documentation
• True Cache overview
• Methods for connecting to True Cache
• True Cache prerequisites
• Oracle True Cache FAQ

If you’ve built software for a while, you’ve probably seen a similar architecture diagram: database for transactions/relational data, Redis for caching, Kafka for events, OpenSearch for full-text and keyword search, object storage as a data lake, and maybe a vector database for AI integration.

There’s nothing wrong with these choices: each technology is good at its job. For example, you’ll find countless articles, papers, and engineering blogs extolling the virtues of Apache Kafka for asynchronous, service-to-service messaging.

But how much is it going to cost to run and maintain all of this? Before on-boarding new component, ask yourself if the problem can be solved using existing platform capabilities. Simple is good. Boring is good.

We optimize whiteboard architecture instead of the business system

Imagine building an activity feed for a SaaS app: on the feed, users generate events, we store activities somewhere, and retrieves the right ones for each user. It also must scale as users and events grow.

During design discussions, the activity feed system might begin with a few core components:

• A RDBMS for relational records like users, preferences, activities
• A message broker like Kafka to decouple application generated events from the service that builds activity feed
• A cache like Redis to store frequently accessed feed items
• A search engine like OpenSearch to index activity records for fast search and filtering

How much does the system cost to operate?

Not just how much the infra/cloud licensing costs, but how much it costs the engineering organization to understand, test, maintain, monitor, secure, upgrade, and troubleshoot the system.

Every component in a software system comes with this baggage. It creates operational work, consumes organization attention, and distracts engineers from building competitive, differentiating product features. Even for managed services, these costs don’t disappear (though they may be somewhat reduced).

This is particularly relevant for software businesses: architecture decisions eventually determine COGS (Cost of Goods Sold, essentially the metric of how much it costs to maintain and sell the software).

However, COGS is usually absent from architecture discussions. Whiteboard conversations focus on throughput, latency, scalability, and load projections. Costs and operational overhead become much clearer later.

At the extreme, I’ve seen systems where adding a new user actually costs more than the revenue that user generates.

Complexity compounds over time

An initial architecture can be perfectly manageable. But successful products evolve, new features are brought in, and new components are added to the stack.

In isolation, each decision may be technically sound, but the system may still be expensive and optimize the wrong things. A small engineering team can effectively operate one database platform, but it’s significantly more difficult to build expertise in separate caching, event streaming, text search, and vector database systems.

At some point, infrastructure, operations, and maintenance can become the engineering group’s main source of work. A system that requires complex infrastructure, significantly more operational staff, and a wide collection of specialized technologies may not have scaled economically.

The database can be more than a database

To avoid the complexity of gluing together independent products, we can look toward modern, multi-model databases like Oracle AI Database or PostgreSQL.

Instead of stitching together independent products, the platform provides integrated capabilities:

• relational data
• JSON/document storage
• graph
• spatial
• vector search
• analytics
• AI capabilities
• transaction processing

Take our activity feed, for example: each separate component could be mapped to in-database features:

And so forth. Most, if not all capabilities can be operated on a single database these days. This doesn’t mean you have to build everything on the same database, but it can be a dramatic simplification.

A note on testing

As the number of moving parts grows, it’s more and more difficult to effectively test the system without a fully deployed stack. I’ve written a lot of tests for these kinds of systems, and full-blown integration tests are challenging to build.

Interestingly, an integrated data platform like a multi-model database is often easier to test.

When I write an integration test, I don’t need to spin up and glue together a complex stack. I can create one (1) database container, run my schema setup, and connect my applications using the provided connection string. This makes integration tests simple and reproducible, with startup times measured in seconds.

This even allows complete local testing with frameworks like Testcontainers and Oracle AI Database Free containers. I have dozens of examples doing exactly this with various (and combined) database features here.

References

• Polyglot, multi-model database code samples
• Integration testing multi-model database applications with Testcontainers
• Sample multi-model database app combining event streaming, relational database, vector database, and spatial data on a single engine.