Laravel Truss - це пакет від Alberto Arena, який візуалізує структуру вашої бази даних як масштабовану entity-relationship діаграму, що відкривається безпосередньо у браузері. Пакет зчитує виключно структуру: таблиці, стовпці, ключі та індекси, жодного разу не виконуючи запити до самих даних. Це означає, що вам не потрібно підключати зовнішні GUI-клієнти до бази даних або регенерувати статичні діаграми після кожної міграції.
Основні можливості
Laravel Truss пропонує широкий набір функцій для роботи зі структурою бази даних:
- Живі ER-діаграми: таблиці, стовпці, первинні ключі та зв'язки, відрендерені за допомогою вбудованих Mermaid-активів
- Режим фокусування (Focus Mode): ізолює одну таблицю та її сусідів за foreign key зв'язками
- Порівняння схем (Schema Diffing): показує додані, видалені або змінені таблиці, стовпці, індекси та зовнішні ключі з моменту останньої міграції
- Діагностика схеми (Schema Doctor): перевіряє відсутність первинних ключів, неіндексовані зовнішні ключі, дублюючі індекси та ризиковані типи стовпців
- Підтримка кількох з'єднань: перемикання між налаштованими підключеннями до баз даних через панель інструментів
- Експорт: діаграма як PNG або SVG з браузера, структура як DBML, JSON, CSV, Mermaid або Markdown-словник даних з браузера чи командного рядка
- Офлайн-режим та CSP-безпека: шрифти та бібліотеки Mermaid постачаються разом із пакетом, тому нічого не завантажується з CDN
Інтерактивна панель ER-діаграм
Відвідавши роут /truss, ви отримуєте полотно у стилі карти, яке можна панорамувати та масштабувати над вашими таблицями. Клацнувши на таблицю, режим фокусування виділяє її разом із сусідніми таблицями за foreign key зв'язками, затемнюючи все інше.
Наприклад, фокусування на таблиці posts центрує її разом із чотирма таблицями, на які вона посилається або які посилаються на неї, приховуючи решту схеми з поля зору. Елемент керування глибиною (Depth) розширює це коло по одному кроку за раз.
Ви можете фільтрувати таблиці за назвою, перемикатися між нативними SQL-типами та Laravel-стильними мітками стовпців, а також вибирати між світлою та темною темами креслення. Якщо ваш додаток працює з кількома базами даних, перерахуйте з'єднання, які хочете бачити, у config/truss.php. Ключі - це назви з'єднань, які вже є у вашому config/database.php, і кожне може приховувати власні таблиці:
// config/truss.php
'connections' => [
'pgsql' => [],
'analytics' => ['excluded_tables' => ['page_views', 'raw_events']],
],
Якщо налаштовано два або більше з'єднань, у панелі інструментів з'являється перемикач. Його переключення повторно рендерить схему з'єднання та зберігає вибір в URL, щоб ви могли додати в закладки або поділитися конкретним виглядом. Кожне з'єднання інтроспектується відносно власної бази даних, тому нічого із сусідньої схеми не потрапляє на діаграму.
Оскільки статичні ресурси та шрифти входять до складу пакета, панель працює офлайн і функціонує за суворими правилами Content Security Policy без завантаження сторонніх скриптів.
Порівняння схем та відстеження міграцій
Truss кешує структурний знімок після виконання міграцій, а потім порівнює поточну базу даних із цим знімком. Подібно до інструментів для виявлення змін у схемі, він відображає результат у панелі "Changes" веб-інтерфейсу та через Artisan-команду:
php artisan truss:diff
Порівняння охоплює додані або видалені таблиці, зміни типів стовпців, коригування індексів та оновлення зовнішніх ключів. Пакет ніколи не читає записи таблиць.
Діагностика Schema Doctor
Schema Doctor виконує детерміністичні перевірки структури та виявляє:
- Таблиці без первинного ключа
- Стовпці зовнішніх ключів без індексу
- Дублюючі або надлишкові визначення індексів
- Ризиковані типи даних
Результати відображаються на панелі "Health" дашборда, і ви можете виконати ті самі перевірки з терміналу або CI-пайплайну:
php artisan truss:doctor
Експорт із командного рядка у кількох форматах
Для документування бази даних або передачі структурного звіту команді Truss експортує як візуальну діаграму, так і визначення, що стоять за нею. Кнопка експорту на дашборді зберігає діаграму як PNG або SVG, а структуру як DBML, JSON, CSV, Mermaid або Markdown-словник даних. Ви також можете працювати з однією таблицею за раз: клацання на таблицю у діаграмі відкриває меню для фокусування, копіювання її JSON або завантаження окремої таблиці як JSON, CSV чи Markdown, що зручно, коли потрібно передати комусь форму лише однієї таблиці.
Ті самі структурні формати доступні для всієї схеми з терміналу:
php artisan truss:export --format=dbml --output=docs/schema.dbml
Вивід йде у stdout, якщо ви не передаєте --output, і він детерміністичний, тому одна й та сама схема завжди генерує однакові байти незалежно від порядку, в якому база даних повідомляє свої таблиці. Саме це робить прапорець --check корисним у CI: він регенерує експорт, порівнює його із закомічений файлом і завершується з ненульовим кодом, якщо вони відрізняються, тож міграція, що змінює схему без оновлення файлу, провалить білд.
Цей експорт доповнює такі інструменти, як команда schema dump, коли ви працюєте з великою схемою або підтримуєте документацію проєкту актуальною.
Встановлення та налаштування
Truss вимагає PHP 8.3+ та Laravel 12+. Для локальної розробки встановіть його як dev-залежність:
composer require albertoarena/laravel-truss --dev
За замовчуванням роут /truss увімкнено лише у середовищі local. Щоб використовувати його у staging або production за авторизаційним гейтом, встановіть його як звичайну залежність без --dev, потім увімкніть і налаштуйте переглядачів у вашому додатку.
Для налаштування кастомних тем, авторизації та повного списку CLI-опцій дивіться репозиторій Laravel Truss на GitHub або сайт документації Truss.
