Task: Recover the ER diagram's relationships
Table of Contents
This page documents a task in the Split the ER diagram by group story. It captures the goal, current status, acceptance, and any notes or results.
1. Goal
A package diagram draws the arrows between the tables it holds. The arrows come from the SQL the parser already reads, so a new foreign key appears without anyone editing a list.
2. Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Split the ER diagram by group |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-10-09 |
3. Acceptance
- detect_relationships no longer consults FK_TARGET_TABLES, and the map is deleted.
- A key render, a check render and a nullable key render each produce the edge and its label; tests prove them.
- Adding a foreign key to a model and regenerating makes the edge appear with no code change.
4. Plan
(Implementation strategy. Written when work starts; key decisions
are distilled into the parent story's * Decisions at close, but the
plan itself stays — it is the historical record of what we did.)
5. Measurements
Every number this task claims about a tree, with the command that produced it
and the commit it was measured at. A number without both is not a measurement,
because a clean-up record describes a tree and trunk moves under a branch: a
consumer count, a gate's component count and a suite's size all change with no
code changing, and the reader of a bare number cannot tell which tree it came
from. Where the raw output matters, put it in an evidence/ file beside the
task and name that file in the Command column.
| What | Value | Command | Commit |
|---|---|---|---|
| Keys the create scripts state | 339: 336 trigger checks, 2 REFERENCES, 1 FOREIGN KEY | the three patterns over projects/ores.sql/create |
3495b31ff0 |
| Keys attached to a table | 338 | SQLParser().fk_targets |
3495b31ff0 |
| Edges in the model | 328, none dangling, none self-referencing | get_model()['relationships'] |
3495b31ff0 |
| Columns newly marked FK in the diagram | 57 | git diff on ores_schema.puml |
6af5fd35de |
| codegen-tests | pass, 75.2 s | compass check --only codegen-tests |
6af5fd35de |
| er-diagram | pass, 2.7 s | compass check --only er-diagram |
6af5fd35de |
6. Notes
The diagram still marks 1,473 columns as FK while only 273 of them have a
target that any script states. The gap is the naming heuristic in
apply_column_markings, which marks every *_id column and everything in
FK_COLUMNS: tenant_id appears 454 times and change_reason_code 373
times. Those markers are left alone here – this task is about the arrows
– but a column marked FK with no edge is the next thing the diagram
says that the schema does not. Worth a task once the split lands.
7. Test Scenarios
Manual QA scenarios (scaffolded via compass add test_scenario)
that verify this task. Link
new ones here as they're created; the scenario doc itself links back
via its "Verifies task" field.
| Scenario | State | Notes |
|---|---|---|
8. PRs
| PR | Title |
|---|---|
| #2930 | [codegen,sql] Recover the ER diagram's relationships |
9. Review
| Comment summary | File | Decision | Notes |
|---|---|---|---|
10. Result
The parser drew no edges because FK_TARGET_TABLES named its targets
without the ores_ prefix that every table in the model carries, so no
lookup could match. The map is deleted.
The targets now come from the schema itself. A create script states a key
in one of three ways, and all three are read: the comment the create
template emits above a trigger check, a REFERENCES clause on a column,
and a named FOREIGN KEY constraint. Each is attached to the table in the
same script that declares the column, so a hand-written script holding
several tables still resolves; a key whose column belongs to no table in
its script, or to more than one, is left out rather than guessed at.
Of 339 stated keys, 338 resolve to a table and 328 become edges: the rest are duplicates of the same table pair and keys a table holds to itself. That a key no script states still draws nothing is a test, so the arrows cannot drift back into a list kept in the parser.
The 57 columns whose target the SQL states but whose name never said so –
day_counter, calendar_code and their like – now carry the FK mark.