2026-08-26 · run 2026-08-26-oracle-migration

Oracle: driver install + migration, the third engine

Summary

Oracle is the third non-Postgres engine. Keycloak does not ship the Oracle JDBC driver (licence), so this run is also the driver-install deliverable. Two results:

1. Keycloak runs and migrates on Oracle. With ojdbc17 + orai18n (Maven Central 23.26.0.0.0) dropped into the base file's providers bind-mount — no custom image needed — Keycloak 26.0.0 starts against Oracle Database Free, creates 87 tables, and the 26.0.0 → 26.7.1 migration reaches migration_model 26.7.1 cleanly.

2. The Oracle Free image self-identifies as "26ai". gvenzl/oracle-free:23-slim reports Oracle AI Database 26ai Free Release 23.26.2.0.0 — Oracle renamed 23ai → 26ai in 2026. Keycloak's documented support is "23.x (23.5+)", and this release reports a 23.x version string, so it is within the supported line, but the rename is worth flagging in the runbook's pre-flight (a customer on "26ai" is on the 23.x line Keycloak supports).

Environment

Procedure

# drivers (Keycloak server/db docs "Installing the Oracle Database driver")
curl -o fixtures/providers/ojdbc17.jar https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc17/23.26.0.0.0/ojdbc17-23.26.0.0.0.jar
curl -o fixtures/providers/orai18n.jar https://repo1.maven.org/maven2/com/oracle/database/nls/orai18n/23.26.0.0.0/orai18n-23.26.0.0.0.jar

# .env: KC_DB=oracle, COMPOSE_FILE=docker-compose.yml:docker-compose.oracle.yml
docker compose up -d db        # Oracle Free first init ~11 min
docker compose up -d keycloak  # 26.0.0
docker compose stop keycloak && sed -i 's/^KC_VERSION=.*/KC_VERSION=26.7.1/' .env
docker compose up -d keycloak  # migrate

Results

Verification