mk-oracle: document 12.1.0.2 as the minimum supported release

The README named no minimum release at all. It now names 12.1.0.2 and says
what an older database gets instead of monitoring. The test-fleet
documentation listed the Oracle XE 11 image alongside the supported targets,
and now marks that image as below the minimum.

- The README gains a Supported Oracle Releases section. It names the columns
  the queries depend on and the release each one arrived in, and it states
  that an older instance fails with ORA-00904 while its version is being
  established, and reports that error in the oracle_instance section.
- The custom-SQL example in the README gated a variant at 12.1.0.0, which is
  below the minimum. The example now uses 19 and 23.
- The Docker README and tests/docs/test-systems.md mark the XE 11 image as
  below the minimum, and note that it is only good for checking that the
  plug-in fails cleanly.
- test-db-endpoints.conf records that a database below the minimum is not a
  valid target for the test suite.

TESTS: None, documentation only.

CMK-37731

Change-Id: I9283cc1d4f09565156c245d2f251c745395ee7c2

Author: andiumbreit

packages/mk-oracle/README.md

@@ -2,6 +2,7 @@
 
 ## Table of Contents
 
+- [Supported Oracle Releases](#supported-oracle-releases)
 - [Oracle Instant Client Download and Installation](#oracle-instant-client-download-and-installation)
   - [Linux](#linux)
   - [Windows](#windows)
@@ -29,6 +30,16 @@
   - [What Is Not Migrated](#what-is-not-migrated)
   - [Adapting Custom SQL Files](#adapting-custom-sql-files)
 
+## Supported Oracle Releases
+
+The minimum supported release is **Oracle 12.1.0.2**.
+
+Older releases are not supported and are not accommodated. The queries name
+`V$DATABASE.CDB` and `V$INSTANCE.CON_ID`, which arrived with 12.1, and
+`V$PDBS.RECOVERY_STATUS`, which arrived with 12.1.0.2. An older instance
+therefore fails with `ORA-00904` while its version is being established, and
+reports that error in the `oracle_instance` section instead of being monitored.
+
 ## Oracle Instant Client Download and Installation
 
 The plugin requires Oracle Instant Client libraries to connect to Oracle databases.
@@ -577,16 +588,16 @@ Resolution rules:
 
 - **Absolute vs. relative.** Absolute paths are used as-is. Relative paths are searched first in **`MK_LIBDIR/plugins/packages/mk-oracle/orasql/`** and then in **`MK_CONFDIR/orasql/`**. When the same relative path resolves in both, the **`MK_LIBDIR/plugins/packages/mk-oracle/orasql/`** copy wins.
 - **File vs. directory.** A `path:` may point at a file (with or without the `.sql` extension) or at a directory. In the directory case the file name is derived from the **item name** for `custom_metrics`, or from the **section name** for predefined `sections`.
-- **Version variants.** Alongside the base `<stem>.sql`, you may provide Oracle-version-specific variants named `<stem>@<min_version>.sql` (e.g. `sessions@12010000.sql`). The plugin picks the file with the highest `min_version` that is still less than or equal to the connected instance's version. The version is the 8-digit numeric form `MMmmRRSSSS` (major / minor / release / patch), e.g. `12.1.0.2` → `12010002`.
+- **Version variants.** Alongside the base `<stem>.sql`, you may provide Oracle-version-specific variants named `<stem>@<min_version>.sql` (e.g. `sessions@19000000.sql`). The plugin picks the file with the highest `min_version` that is still less than or equal to the connected instance's version. The version is the 8-digit numeric form `MMmmRRSSSS` (major / minor / release / patch), e.g. `12.1.0.2` → `12010002`.
 - **Fallback chain.** Resolution order for a section is: `path:` → inline `sql:` → bundled (for predefined sections only). If `path:` is set but no file matches the instance version and no inline `sql:` is provided, the section yields no output.
 
 Example layout on Linux:
 
 ```
 $MK_CONFDIR/orasql/
 ├── product_price.sql
-├── product_price@12010000.sql       # picked for Oracle >= 12.1.0.0
-└── product_price@19000000.sql       # picked for Oracle >= 19.0.0.0
+├── product_price@19000000.sql       # picked for Oracle >= 19.0.0.0
+└── product_price@23000000.sql       # picked for Oracle >= 23.0.0.0
 
 $MK_LIBDIR/plugins/packages/mk-oracle/orasql/
 └── product_price.sql                    # overrides the MK_CONFDIR copy

packages/mk-oracle/test-db-endpoints.conf

@@ -18,7 +18,9 @@
 # 2026-07-09: the plugin's output against a 19c non-CDB instance is
 # correct). Use deploy-run for manual plugin testing against such
 # databases; making them supported suite targets means making those
-# assertions architecture-aware first (CMK-36706).
+# assertions architecture-aware first (CMK-36706). A database below the
+# supported minimum of 12.1.0.2 is not a valid target at all: the plug-in
+# fails against it by design.
 
 # --- ci: the CI database (Jenkins secret CI_ORA_TEST_PASSWORD)
 ci_host=oracle-rocky-ci.lan.checkmk.net

packages/mk-oracle/tests/docs/test-systems.md

@@ -114,8 +114,8 @@ flowchart LR
   and the legacy-vs-new comparison harness.
 - **Local developer databases**:
   [`../files/docker/run-db.sh`](../files/docker/run-db.sh) starts a local
-  Oracle container (versions 23 / 19 / 12 / 11) for ad-hoc development runs —
-  not used by CI.
+  Oracle container (versions 23 / 19 / 12, and 11 which is below the supported
+  minimum of 12.1.0.2) for ad-hoc development runs — not used by CI.
 - **Perf tier** ([`../perf/`](../perf)): `docker-compose.yml` with
   `gvenzl/oracle-free:23.26.0` for the semi-automated performance comparison
   (Rust vs legacy plugin) — run locally, no CI job.

packages/mk-oracle/tests/files/docker/README.md

@@ -18,7 +18,9 @@ Before you start, make sure you have the following installed:
 This `docker-compose.yml` file defines several Oracle database services. You should only run **one at a time** since they are configured to use the same host port (`1521`) by default.
 
 - `oracle-free` (Version 23): Runs the **Oracle Database Free** edition.
-- `oracle-xe` (Version 11): Runs the **Oracle Database Express Edition (XE)**.
+- `oracle-xe` (Version 11): Runs the **Oracle Database Express Edition (XE)**. Below the
+  supported minimum of 12.1.0.2, so the plug-in only fails against it; useful for
+  checking that it fails cleanly, not for monitoring.
 - `oracle-12c` (Version 12): Runs **Oracle Database 12c**.
 - `oracle-19c` (Version 19): Runs **Oracle Database 19c**.
 
@@ -37,7 +39,7 @@ You can easily start any of the supported database versions using the `run-db.sh
 ### Options
 
 - `-v, --version`: **Required**. The Oracle version to run.
-  - Available versions: `23`, `11`, `12`, `19`.
+  - Available versions: `23`, `19`, `12`, and `11` (below the supported minimum).
 - `-P, --port`: **Optional**. The host port to bind the database listener to.
   - Default: `1521`.