Tool to visualize database diagrams (ERD)

Severity: Recommended

Developers should have a way to visually understand the database schema - table relationships, foreign keys, and overall structure. This accelerates onboarding and reduces mistakes.

Check automatically:

1. Check for Prisma (has built-in visualization):

# Prisma can generate ERD via prisma-erd-generator or Prisma Studio
grep -rE "prisma|@prisma/client" package.json 2>/dev/null

# Check for ERD generator in Prisma schema
grep -rE "prisma-erd-generator|erd-editor" prisma/schema.prisma 2>/dev/null

2. Check for DBML files (dbdiagram.io format):

# DBML is a common ERD format
find . -name "*.dbml" -type f 2>/dev/null

3. Check for ERD documentation:

# Look for ERD images or documentation
find . -type f \( -name "*erd*" -o -name "*schema*" -o -name "*diagram*" \) \( -name "*.png" -o -name "*.svg" -o -name "*.pdf" \) 2>/dev/null

# Check docs folder specifically
ls -la docs/*erd* docs/*schema* docs/*diagram* 2>/dev/null

4. Check for database visualization packages:

# NPM packages for ERD generation
grep -rE "dbdiagram|prisma-erd|tbls|schemaspy|eralchemy" package.json 2>/dev/null

# Python ERD tools
grep -rE "eralchemy|sadisplay|django-extensions" requirements*.txt pyproject.toml 2>/dev/null

5. Check for visualization in docker-compose:

# Tools like SchemaSpy or tbls might run as containers
grep -rE "schemaspy|tbls" docker-compose*.yml 2>/dev/null

Ask user:

• "How do developers visualize the database schema?"
• "What tool do you use to see table relationships?"
• "Where is the ERD documentation (if any)?"

Common tools (for reference):

• Prisma Studio - Built into Prisma, shows schema visually
• dbdiagram.io - Web tool, uses DBML format
• DBeaver - Free database IDE with ERD view
• DataGrip - JetBrains database IDE with ERD
• TablePlus - GUI with schema visualization
• pgAdmin - PostgreSQL admin with ERD plugin
• tbls - CLI tool that generates schema docs
• SchemaSpy - Generates HTML documentation with diagrams

Cross-reference with:

• DBT-002 (data exploration - often same tool provides both)
• Section 5 (Database setup - schema should be documented)

Pass criteria:

• Team has an accessible way to view database schema visually
• New developers can quickly understand table relationships
• ERD is current (reflects actual schema, not outdated)

Fail criteria:

• No visualization tool available
• "We read the migration files" (not visual)
• ERD exists but is outdated/unmaintained
• Only production DBA has access to visualization tools

Evidence to capture:

• Tool(s) used for ERD visualization
• Location of ERD documentation (if static)
• Whether ERD is auto-generated or manually maintained
• Accessibility (all developers, or restricted)

---