Oracle Database Version Matrix

The Oracle Database sink is a first-party production sink. Its compatibility evidence is managed through a local, opt-in version matrix rather than routine GitHub Actions. The matrix is designed for release preparation and local certification work where a maintainer has already arranged Docker resources, Oracle image access, registry or license setup, and any internal mirror policy.

The matrix preserves the normal nats-sinks delivery boundary: at-least-once delivery, durable Oracle commit first, JetStream ACK last. A version check must never weaken idempotency, retry, DLQ, or disconnected replay behavior to make a database version pass.

Inventory Model

The default inventory lives in examples/oracle-database-version-matrix/matrix.json. It separates:

• prebuilt Oracle Database Free images from Oracle Container Registry;
• Oracle Autonomous Database Free Container Image variants;
• locally buildable Oracle docker-images SingleInstance versions;
• historical or gated versions that require operator-provided image material, license acceptance, or internal mirroring;
• entries that are documented but not directly executable by the single-instance runner.

The initial inventory evaluates these Oracle Database families:

Matrix entry	Version family	Source path	Default status
oracle-xe-11g-r2	Oracle Database 11g Release 2 XE	Oracle docker-images SingleInstance	requires_manual_image_build
oracle-12c-r1	Oracle Database 12c Release 1	Oracle docker-images SingleInstance	requires_manual_image_build
oracle-12c-r2	Oracle Database 12c Release 2	Oracle docker-images SingleInstance	requires_manual_image_build
oracle-18c-xe	Oracle Database 18c XE	Oracle docker-images SingleInstance	requires_manual_image_build
oracle-19c	Oracle Database 19c	Oracle docker-images SingleInstance	requires_manual_image_build
oracle-21c-xe	Oracle Database 21c XE	Oracle docker-images SingleInstance	requires_manual_image_build
oracle-free-23ai	Oracle Database Free 23ai / 23c-era images	Oracle Container Registry Database Free	requires_registry_license_setup
oracle-free-26ai	Oracle Database Free 26ai	Oracle Container Registry Database Free	requires_registry_license_setup
adb-free-19c	Autonomous Database Free 19c	Autonomous Database Free Container Image	requires_registry_license_setup
adb-free-23ai	Autonomous Database Free 23ai	Autonomous Database Free Container Image	requires_registry_license_setup
adb-free-26ai	Autonomous Database Free 26ai	Autonomous Database Free Container Image	requires_registry_license_setup

Public source references used for this inventory are Oracle Container Registry Database Free, Oracle Autonomous Database Free Container Image, and the Oracle docker-images SingleInstance repository. The repository does not commit Oracle binaries, pulled image layers, generated database files, wallets, or private registry names.

Running The Matrix

List the known entries:

python scripts/run-oracle-db-version-matrix.py --list

Perform a dry run for one entry with an explicit image reference:

python scripts/run-oracle-db-version-matrix.py \
  --include oracle-free-26ai \
  --image-ref oracle-free-26ai=container-registry.oracle.com/database/free:EXPLICIT_TAG \
  --dry-run

Run a live single-instance entry when the image is already present locally:

python scripts/run-oracle-db-version-matrix.py \
  --include oracle-free-26ai \
  --image-ref oracle-free-26ai=registry.example.invalid/oracle/database-free:26.1.0

Allow the runner to pull the selected image:

python scripts/run-oracle-db-version-matrix.py \
  --include oracle-free-26ai \
  --image-ref oracle-free-26ai=registry.example.invalid/oracle/database-free:26.1.0 \
  --allow-pull

Run disconnected replay as part of the selected version check:

python scripts/run-oracle-db-version-matrix.py \
  --include oracle-free-26ai \
  --image-ref oracle-free-26ai=registry.example.invalid/oracle/database-free:26.1.0 \
  --with-disconnected-replay

The runner writes sanitized evidence to .local/oracle-db-version-matrix/oracle-db-version-matrix-report.json by default. That path is ignored by Git. The report includes matrix IDs, source types, support statuses, and high-level test outcomes. It does not include passwords, full connection strings, container names, container IDs, local image layers, host-specific paths, raw Docker logs, payloads, or private endpoints.

What The Live Runner Does

For single-instance Oracle Database entries, the runner:

1. validates the selected matrix entry and explicit image reference;
2. chooses a random loopback port;
3. generates a local-only Oracle password;
4. starts one short-lived Oracle Database container;
5. waits for a configured readiness phrase in Docker logs;
6. creates a generated runtime user with the permissions needed for local certification where the selected image supports that bootstrap path;
7. runs python -m pytest -q -m integration tests/integration/test_oracle_sink.py as that generated runtime user;
8. sets a fresh test table name and drop-before/drop-after flags;
9. optionally enables disconnected replay certification;
10. removes the container by default.

The runner refuses implicit or latest image tags. Use explicit tags or digests so the evidence can be repeated later.

Status Values

Matrix evidence uses these status values:

Status	Meaning
tested	The selected container started and Oracle sink certification passed.
test_failed	The selected container started, but certification failed. Raise a managed bug before fixing code.
dry_run	The selected plan was validated without starting Docker.
requires_image_ref	The inventory entry needs a concrete image reference from the operator.
requires_manual_config	The entry is documented but not executable by the single-instance runner.
image_not_present	The image is absent locally and --allow-pull was not selected.
image_pull_failed	Docker could not pull the selected image.
container_start_failed	Docker did not start the selected container.
readiness_timeout	The container did not report readiness before the bounded timeout.
runtime_user_bootstrap_failed	The runner could not create the generated least-privilege test user.

Autonomous Database Free Boundary

Autonomous Database Free Container Image entries are documented in the matrix because they are relevant for Oracle sink compatibility discussions. They are not currently executed by the single-instance runner because they require additional operator setup and a different readiness and connection profile. Add a narrower issue before turning those entries into live matrix steps.

Support Statement

The matrix records evidence. It is not a blanket Oracle support promise. README and Oracle sink documentation should describe Oracle Database support in terms of tested versions, expected compatibility, known limitations, and documented exclusions.

When a matrix run exposes a reproducible compatibility defect, create a managed GitHub bug, add the smallest failing regression test first, fix the defect, and attach sanitized matrix evidence to the issue.