Initial Oracle Support on Explain feature

Introduce comprehensive support for Oracle Database to the SQL Explain
panel in django-debug-toolbar. Unlike databases that support single-step
integrated query analysis (such as PostgreSQL's "EXPLAIN ANALYZE"),
Oracle requires a multi-step orchestration workflow to execute an
explain plan and format its output securely without session pollution.

Key Implementations & Changes:

1. Core Oracle Explain Orchestration:
   - Implement `OracleExplainPlanHelper` to encapsulate the multi-step
     explain plan lifecycle.
   - Generate temporary execution nodes under a session-safe, unique
     `STATEMENT_ID` (`dt_<uuid>`) within the session's `PLAN_TABLE`.
   - Query `DBMS_XPLAN.DISPLAY` with `ADVANCED +ADAPTIVE` flags to
     retrieve structured, human-readable execution plans.
   - Clean up temporary rows from `PLAN_TABLE` at the end of execution.
   - Suppress Query Block Registry (QBR) XML output on legacy Oracle
     connections (< 21) to prevent memory exhaustion and infinite
     recursion bugs on terminal client markdown parsers.
   - Include a graceful schema health audit fallback that queries
     `ALL_TABLES` and `ALL_INDEXES` metadata to format and append table
     and index statistics (sizes, status, performance counters) as
     aligned ASCII tables, sanitizing permission/database errors.

2. Query Tracking and Integration:
   - Update `debug_toolbar/panels/sql/forms.py` to hook `SQLSelectForm`
     and delegate select-explain execution to the new Oracle helper
     when connected to an Oracle database.
   - Update `debug_toolbar/panels/sql/tracking.py` to escape and filter
     out toolbar queries using vendor-specific quoting (`quote_name`)
     to prevent the toolbar's internal queries from showing up in and
     polluting SQL panels.

3. Docker & Infrastructure Support:
   - Introduce `docker-compose.yml` to provision local PostgreSQL,
     MariaDB, and Oracle Database Free containers to facilitate
     comprehensive multi-backend integration testing.
   - Update `.github/workflows/test.yml` and `tox.ini` to define and
     run tests against Oracle, and also ensuring coverage databases
     do not collide during parallel test execution.

4. Comprehensive Test Coverage:
   - Introduce `tests/panels/test_sql_oracle.py` with rigorous unit
     tests mocking and verifying the helper's edge cases, legacy vs.
     modern QBR handling, error boundary sanitization, and fallback
     options.
   - Add integration tests verifying correct explain output and
     formatting across both synchronous and asynchronous contexts.

Fixes #227

Author: luzfcb

.github/workflows/test.yml

@@ -261,6 +261,77 @@ jobs:
         path: .coverage.sqlite.${{ matrix.python-version }}*
         include-hidden-files: true
 
+  oracle:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      max-parallel: 5
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+
+    services:
+      oracle:
+        image: gvenzl/oracle-free:23.26.2-slim-faststart
+        env:
+          ORACLE_PASSWORD: oracle_secret_pass
+        ports:
+          - 1521:1521
+        options: >-
+          --health-cmd "healthcheck.sh"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+          --health-start-period 60s
+          --health-start-interval 5s
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      with:
+        persist-credentials: false
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+      with:
+        python-version: ${{ matrix.python-version }}
+        allow-prereleases: true
+
+    - name: Get pip cache dir
+      id: pip-cache
+      run: |
+        echo "dir=$(pip cache dir)" >> $GITHUB_OUTPUT
+
+    - name: Cache Pip Dependencies
+      uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
+      with:
+        path: ${{ steps.pip-cache.outputs.dir }}
+        key:
+          ${{ matrix.python-version }}-v1-${{ hashFiles('**/pyproject.toml') }}-${{ hashFiles('**/tox.ini') }}
+        restore-keys: |
+          ${{ matrix.python-version }}-v1-
+        lookup-only: true
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install --upgrade tox tox-gh-actions
+
+    - name: Test with tox
+      run: tox
+      env:
+        DB_BACKEND: oracle
+        DB_NAME: localhost:1521/FREEPDB1
+        DB_USER: system
+        DB_PASSWORD: oracle_secret_pass
+        DB_HOST: ""
+        DB_PORT: ""
+        COVERAGE_FILE: ".coverage.oracle.${{ matrix.python-version }}"
+
+    - name: Store coverage file
+      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+      with:
+        name: coverage-oracle-${{ matrix.python-version }}
+        path: .coverage.oracle.${{ matrix.python-version }}*
+        include-hidden-files: true
+
   lint:
     runs-on: ubuntu-latest
     strategy:
@@ -306,6 +377,7 @@ jobs:
       - mysql
       - postgres
       - sqlite
+      - oracle
     permissions:
       pull-requests: write
       contents: write

debug_toolbar/panels/sql/forms.py

@@ -79,6 +79,13 @@ def explain(self):
                 cursor.execute(f"EXPLAIN QUERY PLAN {sql}", params)
             elif vendor == "postgresql":
                 cursor.execute(f"EXPLAIN ANALYZE {sql}", params)
+            elif vendor == "oracle":
+                from debug_toolbar.panels.sql.oracle_helper import (
+                    OracleExplainPlanHelper,
+                )
+
+                helper = OracleExplainPlanHelper(cursor)
+                return helper.execute(sql, params)
             else:
                 cursor.execute(f"EXPLAIN {sql}", params)
             headers = [d[0] for d in cursor.description]