Keeping the diagram current.

A committed diagram is only useful while it is true. The cheapest way to keep it true is to regenerate it in the same step that changes the schema, so the diff lands in the pull request that caused it.

When to regenerate

Regenerate after anything that changes either input:

Nothing else moves the file. Rewriting a controller, adding a scope, or reformatting a model changes nothing, because neither input changed.

Regenerate with your migrations

Bind the two together in a Composer script so migrating locally always refreshes the diagram:

{
  "scripts": {
    "migrate": ["@php artisan migrate", "@php artisan cartographer:erd"],
    "erd": "@php artisan cartographer:erd"
  }
}

composer migrate

Do not add cartographer:erd to a deployment script. Production has no reason to write into the repository, and the package is a dev dependency that will not be installed there.

Review the diff

The point of committing the file is the diff:

php artisan migrate
php artisan cartographer:erd
git diff docs/erd.md

     posts {
         bigint author_id FK
+        bigint editor_id FK
         text body "nullable"

Read the diff as a second opinion on the migration. A new FK marker that you did not intend, an edge that disappeared because a relation method was renamed, an entity that vanished because a table was dropped — each of those shows up here before it shows up in production.

An empty diff after a schema change means the change did not reach the database you generated against. Check that the migration ran on the connection Cartographer is reading.

Catch a stale diagram before you push

A pre-commit hook keeps the file honest without anyone remembering:

#!/usr/bin/env bash
# .git/hooks/pre-commit
set -euo pipefail

php artisan cartographer:erd
git add docs/erd.md

That regenerates and stages the diagram on every commit. It needs a reachable database, so it is the wrong choice for a team where not everyone runs one locally. In that case, prefer failing the build — see continuous integration.

For a shared hook that lives in the repository, point git at a tracked directory:

git config core.hooksPath .githooks

Multiple diagrams

If you generate a set, regenerate the whole set together. A script that produces some diagrams from today's schema and leaves others on last month's is worse than no diagrams:

{
  "scripts": {
    "erd": "bin/erd"
  }
}

Diagrams per subsystem has the script.

What a clean regeneration proves

Running the command twice with no changes leaves the working tree clean. That is worth knowing, because it means any diff at all is a real change to your models or your schema — never renumbering, reordering, or timestamp noise. The output carries no date and no version stamp for exactly this reason.

What to read next

• Continuous integration to fail a build on a stale diagram.
• Diagrams per subsystem for generating a set.
• Troubleshooting if a regeneration produces an unexpected diff.