Prequel Laravel Package

Getting Started

Prequel is a self-hosted, in-app database browser for Laravel — think "phpMyAdmin, but as a route in your app." It reads your existing Laravel DB configuration, so there is no second set of credentials to maintain.

Install (dev only):

composer require protoqol/prequel --dev
php artisan vendor:publish --tag=prequel          # config/prequel.php
php artisan vendor:publish --tag=prequel-assets   # public/vendor/prequel

Laravel package discovery registers Protoqol\Prequel\PrequelServiceProvider automatically. Add the toggle to .env (and only .env, never .env.example):

PREQUEL_ENABLED=true

Then boot php artisan serve (or Sail) and open http://localhost:8000/prequel.

Where to look first: config/prequel.php. It is the whole control surface — the route path, the enabled flag, the middleware stack, and which connection/database Prequel talks to. Read that file before anything else; every behaviour you'll care about is driven from it. Pay particular attention to the connection/driver key: as of v1.23.13, if the configured driver isn't one Prequel recognises, it now falls back to MySQL rather than erroring loudly (see Gotchas).

First use case: the one that makes Prequel worth the install is "a teammate or QA person needs to look at a table and I don't want to hand out DB credentials." Point them at /prequel, they browse tables, inspect schema, and run read queries — using the app's own connection.

Implementation Patterns

Local development browser (the 90% case). Keep it --dev in composer.json, enabled only in local. It's faster than alt-tabbing to TablePlus for "what's actually in this column after the seeder ran?", and it renders alongside your app so URL/asset/session bugs don't get confused with DB bugs.

Read-only inspection for QA / stakeholders. The pattern that works well:

// config/prequel.php
'enabled'    => env('PREQUEL_ENABLED', false),
'path'       => 'prequel',
'middleware' => ['web', 'auth', 'can:viewDatabase'],
'connection' => env('DB_CONNECTION'),

Wrap it in a Gate whose ability is granted to a small set of users, then flip PREQUEL_ENABLED=true on a staging box behind basic auth or an IP allowlist. Never expose it publicly.

Docker / Sail. Prequel is served by your app, so the only requirement is that PHP in the container can reach the DB host. If DB_HOST=mysql works for your app, it works for Prequel. No port-forwarding dance, which is genuinely the nicest thing about it in containerised setups.

Query scratchpad during migration work. Run the migration, then use the query runner to confirm the resulting schema and defaults. Useful for spotting the classic "MySQL silently coerced my ->default()" cases without leaving the terminal tab.

Keeping it out of production. Two belts: --dev so composer install --no-dev doesn't ship the code, and PREQUEL_ENABLED=false (the default in the published config) so a stray deploy can't expose it. Add it to your deploy checklist alongside Telescope and Ignition.

Multi-app monorepos. Each Laravel app gets its own Prequel instance on its own route. It does not aggregate across apps, so if you need cross-service browsing, this isn't the tool.

Pin the version explicitly. Since v1.23.13 changes driver-resolution behaviour, lock to a known-good tag ("protoqol/prequel": "1.23.13" in require-dev) rather than floating on ^1.23. You want the connection-fallback change to be a deliberate upgrade, not a surprise on composer update.

Gotchas and Tips

Momentum is thin — treat it as low-maintenance, not abandoned. The project went quiet through 2024 and has recently resumed with small community PRs (v1.23.13 is a connection-handling fix from a first-time contributor). That's a good sign, but it is still a single-maintainer-scale project with no security response process. Fine for a local dev tool; not fine for anything internet-facing. Pin the version and test each bump yourself rather than assuming Laravel-version compatibility.

v1.23.13: unknown drivers silently become MySQL. The headline change is "Make MySQL the default connection type in case the project's connection type is different." In practice: if your DB_CONNECTION isn't one Prequel maps, it no longer bails — it tries MySQL. On a Postgres or SQL Server project this surfaces as a connection/handshake error that looks like a credentials or driver problem, not a config-mapping problem. If Prequel suddenly "can't connect" after upgrading, check the driver mapping first, before touching DB_*. SQLite users on relative paths will hit this too, and it will mask the real cause.

No authentication of its own. Prequel assumes whatever middleware you put in front of it. The default config is ['web']. If you set enabled => true on a box where web doesn't imply auth, you've published your database to the internet. This is the single most common way people get burned.

Config caching. Change config/prequel.php and see nothing happen? php artisan config:clear. Same for route path changes — route:clear too, since Prequel registers its routes at boot. This matters double for the v1.23.13 driver fallback: the resolved connection is computed from cached config, so a stale cache will keep you on the old driver behaviour after you've "fixed" it.

Catch-all routes shadow it. If you have a Route::get('/{any}') or a Vue/Inertia fallback, Prequel's routes may never match. Register Prequel's path outside the wildcard, or move the wildcard lower in routes/web.php.

One connection at a time. Prequel reads a single connection from config; there's no in-UI connection switcher. Switching databases means editing config and clearing caches. Plan around it rather than fighting it.

SQLite relative paths. Use an absolute path (database_path('database.sqlite') or the resolved value of DB_DATABASE) — relative paths resolve against the process working directory, which differs between artisan serve, Octane, and queue workers, producing "database not found" errors that look like permission problems.

MySQL 8 authentication. If you're on caching_sha2_password with an old client library, Prequel's connection will fail where artisan tinker succeeds (different code paths, e.g. socket vs TCP). Verify PDO::getAvailableDrivers() and the PHP mysqlnd version before blaming the package.

Re-publish assets after any upgrade. public/vendor/prequel is a copy, not a symlink. Stale assets after a version bump produce blank pages or 404s on JS bundles — republish and hard-refresh before debugging anything else. Do this first when upgrading to v1.23.13.

Table prefixes and views. Prefixed tables and database views can render oddly or be filtered out of the sidebar. Fall back to the query runner for those rather than assuming the browse UI is broken.

Large tables will hurt. Row browsing paginates, but "select everything" through the query runner has no guardrails and no query timeout beyond PHP's max_execution_time. Point it at a replica or a dump, not a hot production table — even from staging.

Debugging checklist when the page is blank: php artisan route:list | grep prequel (is it registered?), check enabled, check the middleware stack for a redirect loop, check storage/logs/laravel.log, then check public/vendor/prequel exists. If it loads but can't connect, add "verify the driver actually maps to a supported one" to the end of that list — v1.23.13 makes a wrong driver look like a wrong password.

Extension point is the middleware stack. You can't easily override Prequel's internals, but middleware in config lets you bolt on IP allowlisting, LDAP auth, audit logging, or rate limiting without touching package code. That's the intended seam — use it rather than editing vendor/.