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.

Emacs 29.3 (Org mode 9.6.15)