Db Draw Laravel Package

Getting Started

Install it as a dev dependency so it never ships to production:

composer require --dev jawira/db-draw

The smallest useful invocation is "point at a database URL, emit a PlantUML file":

vendor/bin/db-draw 'mysql://user:[email protected]:3306/app' --output=docs/db.puml

The .puml output is plain text — open it in an IDE with a PlantUML plugin, or render it with plantuml -tsvg docs/db.puml. If you have a local PlantUML install you can usually ask the tool for the image directly, but producing the .puml first is the safer first step because it has no Java dependency.

Where to look first:

1. vendor/bin/db-draw --help — the authoritative flag list; treat any snippet you find online as illustrative.
2. The package README for connection-URL examples.
3. Jawira\DbDraw\DbDraw — the programmatic entry point, which mirrors the CLI.

First use case: reverse-engineering an inherited or legacy schema. Run it once against staging, commit the .puml to docs/, and you have a reviewable, diffable ER diagram for onboarding without touching the database.

Programmatic minimal example:

use Doctrine\DBAL\DriverManager;
use Jawira\DbDraw\DbDraw;

$connection = DriverManager::getConnection(['url' => env('DATABASE_URL')]);

DbDraw::create()
    ->generatePlantUml($connection)
    ->saveToFile(base_path('docs/db.puml'));

Implementation Patterns

Composer script for repeatability. Don't leave the command in a shell history; wrap it:

"scripts": {
  "db:diagram": "db-draw \"$DATABASE_URL\" --output=docs/db.puml"
}

Artisan command wrapper (the Laravel-native pattern). Keep the DB credentials out of the command by building a URL from Laravel's own config:

$c = config('database.connections.mysql');

$url = sprintf(
    'mysql://%s:%s@%s:%d/%s',
    rawurlencode($c['username']),
    rawurlencode($c['password']),
    $c['host'],
    $c['port'],
    $c['database'],
);

$connection = DriverManager::getConnection(['url' => $url]);

DbDraw::create()
    ->generatePlantUml($connection)
    ->saveToFile(base_path('docs/db.puml'));

Wrap that in php artisan db:diagram and you get config inheritance, .env handling, and one obvious place to add filters per environment.

Separate generation from rendering. Generate .puml in PHP/CI (cheap, deterministic, no Java). Render to SVG/PNG in a separate step — a build image with PlantUML, a GitHub Action, or a developer's machine. This keeps your application test suite and CI pipeline free of a JVM.

Multi-connection / multi-schema. Loop over config('database.connections'), skipping non-relational drivers (sqlite in-memory, mongodb), and write one .puml per connection (docs/db-{connection}.puml). For large databases, split by domain instead of one monster diagram.

Diff-friendly documentation. Commit the .puml and regenerate it as part of a "before release" checklist or a scheduled job. Because PlantUML is text, the diagram shows up in pull request diffs — reviewers can see a table or relation appear without running anything.

Targeted diagrams. Use the table filter/exclude options (see --help for exact spelling) to scope output: exclude migrations, jobs, failed_jobs, telescope_*, sessions, cache*, and pivot tables you don't care about. Add columns only when the diagram is small enough to stay legible.

Gotchas and Tips

Image output requires PlantUML and Java. The .puml path never does. If --format=png/svg fails, verify plantuml is on PATH or pass the jar/binary location explicitly. In CI, a PlantUML Docker image is often less painful than installing Java on the runner.

Only declared foreign keys become relationships. If your schema has implicit joins (user_id columns without an FK constraint, or application-level relations), the diagram will show isolated tables. Either add the constraints or hand-annotate the generated .puml. This is the single most common "the diagram is wrong" report.

Driver names differ from Laravel's. Laravel uses mysql, pgsql, sqlite, sqlsrv; Doctrine DBAL expects pdo_mysql, pdo_pgsql, etc., or a URL scheme. URL-based connections sidestep the mapping entirely and are the most robust choice here. Watch URL-encoding on passwords containing @, :, /, or #.

Permissions matter. The tool introspects system catalogs (information_schema and friends). A restricted read user on a managed database may see nothing or only its own schema. Test against the same credentials your app uses before blaming the tool.

Don't put passwords in the command line. Shell history, process listings, and CI logs all leak it. Always route through an environment variable or a config-derived URL.

Large schemas produce unreadable output. Twenty tables is fine; two hundred is wallpaper. Filter aggressively, and when you can't, split by module and drop --columns. Adding column detail multiplies diagram size fast — reserve it for focused, small diagrams.

Views, enums, composite keys, and partial indexes are second-class. Expect noise or omissions in these areas. The tool reflects what DBAL reports; quirks in type mapping for exotic column types are a DBAL concern, not something to fight here.

Pin the version. This is a small, single-maintainer package (low star count, young project). CLI flags and output formatting can shift between releases. Pin it in composer.json, and treat regeneration as a deliberate action rather than wiring it into every build — otherwise diagram churn drowns real changes.

Extension point: post-process the text, don't fork. Because the output is PlantUML, you can append !theme directives, note blocks, grouping (package/together), and custom colors with a small post-processing step in your Artisan command. That covers 90% of customization needs without maintaining a fork.

Version tension with Doctrine DBAL. If another dependency pins DBAL to a different major version than this package expects, you'll get resolution conflicts. A --dev install avoids runtime impact but still shares the same vendor/ tree, so check composer why doctrine/dbal when installation fails.

Debugging output. If a diagram is empty, first confirm the connection resolves to the right database (SELECT current_database() / DATABASE()), then check your filter patterns — an over-broad exclude regex silently removes everything. Generating the .puml before rendering isolates introspection bugs from rendering bugs.