Introduction.

A migration changes your database, but it does not update the diagram your team uses to understand it. Over time, that diagram stops matching the application.

Laravel Cartographer generates a Mermaid entity relationship diagram from an existing Laravel application. Run one Artisan command:

php artisan cartographer:erd

The command writes docs/erd.md. GitHub and GitLab render the file as a diagram:

erDiagram
    posts }o--|| categories : "category"
    posts ||--o{ comments : "comments"
    posts }o--o{ tags : "tags"
    posts }o--|| users : "author"

    posts {
        bigint author_id FK
        text body "nullable"
        bigint category_id FK "nullable"
        bigint id PK
        varchar title
    }

Commit the generated file with the migration. The pull request then shows the database change and the updated diagram together.

Where the diagram comes from

Cartographer combines information from your models and your database.

Your Eloquent models provide the relationships. For example, an author() relation becomes an edge labelled author.

Your database provides the tables, columns, and keys. Cartographer reads the current schema instead of rebuilding it from old migration files.

The package never reads rows from your tables. It reads schema information and builds Eloquent relation objects without running relation queries.

What you can generate

The default command creates a Markdown file containing Mermaid syntax. You can also:

• show only part of a large application;
• create a separate diagram for each subsystem;
• reduce or hide column details;
• export an SVG or PNG with mermaid-cli;
• fail a CI build when a committed diagram is out of date.

The detailed options live in the operations and reference pages. The quick start uses the default path first.

Requirements

The package follows semantic versioning. You can upgrade within 1.x without breaking changes.

Source code and issues are available on GitHub.

What it does not do

• It does not parse migration files. It reads the current database schema.
• It does not read application data.
• It does not include an image renderer. SVG and PNG exports use a mermaid-cli installation in your project or on your system.
• It does not add routes, pages, middleware, or migrations to your application.
• It does not include tables that have no discovered model, except pivot tables used by many-to-many relationships.
• It does not support ORMs other than Eloquent.

What to read next

• Installation and setup to install the package and confirm that it can find your models and database.
• Quick start to generate, review, and commit your first diagram.
• How a diagram is built to understand where each part of the generated file comes from.