Files

T

claude@clouddev1 9f15f386d5 docs(adr): design the DSL→SQL teaching echo (ADR-0038) + dependencies

Realises ADR-0030 §10 (the DSL→SQL teaching bridge) as a /runda'd design
set, before implementation:

- ADR-0037 (new): execution-time mode side-channel — SubmissionMode
  {Simple, Advanced, AdvancedOneShot} threaded Action→worker, output-only;
  redeems ADR-0033 Amendment 3's deferred follow-up. Replay stays silent.
- ADR-0038 (new): the teaching echo + full catalogue (Buckets A/B/C),
  the copy-paste round-trip contract, the three-category framework, and
  the Value→SQL-literal renderer. DDL + show-data centric (overlapping
  DML is SQL-first, so already SQL). Build-order deps recorded.
- ADR-0035 Amendment 2: standard-first dialect stance + ALTER COLUMN
  SET/DROP NOT NULL, SET/DROP DEFAULT, ISO SET DATA TYPE gap-fill.
- ADR-0033 Amendment 4: reclassifies the `update … --all-rows`
  non-fall-back as a bug; it now falls back to the DSL Update and echoes
  (keyed on adjacent `--`; spaced arithmetic preserved).
- ADR-0039 (new): EXPLAIN over advanced SQL — decision recorded, build
  deferred; supersedes ADR-0030 §13 OOS-2.
- ADR-0000: out-of-scope discipline (deferred vs rejected). README index
  updated for all of the above.

Reconcile CLAUDE.md: simple-mode column ops are implemented, not pending
(requirements.md C2/B2 already [x]).

2026-05-27 20:44:38 +00:00

3.3 KiB

Raw Blame History

ADR-0039: EXPLAIN over advanced-mode SQL queries

Status

Accepted — decision recorded 2026-05-27. Implementation deferred as a follow-up to the ADR-0037/ADR-0038 teaching-echo effort: the decision below is settled, but the full design has not been /runda'd or built, and is not part of that pass. 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.

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.

3.3 KiB Raw Blame History