oli/rdbms-playground
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Advanced mode: explain not yet supported #7

New Issue
Closed
opened 2026-05-28 14:44:18 +01:00 by oliversturm · 1 comment
oliversturm commented 2026-05-28 14:44:18 +01:00 (Migrated from github.com)
Copy Link
Copy Source

Observed

In simple mode, explain show data <T> / explain update ... / explain delete ... work and render a styled EXPLAIN QUERY PLAN tree (ADR-0028).

In advanced mode, the equivalent SQL entry points (e.g. explain select * from Customers) are not yet wired up.

Expected

Advanced mode should support explain for at least select, update, delete — same plan-tree rendering as simple mode. EXPLAIN QUERY PLAN doesn't execute the wrapped statement, so this is safe for destructive verbs as well.

Status

Known pre-existing gap; tracker.

### Observed In simple mode, `explain show data <T>` / `explain update ...` / `explain delete ...` work and render a styled `EXPLAIN QUERY PLAN` tree (ADR-0028). In advanced mode, the equivalent SQL entry points (e.g. `explain select * from Customers`) are not yet wired up. ### Expected Advanced mode should support `explain` for at least `select`, `update`, `delete` — same plan-tree rendering as simple mode. `EXPLAIN QUERY PLAN` doesn't execute the wrapped statement, so this is safe for destructive verbs as well. ### Status Known pre-existing gap; tracker.
oliversturm commented 2026-05-30 19:44:18 +01:00 (Migrated from github.com)
Copy Link
Copy Source

Implemented in f62ccce (ADR-0039, marked implemented).

explain now wraps the advanced-mode SQL commands — select, with (CTE), insert, update, delete — in addition to the DSL show data/update/delete it already covered, rendering through the same ADR-0028 span-styled plan tree. Advanced mode only for the SQL inner; DSL explain unchanged in both modes.

Approach: a second Advanced explain CommandNode (EXPLAIN_SQL) registered under the shared explain entry word, reusing the established insert/update/delete shared-word dispatch (SQL-first, DSL-fallback) — no new grammar machinery. build_explain_sql slices the inner SQL off the source (excludes the explain prefix) and reuses the existing SQL builders; do_explain_plan runs EXPLAIN QUERY PLAN over the carried text verbatim, no params. EXPLAIN QUERY PLAN never executes, so it's safe for the destructive verbs.

Verified end-to-end in the live TUI (not just unit tests): each verb renders a plan tree; explain show data still works in advanced mode (DSL fallback); the plan flips SCAN→index SEARCH once an index exists; explain of update/delete/insert does not mutate data; explain create table … (DDL) is rejected; and the hint after explain offers select/with/insert/update/delete/show.

Notes: advanced explain update/delete now route through SQL (identical plan, full SQL syntax); DSL-explain tests pinned to simple mode. A VALUES insert has no query plan in SQLite, so explain insert … values (…) shows the SQL with an empty tree (correct). The terse [ok] explain <Table> echo is pre-existing (issue #9).

23 tests added (parsing, completion, execution against real SQLite, plus a REGISTRY help-id-uniqueness invariant). Full suite 2085/0/1, clippy clean. Docs: ADR-0039 status→implemented + Implementation section, README index, requirements.md QA1, CLAUDE.md, and help/usage text.

Implemented in f62ccce (ADR-0039, marked implemented). `explain` now wraps the advanced-mode SQL commands — `select`, `with` (CTE), `insert`, `update`, `delete` — in addition to the DSL `show data`/`update`/`delete` it already covered, rendering through the same ADR-0028 span-styled plan tree. Advanced mode only for the SQL inner; DSL `explain` unchanged in both modes. **Approach:** a second `Advanced` `explain` CommandNode (`EXPLAIN_SQL`) registered under the shared `explain` entry word, reusing the established `insert`/`update`/`delete` shared-word dispatch (SQL-first, DSL-fallback) — no new grammar machinery. `build_explain_sql` slices the inner SQL off the source (excludes the `explain` prefix) and reuses the existing SQL builders; `do_explain_plan` runs `EXPLAIN QUERY PLAN` over the carried text verbatim, no params. `EXPLAIN QUERY PLAN` never executes, so it's safe for the destructive verbs. **Verified end-to-end in the live TUI** (not just unit tests): each verb renders a plan tree; `explain show data` still works in advanced mode (DSL fallback); the plan flips SCAN→index SEARCH once an index exists; explain of update/delete/insert does **not** mutate data; `explain create table …` (DDL) is rejected; and the hint after `explain ` offers `select/with/insert/update/delete/show`. **Notes:** advanced `explain update`/`delete` now route through SQL (identical plan, full SQL syntax); DSL-explain tests pinned to simple mode. A `VALUES` insert has no query plan in SQLite, so `explain insert … values (…)` shows the SQL with an empty tree (correct). The terse `[ok] explain <Table>` echo is pre-existing (issue #9). 23 tests added (parsing, completion, execution against real SQLite, plus a REGISTRY help-id-uniqueness invariant). Full suite 2085/0/1, clippy clean. Docs: ADR-0039 status→implemented + Implementation section, README index, requirements.md QA1, CLAUDE.md, and help/usage text.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Something isn't working
 documentation
Improvements or additions to documentation
 duplicate
This issue or pull request already exists
 enhancement
New feature or request
 good first issue
Good for newcomers
 help wanted
Extra attention is needed
 invalid
This doesn't seem right
 question
Further information is requested
 wontfix
This will not be worked on
No labels enhancement
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
claude-clouddev1 oli (Oli Sturm)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: oli/rdbms-playground#7