Dbstan Laravel Package

Getting Started

Install the package with Composer (it is Laravel auto-discovered, so no manual provider registration on Laravel 8+):

composer require --dev itpathsolutions/dbstan

Then publish the configuration so you can see the ruleset before running anything:

php artisan vendor:publish --tag=dbstan-config

The published config/dbstan.php is where you should look first — it lists the conventions and checks the tool applies (table/column naming, index coverage, foreign-key presence, type consistency, etc.). Reading it tells you more about the tool's opinions than the README does.

Run the analyzer against your default connection:

php artisan dbstan:analyze

(Use php artisan list | grep -i dbstan to confirm the exact command signature for your installed version, since command names have shifted between releases.)

First use case: point it at an existing legacy project before a refactor. The output is a standardization/health report — naming outliers, tables missing indexes, inconsistent column types — which makes an excellent starting backlog and a "before" snapshot you can diff against after cleanup.

Implementation Patterns

Baseline-then-gate. Run once on main, capture the output, and commit the rule config. From then on, run the analyzer in CI and fail the build on new findings only. This is the single highest-value pattern: retrofitting an entire legacy schema at once is unrealistic, but stopping the bleed is not.

Pre-migration review checklist. Before merging a migration that adds a table, run the analyzer on a fresh migrate:fresh database and eyeball the new table. It catches the boring stuff reviewers miss: missing index on the foreign key, varchar(255) where every sibling uses string, status as string instead of an enum-ish type.

Pair with existing tooling, don't replace it. dbstan is a schema-convention and analysis layer, not a query profiler. Keep Larastan for static types, Pint for code style, and Laravel Telescope/Debugbar for runtime query cost. Treat dbstan output as a code-review comment source, not an authoritative performance report.

Convention config per project. Because the ruleset is config-driven, tune it to the project rather than the reverse: whitelist legacy tables, disable checks that don't apply (e.g. multi-tenant schemas with intentional prefixing), and document why in a comment block at the top of the config. This is the file new team members should read on day one.

Multi-connection usage. For apps with a separate reporting or tenant connection, run the analyzer per connection and store the reports side by side; drift between the primary and secondary schemas is a common source of production bugs and is exactly what this class of tool surfaces well.

Scheduled drift reports. A weekly scheduled run that posts the summary into Slack gives you early warning when a hotfix migration bypassed review.

Gotchas and Tips

• It reads the live schema, not your migrations. The analysis reflects what is actually in the database, so a stale local DB produces misleading findings. Always php artisan migrate:fresh (or analyze a CI-provisioned database) before trusting the output.
• SQLite and MySQL disagree. Index behavior, type names, and foreign-key introspection differ; a clean report on SQLite does not guarantee a clean report on production MySQL/Postgres. Run CI against the same engine as production.
• Large schemas are noisy. On a 150-table legacy database the first report is overwhelming. Scope the run to a subset of tables/connections where the tool supports it, and work outward.
• Exit codes matter more than pretty output. Confirm the command returns non-zero on failure before wiring it into CI; otherwise a green pipeline hides the findings.
• Don't auto-apply fixes. If the package offers any "fix"/"standardize" mode, treat its output as suggestions to be turned into hand-written migrations. Generated schema changes bypass your review, rollback, and data-preservation considerations.
• JSON, ENUM, spatial, and custom column types are frequent false positives. Most standardization tools don't model vendor-specific types; expect to suppress or ignore these in config rather than "fixing" them.
• Debugging a confusing finding: open the rule's config entry, then inspect the table directly (SHOW CREATE TABLE ... / \d+ ...) — the mismatch between what you believe the schema is and what the tool reports is usually the real bug.
• Keep it in require-dev. It has no runtime role in the application, and pulling it into production dependencies only adds deploy surface — but note it then won't be available for a scheduled production drift check, so run that job from a separate tooling environment.
• With only ~50 stars and 0 dependents, treat the package as a useful but lightly battle-tested utility: pin the version in composer.json, and be prepared to vendor small fixes yourself. The MIT license makes that painless.