Database

/laravel-agent:db:diagram

Generate database schema ER diagram

Overview

The /db:diagram command generates a visual diagram of your database schema by analyzing Laravel migrations. It creates Entity-Relationship Diagrams (ERD) in multiple formats including Mermaid.js, DBML, and PlantUML, making it easy to visualize and document your database structure.

Usage

/laravel-agent:db:diagram [format] [tables]

Arguments

  • format (optional) - Output format: mermaid (default), dbml, or plantuml
  • tables (optional) - Comma-separated list of specific tables to include

Examples

# Generate full schema diagram in default Mermaid format
/laravel-agent:db:diagram

# Generate diagram in Mermaid.js format
/laravel-agent:db:diagram mermaid

# Generate diagram in DBML format for dbdiagram.io
/laravel-agent:db:diagram dbml

# Generate diagram in PlantUML format
/laravel-agent:db:diagram plantuml

# Generate diagram for specific tables only
/laravel-agent:db:diagram users,orders,products

# Generate DBML diagram for specific tables
/laravel-agent:db:diagram dbml users,orders

How It Works

The command analyzes your database schema through a three-step process:

  1. Analyze Schema - Reads all migration files in your database/migrations directory
  2. Extract Structure - Identifies table definitions, columns, data types, and relationships
  3. Generate Diagram - Creates a visual representation in your chosen format

Output Formats

Mermaid.js (Default)

The default format generates Mermaid.js ERD syntax that renders natively in:

  • GitHub README and markdown files
  • GitLab documentation
  • VS Code with Mermaid extensions
  • Many documentation platforms

DBML (Database Markup Language)

Export to DBML format for use with dbdiagram.io, an interactive database diagram editor. Perfect for:

  • Interactive editing and refinement
  • Sharing with team members
  • Exporting to various image formats

PlantUML

Generate PlantUML format for integration with documentation systems and wikis that support PlantUML rendering.

Example Output

Here's an example of a generated Mermaid.js ERD:

## Database Schema

```mermaid
erDiagram
    users ||--o{ orders : places
    orders ||--|{ order_items : contains
    products ||--o{ order_items : "ordered in"

    users {
        bigint id PK
        string name
        string email UK
        timestamp created_at
    }

    orders {
        bigint id PK
        bigint user_id FK
        string status
        decimal total
        timestamp created_at
    }

    products {
        bigint id PK
        string name
        string description
        decimal price
    }

    order_items {
        bigint id PK
        bigint order_id FK
        bigint product_id FK
        integer quantity
        decimal price
    }
```

Relationship Mapping

The command automatically detects relationships based on:

  • Foreign Keys - Explicit foreign key constraints in migrations
  • Naming Conventions - Columns ending in _id (e.g., user_id)
  • Pivot Tables - Many-to-many relationship tables

Supported Column Types

The diagram includes common Laravel migration column types:

  • Primary keys (id, bigIncrements, uuid)
  • Strings (string, text, char)
  • Numeric (integer, bigInteger, decimal, float)
  • Dates (timestamp, date, datetime)
  • Boolean (boolean)
  • JSON (json, jsonb)
  • Foreign keys and indexes

Use Cases

  • Documentation - Add schema diagrams to your project README or wiki
  • Onboarding - Help new developers understand the database structure
  • Planning - Visualize changes before creating migrations
  • Code Reviews - Include diagrams in PRs that modify schema
  • Architecture Discussions - Share visual representations with stakeholders

Best Practices

  1. Keep diagrams updated - Regenerate after schema changes
  2. Use specific tables for focus - Generate targeted diagrams for complex areas
  3. Choose the right format - Mermaid for documentation, DBML for collaboration
  4. Include in documentation - Add generated diagrams to your project docs
  5. Review relationships - Verify detected relationships match your intent

Tips

  • For large databases, generate diagrams for related table groups instead of the entire schema
  • Use DBML format when you need to manually adjust the layout or styling
  • Mermaid diagrams can be embedded directly in GitHub markdown files
  • Consider generating separate diagrams for different bounded contexts or modules

See Also