Skip to content

refactor: use dbterd 1.28 built-in json ERD target#4

Merged
datnguye merged 1 commit into
mainfrom
refactor/erd-builtin-json-target
Jun 15, 2026
Merged

refactor: use dbterd 1.28 built-in json ERD target#4
datnguye merged 1 commit into
mainfrom
refactor/erd-builtin-json-target

Conversation

@il-dat

@il-dat il-dat commented Jun 15, 2026

Copy link
Copy Markdown
Collaborator

What & why

Migrate ERD extraction from our custom @register_target("json") adapter to dbterd 1.28's built-in, schema-validated json target. dbterd now owns the {nodes, edges, metadata} contract, so the locally-registered target (and its module) are no longer needed. build_erd(target="json") forces the official target and build_erd_data maps its payload into the SPA's {nodes, edges} shape, patching two known dbterd quirks: short-name edge ids under entity_name_format (resolved via a name_to_id map) and missing is_foreign_key flags on some algos like model_contract (back-filled from each edge's from_columns). The dbterd floor is bumped to >=1.28 (the built-in json target floor), and dbdocs/extract/erd_json.py plus its unit test are deleted.

Type of change

  • 🐞 Bug fix (non-breaking change that fixes an issue)
  • ✨ Feature (non-breaking change that adds capability)
  • 💥 Breaking change (existing behavior changes)
  • 🧹 Refactor / internal (no user-facing change)
  • 📖 Docs only

Area

  • CLI (generate / serve / deploy)
  • extract/ (nodes / erd / graph / column_lineage / health)
  • site/ (data dict / builder / 3-tier SPA / deploy)
  • frontend/ (React Flow graph bundle)
  • Config (dbdocs.yml) / packaging / CI / docs

How to test

task test           # 331 tests, 100% coverage — covers build_erd_data, _resolve_edge_id, _backfill_fk_flags
task frontend:e2e   # verifies the ERD renders against a real demo build (the dbterd-quirk regression gate)
task generate && task serve   # open the site, click a model, check the ERD tab renders nodes + FK edges

Checklist

  • task lint passes (ruff format --check + ruff check). — clean, 60 files formatted, all checks passed.
  • task test passes at 100% coverage (the gate is enforced in CI). — 331 passed, TOTAL 100.00%.
  • I followed the load-bearing patterns in .claude/design_patterns.md (extended an existing seam, didn't fork one). The "ERD from dbterd's built-in json target" pattern entry + TOC are updated in this PR to match the new implementation.
  • Data-dict / SPA changes keep producer ↔ consumer in sync — the {nodes, edges} shape the builder emits is unchanged; the graph bundle consumes the same keys. Payload is not re-inlined.
  • Graph-UI changesdbdocs/site/bundle/assets/graph/index.js carries a small aligned tweak to erd_algo / is_foreign_key handling; frontend/src/** is unchanged so no full bundle rebuild was needed.
  • New files under dbdocs/site/bundle/** covered by the pyproject.toml artifacts glob. — n/a, no new bundle files (a module was deleted).
  • Docs / dbdocs.yml.example updated for any new config knob or CLI flag. — n/a, no new config knob or CLI flag; .claude/skills/spa-site/SKILL.md and the design-pattern doc were updated to reflect the dbterd 1.28 floor.

Screenshots / notes

  • dbterd dependency floor moves >=1.27>=1.28; uv.lock updated to match.
  • The two patched dbterd quirks (short-name edge ids, missing FK flags) are the regression-prone seams — re-run task frontend:e2e on future dbterd bumps to confirm they still hold.

@datnguye datnguye self-requested a review June 15, 2026 02:23
@datnguye datnguye merged commit e44a20c into main Jun 15, 2026
14 checks passed
@datnguye datnguye deleted the refactor/erd-builtin-json-target branch June 15, 2026 02:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants