Initial Oracle Database support to the SQL Explain panel - #2448
Open
luzfcb wants to merge 1 commit into
Open
Conversation
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 django-commons#227
luzfcb
force-pushed
the
initial_oracle_support
branch
from
August 14, 2026 22:07
3aca578 to
3404c4b
Compare
Coverage report
Click to see where and how coverage changed
This report was generated by python-coverage-comment-action |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Member
|
At first glance, this may be too big of a feature to merge in without knowing how many people would utilize this. It's a lot more code to maintain for a specific vendor. An alternative is to create a |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem:
django-debug-toolbar returns an HTTP 500 error when attempting to use the Explain panel with Oracle.
Click here to display the source of error when using with Oracle
Description
This PR solves the issue by introducing initial support for Oracle Database to django-debug-toolbar's SQL Explain panel, closing the 14-year-old issue #227.
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 Features & Implementations:
Oracle SQL Explain Orchestration:
OracleExplainPlanHelperto encapsulate and run the multi-stepEXPLAIN PLANandDBMS_XPLAN.DISPLAYlifecycle.PLAN_TABLEat the end of execution.ALL_TABLESandALL_INDEXESmetadata to format and append table and index statistics (sizes, status, performance counters) as aligned ASCII tables.Query Tracking and Toolbar Integration:
debug_toolbar/panels/sql/forms.pyto hookSQLSelectFormand delegate select-explain execution to the new Oracle helper.debug_toolbar/panels/sql/tracking.pyto filter out toolbar queries using vendor-specific quoting (quote_name).Infrastructure & CI/CD:
docker-compose.ymlto provision local PostgreSQL, MariaDB, and Oracle Database Free containers for multi-backend testing..github/workflows/test.ymlandtox.iniwith isolated test/coverage databases.Testing:
tests/panels/test_sql_oracle.pywith rigorous unit and mocking coverage.**Click here to display how Explain will looks like on Oracle**
Screenshot
A real report
Checklist:
docs/changes.rst.AI/LLM Usage