rdbms-playground/docs/adr/0050-incidental-ddl-confirmations-omit-relationships.md

ADR-0050: Incidental-DDL confirmations omit relationship info (structure-only)

Status

Accepted + implemented 2026-06-12 (issue #28). Closes Gitea #28. Both forks below were escalated to the user and user-chosen before any code was written; implemented test-first. Supersedes the incidental-DDL clause of ADR-0044 §1 and the part of ADR-0016 §5 that placed a relationship block under every structure echo. The diagram behaviour ADR-0044 introduced for relationship-subject surfaces is unchanged.

Context

ADR-0016 §5 rendered a structure box followed by a plain-text References: / Referenced by: relationship block under every structure echo. ADR-0044 §1 split that by surface:

• Relationship-subject surfaces — show table <T>, add 1:n relationship, drop relationship, show relationship <name> — render relationships as compact diagrams (the user asked for, or acted on, a relationship).
• Incidental DDL auto-shows — create table, add/drop/rename/ change column, add/drop index — kept the terse prose block, with the rationale "a simple add column on a heavily-related table should not print a wall of diagrams."

Issue #28 reconsiders the deeper question ADR-0044 did not ask: should an incidental-DDL confirmation show relationship information at all? Owner preference: no. A confirmation echo should focus on the change just made — the new / updated structure — not re-print the table's relationships, which the user did not touch. The terse prose was the lesser of "prose vs diagram", but the right answer for these surfaces is neither.

Decision

Incidental-DDL confirmation echoes render the structure only — the table-name header, the column / type / constraints box, the Indexes: section, and the constraint section — with no relationship section (neither prose nor diagram).

• Scope: all incidental DDL (user-chosen, over "just add column"): create table, add column, drop column, rename column, change column, add index, drop index. The rule is uniform — a structural edit confirms structure, never relationships. (For a freshly created table the relationship section was empty anyway; the rule still applies for consistency of the mental model.)
• Relationship-subject surfaces are unchanged. show table, add/drop relationship, and show relationship <name> still render diagrams. Relationships appear only when the user asks for them (show table / show relationship) or acts on one (add/drop relationship).
• No information is lost. Anything dropped from an incidental echo is one show table <T> away.

Mechanism

The handle_dsl_success routing (app.rs) is unchanged: it still sends relationship-subject commands to the diagram renderer and everything else to render_structure. The change is entirely inside render_structure (output_render.rs): it no longer appends the relationship block — render_structure = structure box + indexes + constraints. All of render_structure's callers are incidental DDL (verified), so this single edit covers the whole scope with no per-command branching.

Prose renderer disposition

The orphaned prose renderer (relationship_prose_lines, and its sole helper cols_disp) is deleted (user-chosen, over retaining it dormant). After this change no shipped surface renders the prose form, so keeping it would be dead code. The prose format remains documented in ADR-0016 §5 and in git history; if ADR-0044's OOS-7 user-configurable "always-prose" display setting is ever built, it re-introduces the ~30 lines from that provenance.

Forks (all user-chosen)

• Scope: all incidental DDL, not just add column — the owner's rationale ("confirm the change, not untouched relationships") applies uniformly, gives a clean mental model, and is the simpler edit (remove one call vs a per-command flag).
• Prose renderer: delete it — no dead code — over retaining a public, tested-but-uncalled renderer for the speculative OOS-7 setting.

Consequences

• Incidental confirmations are shorter and on-topic; a heavily-related table no longer prints a relationship wall after add column.
• One relationship renderer (prose) leaves the codebase; the diagram renderer (ADR-0044) is the only relationship render path that ships.
• requirements.md is unaffected (this is an ADR-tracked refinement of a decided area, like ADR-0044 itself); the change is cross-referenced from the commit + this ADR.

Tests

• Unit (output_render.rs): the prose-asserting test render_structure_with_relationships (+ its snapshot) is removed; a new test asserts render_structure on a description carrying both inbound and outbound relationships emits the structure box but no References: / Referenced by: lines. The box/index/constraint tests are unaffected (their descriptions have no relationships).
• Integration (walking_skeleton.rs): the misnamed add_relationship_flow_shows_inbound_section_on_parent (which sends an AddColumn and asserted the inbound prose) is inverted + renamed to assert the add-column confirmation shows the structure but omits the relationship prose.
• Unchanged: the diagram tests (show_list.rs show table, walking_skeleton.rs add relationship) still pass — they already assert prose is absent and diagrams are present.

Out of scope

• The diagram form and its per-surface defaults (ADR-0044) — unchanged.
• The OOS-7 user-configurable display setting (always-prose / -diagram / auto-by-width) — still a future follow-up; this ADR removes the prose renderer, not the idea of a prose mode.