What Is Laravel Truss?
Laravel Truss is a package by Alberto Arena that renders your database structure as a live, interactive entity-relationship diagram you can open at /truss in the browser. It reads schema metadata only — tables, columns, keys, and indexes — and never touches row data, so there is no risk of exposing sensitive records.
The package requires PHP 8.3+ and Laravel 12+. Install it as a dev dependency for local use:
composer require albertoarena/laravel-truss --dev
By default the /truss route is active only in the local environment. Install it without --dev and configure an authorisation gate to expose it in staging or production.
Interactive ER Diagram Dashboard
Visiting /truss opens a map-style canvas you can pan and zoom. Click any table to enter Focus Mode, which centres that table alongside its foreign-key neighbours and dims everything else. A Depth control widens the visible ring one hop at a time, so you can trace relationships without losing context.
Additional controls let you:
- Filter tables by name.
- Toggle between native SQL types and Laravel-style column labels.
- Switch between light and dark blueprint themes.
Multi-Connection Support
If your application uses more than one database, list each connection in config/truss.php:
// config/truss.php
'connections' => [
'pgsql' => [],
'analytics' => ['excluded_tables' => ['page_views', 'raw_events']],
],
A toolbar picker appears when two or more connections are configured. Switching connections re-renders the schema and persists the selection in the URL so you can bookmark or share a specific view.
Because fonts and Mermaid assets ship with the package, the dashboard works offline and under strict Content Security Policy rules without fetching anything from a CDN.
Schema Diffing and Migration Tracking
Truss caches a structural snapshot after migrations run and compares the live database against it. The diff surfaces in a Changes panel in the dashboard and via Artisan:
php artisan truss:diff
The diff covers added or dropped tables, column type changes, index adjustments, and foreign key updates.
Schema Doctor Diagnostics
The Schema Doctor runs deterministic checks against your structure and flags:
- Tables with no primary key.
- Foreign key columns without an index.
- Duplicate or redundant index definitions.
- Risky data type choices.
Results appear in the dashboard's Health panel and can be piped into a CI pipeline:
php artisan truss:doctor
Command-Line Exports
Truss can export the full schema structure from the terminal in multiple formats:
php artisan truss:export --format=dbml --output=docs/schema.dbml
Supported formats: DBML, JSON, CSV, Mermaid, and Markdown data dictionary. Output is deterministic — the same schema always produces the same bytes regardless of the order the database reports its tables. That makes the --check flag useful in CI: it regenerates the export, compares it against the committed file, and exits non-zero when they differ.
The browser dashboard also lets you export the visual diagram as PNG or SVG, and individual tables as JSON, CSV, or Markdown.
Key Takeaways
- Live, zoomable ER diagrams rendered with vendored Mermaid assets — no external GUI needed.
- Focus Mode isolates a table and its foreign-key neighbours with a configurable depth.
- Schema diffing tracks structural changes since the last migration snapshot.
- Schema Doctor catches missing primary keys, unindexed foreign keys, duplicate indexes, and risky column types.
- Multi-connection support with per-connection table exclusions.
- Fully offline and CSP-safe; no CDN requests.
- Deterministic CLI exports enable schema drift detection in CI.
Source: Laravel News — Laravel Truss: Live Interactive Database ER Diagrams
