rdbms-playground/docs/adr/0039-explain-over-advanced-sql.md

ADR-0039: EXPLAIN over advanced-mode SQL queries

Status

Accepted — decision recorded 2026-05-27. Implemented 2026-05-30 (issue #7; see Implementation below). Supersedes ADR-0030 §13 OOS-2.

Context

ADR-0028 gave the DSL explain command: a prefix over show data / update / delete that runs EXPLAIN QUERY PLAN and renders an annotated, span-styled plan tree. ADR-0030 §13 OOS-2 excluded "EXPLAIN of advanced-mode SQL queries."

On readback (2026-05-27) that exclusion is a deferred out-of-scope item, not a rejected one (see ADR-0000's out-of-scope discipline): its own wording — "the DSL explain still works for what it already wraps" — shows it was "not included in this surface," never "undesirable for teaching." There was no pedagogical argument against it; it simply fell outside the Phase-4/5 SQL-surface scope. It surfaced while characterising advanced-mode explain (briefly suspected a bug; it was OOS-2 behaving exactly as written).

Letting a learner see the plan for the SQL they wrote is a natural extension of ADR-0028's intent, so OOS-2 is lifted.

Decision

explain works over advanced-mode SQL queries — the SQL commands Select / SqlInsert / SqlUpdate / SqlDelete — in addition to the DSL ShowData / Update / Delete it already wraps (ADR-0028). It runs EXPLAIN QUERY PLAN over the command's validated SQL text and renders through the existing ADR-0028 plan tree. Advanced mode only (the SQL commands are advanced-only); the DSL explain stays available in both modes, unchanged. Supersedes ADR-0030 §13 OOS-2.

Design sketch (deferred to the build)

• Grammar. The explain inner gains the SQL statement shapes in advanced mode, alongside the DSL trio — mirroring how explain already wraps the DSL nodes, here wrapping the SQL command shapes.
• Execution. Run EXPLAIN QUERY PLAN over the carried SQL text (the Sql* / Select commands already hold validated text); reuse ADR-0028's plan capture + renderer. EXPLAIN QUERY PLAN never executes the statement, so explaining a destructive SQL command is safe — the same property ADR-0028 already relies on.
• Mode. SQL inner only in advanced mode; DSL inner in both, unchanged.

Built test-first when picked up.

Implementation (2026-05-30)

Built as designed, with the mode-gating and DSL/SQL disambiguation handled by the existing shared-entry-word dispatch rather than any new grammar machinery:

• Two explain CommandNodes under one entry word. The original data::EXPLAIN (Simple, DSL inner) is unchanged. A new data::EXPLAIN_SQL (Advanced) carries EXPLAIN_SQL_SHAPE — a Choice over select / with / insert / update / delete, each [Word, Subgrammar(&SQL_*_SHAPE)] reusing the standalone SQL command shapes. Both register under explain in REGISTRY, exactly mirroring the insert/update/delete shared-word pattern (ADR-0033 §2). The walker's decide then does all the work: advanced mode tries EXPLAIN_SQL first and falls back to the DSL EXPLAIN when no SQL branch matches (explain show data …, or a DSL-only --all-rows); simple mode reaches only the DSL node. with (CTE) is included — it builds a Command::Select, in scope per the decision's AST naming.
• Rejected DynamicSubgrammar mode-gating. A factory reading ctx.mode would be memoised wrongly: the dynamic-resolution cache key omits mode, so a node resolved in one mode would be served back in the other. The two-CommandNode route avoids this and stays on the established dispatch path.
• Clean inner SQL. build_explain_sql slices the inner SQL text from the source starting at the inner entry keyword's span (so the carried text excludes explain), then delegates to the existing build_select / build_sql_* builders. Their metadata extraction (target table, etc.) reads the path by role, which is offset- independent, so wrapping is transparent.
• Execution. do_explain_plan gains arms for Select / SqlInsert / SqlUpdate / SqlDelete that run EXPLAIN QUERY PLAN over the carried SQL text verbatim, no bound params (grammar-as-text). display_sql is the user's text as written (the DSL path canonicalises only because it synthesises SQL). The ADR-0028 renderer is reused unchanged.
• Behaviour note. In advanced mode explain update … / explain delete … now route through the SQL path (previously the DSL inner). The plan is identical (§6/§7 parity), and the SQL grammar accepts the full SQL syntax the DSL grammar rejected. DSL-explain tests were pinned to simple mode; advanced SQL wrapping has its own tests.

Out of scope

• EXPLAIN of DDL (CREATE / ALTER / DROP). EXPLAIN QUERY PLAN applies to SELECT / INSERT / UPDATE / DELETE; DDL has no query plan. (Deferred — may be revisited if a useful rendering emerges; per ADR-0000's out-of-scope discipline, this is deferred, not rejected.)

Consequences

• A self-contained feature, orthogonal to the DSL → SQL echo (ADR-0038): the echo renders SQL from DSL commands; this explains SQL the user wrote. They share nothing but the plan renderer's lineage.
• One OOS item in ADR-0030 §13 is now superseded; the rest stand.

See also

• ADR-0028 — the DSL explain and the span-styled plan tree this reuses.
• ADR-0030 §13 — OOS-2, superseded here.
• ADR-0032 / ADR-0033 — the SQL SELECT / DML this explains.
• ADR-0000 — the out-of-scope discipline that reframed OOS-2 as deferred.