DOCS

Quickstart

1. Upload one or more baseline files — SQL/PL-SQL source, a DBMS_XPLAN execution plan export, an AWR/TKPROF report, or an Oracle dump — into the baseline panel.
2. Upload the matching current files from the run you're investigating into the current panel. Multiple files of the same type are paired by filename, then by position.
3. Click Analyze. OraTune parses both sides, computes the diff and plan comparison, and runs the findings engine — plus your configured AI provider, if one is set.
4. Review the four result tabs — Code Diff, Execution Plans, Findings, and Recommendations. See Reading your results for what each one shows.
5. Export the report from File > Export Report. It saves a single self-contained HTML file with the findings, plan comparison, diff statistics, and recommendations.

Supported file types

Reading your results

When analysis finishes, the results land in four tabs, each covering a different facet of the comparison.

• Code Diff — syntax-highlighted baseline-vs-current SQL. Changed, added, and removed lines are colour-coded; structural changes such as hint or index-hint additions and removals are listed beneath, with a similarity ratio and add, remove, and change counts.
• Execution Plans — the two plan trees side by side, with cost and cardinality at each node. Full-scan regressions, index changes, join-method changes, and new sort operations are called out, along with a total-cost delta and a plan-shape-changed flag.
• Findings — every issue as a severity-sorted card. Click any ORA-XXXXX code to open its reference entry.
• Recommendations — root-cause analysis and numbered remediation, from your AI provider or the offline engine, rendered as Markdown.

Severity levels

Every finding carries one severity. The app also colour-codes them; the label is the source of truth.

Exported report

File > Export Report writes a single self-contained HTML file — all findings, the plan-comparison summary, code-diff statistics, and recommendations — with no external CSS or JavaScript. It is portable enough to attach to a change ticket.

Batch analysis

Batch analysis compares many file pairs in one run. Switch to the Batch tab, set a baseline folder and a current folder, and click Run Batch.

• Pairing — files are matched by exact filename across the two folders (case-sensitive). report_q1.sql in both folders is one pair. Name files consistently or they will not pair.
• Type — each pair is classified by extension and analysed as the matching single-pair type. Only recognised extensions are considered — the SQL/PL/SQL set, .xml plans, .txt/.lst/.html/.htm reports, and .dmp dumps.
• Unmatched files — anything present in only one folder is listed in the results but not analysed. Review that list for naming mismatches.
• Results — one row per pair with its highest-severity finding; click a row for that pair's full findings log. When an AI provider is configured, a summary paragraph closes the run.

Live database mode

Live DB mode connects OraTune to a running instance for real-time diagnostics. Click Connect in the Live DB tab and enter connection details.

• Connection dialog — two connection types:
  • Direct: Host, Port (default 1521), Service Name, Username, Password.
  • TNS: TNS Alias, Username, Password.
  • Test Connection opens and immediately closes a connection to validate the credentials, without disturbing the active session.

Least-privilege connection

Grant only what the tabs you use require.

Every tab needs only SELECT on the views it queries. Plan Baselines and Scheduler additionally require EXECUTE on DBMS_SPM or DBMS_SCHEDULER — those grants let OraTune alter, drop, or run jobs from inside the app, so restrict them to a connection you trust with that control.

Estimated vs actual plans

The Explain Plan tab runs one of two ways. Estimated runs EXPLAIN PLAN and reads it back with DBMS_XPLAN.DISPLAY — the statement is not executed. Actual runs the statement with a gather_plan_statistics hint and reads real row counts with DISPLAY_CURSOR. Because Actual mode executes the statement, do not run it against a query that performs DML. Bind variables (:name) are set to NULL so the statement plans without values.

Stats Health checks

The Stats Health tab runs five checks against optimizer statistics — stale, missing (NUM_ROWS null), locked, un-analysed partitions, and system statistics. Each result carries a severity and can be filtered by schema.

For what every Live DB tab does, see Features.

ORA- error reference

OraTune bundles an offline reference for 225+ ORA- error codes — no internet connection needed.

• Open it from Tools > ORA- Error Reference (Ctrl+Shift+O), or click any ORA-XXXXX code shown in the Findings tab to jump straight to that entry.
• Each entry carries the message template, the cause, and the recommended action.
• Search matches across code, message, and cause at once (case-insensitive) and filters as you type. An empty search lists every entry.

AI recommendations

The Recommendations tab works with no configuration: a deterministic offline rules engine ships findings with Oracle-specific remediation on its own.

• Optional providers — add an API key in Tools > Settings to use Claude, OpenAI, Azure OpenAI, or GitHub Copilot for root-cause narratives instead. Claude is the default.
• What leaves your machine — with a provider enabled, OraTune sends a summary of the analysis to that provider's API. Nothing is sent when the offline engine is used. For exactly what the summary contains, see the FAQ.
• Where keys live — Windows Credential Manager, under the service name OraTune, one entry per provider — never the settings file. If no secure store is available, OraTune leaves the key unset rather than writing plaintext. Keys can also be supplied by environment variable: ANTHROPIC_API_KEY, OPENAI_API_KEY, AZURE_OPENAI_API_KEY, GITHUB_COPILOT_TOKEN.

Tips

• Upload matching artifacts on each side — baseline SQL with current SQL, baseline plan with current plan.
• For execution plans, generate with SELECT * FROM TABLE(DBMS_XPLAN.DISPLAY_CURSOR(sql_id => 'YOUR_SQL_ID', format => 'ALL ALLSTATS LAST')).
• For TKPROF, upload the raw .lst or .txt from the tkprof utility, not the spooled session log.
• For ADR traces, rename the .trc file to .dmp before uploading.
• AI recommendations are sharpest when you provide both the SQL and an execution plan — the plan comparison gives precise context for what changed.
• The offline engine handles common regressions — stale statistics, index changes — well without any key.
• Batch: name files identically across folders so they pair, and review the unmatched list after the run.
• Live DB: if Oracle Client is installed, thick mode activates automatically and covers older Oracle versions that thin mode does not.

Troubleshooting

Still stuck? Contact us.

FAQ