Database Laravel Package

Technical Evaluation

Release delta (v2.1.10): the only substantive change is a widened dependency constraint — illuminate/database now accepts ^10.0 || ^11.0 || ^12.0 || ^13.0 (previously capped below 13). No API changes, no deprecations, no behavioral changes, no bug fixes listed. This is a compatibility-ceiling raise, not a feature release. It matters for upgrade planning and dependency resolution, not for architecture or code.

Positioning correction (unchanged, material): webman/database is not a Laravel package. It is the database component of the webman framework (Workerman-based, resident-memory PHP runtime) that adapts illuminate/database — Laravel's Query Builder, Eloquent ORM, Schema Builder and pagination — onto a connection-pooled, long-lived worker model. The TPM value proposition is therefore not "adopt Laravel's DB layer" but "carry Laravel-shaped developer ergonomics and existing Eloquent models into a webman service with minimal rewrite."

Architecture fit

• Strong fit only if the target runtime is webman/Workerman (optionally Swoole or Swow coroutines). It exists precisely because vanilla illuminate/database holds a singleton PDO per process, which exhausts MySQL connections under N resident workers.
• Poor fit inside Laravel, Laravel Octane, or PHP-FPM — those should use illuminate/database directly. Adopting this package there buys a pool you don't control and a config path (config/plugin/webman/database/) that contradicts Laravel's bootstrap.
• Reuses Laravel's public DB API surface, so repository/model code is largely portable in both directions. That bidirectionality is the real architectural asset, and v2.1.10 extends it one Laravel major further.

Integration feasibility

• Install is a single Composer require plus webman's plugin auto-discovery; DB config is a near-clone of config/database.php, so Laravel-fluent engineers ramp with near-zero API learning.
• The widened constraint removes a concrete resolver hazard: teams that also depend on illuminate/* 13.x components in the same tree (shared packages, monorepo tooling) will no longer get a Composer conflict when webman/database is added. That was a real blocker scenario worth flagging as now resolved.
• Schema migrations require webman/console (or an alternative runner); that's the one piece of tooling that does not come for free from Laravel familiarity.
• Eloquent models move over, but container-dependent behavior (observers, model events wired through service providers, global scopes bound in the container) needs explicit re-binding — webman does not ship the full Laravel container.

Technical risk

• License: MIT, no constraint.
• Adoption signal: 5 stars and 0 dependents is weak package-level evidence; real usage is bundled through the webman framework, so treat the repo as single-maintainer infrastructure rather than an independently validated library.
• Constraint-vs-test-matrix gap (new): v2.1.10 advertises ^13.0 support, but a one-line constraint bump does not prove the package's test suite actually runs against Laravel 13. Treat 13.x as resolver-permitted, not validated, until you either see CI matrix coverage upstream or run the parity suite yourself. Historically this pattern is how "supported" versions quietly rot.
• Prior metadata anomaly (a stated last-release date inconsistent with the artifact) is partly alleviated: this release ships a real compare link and a concrete changelog. Still verify the actual tag before pinning; the diff shown is a manifest constraint only, so confirm no transitive lock changes.
• Pool semantics remain the dominant risk — connection affinity for transactions and session state is the classic failure source in this design. Nothing in this release touches it.
• Opportunity score 45.99 signals a commoditized space: no differentiation to exploit, only switching-cost savings.

Key questions

1. Which runtime — plain Workerman, Swoole, or Swow? Pool behavior and debugging differ across all three.
2. Do we need driver parity beyond MySQL (Postgres, SQLite in tests)?
3. Which Laravel features do our models actually rely on — DB only, or queues/events/container?
4. What is our per-worker pool size and resulting peak connection count against max_connections?
5. Who owns upgrades when illuminate/database ships a breaking minor — and does our policy now treat a ^13 bump as routine (it should not) or as a reviewable change?
6. Does upstream CI actually exercise 13.x, or is that constraint aspirational?

Integration Approach

Stack fit

• Requires PHP 8.1+, Composer 2, webman 2.x, Workerman 5.x. Bind only the Illuminate\Database\* contracts; do not attempt to bootstrap a full Laravel application container inside webman.
• Fits cleanly when the DB layer is the only Laravel dependency. Every additional illuminate/* package you import increases the surface you must manually wire — but with v2.1.10 the version-alignment cost of that surface is materially lower.
• Version policy: pin illuminate/database explicitly in your root composer.json rather than letting ^10 || ^11 || ^12 || ^13 float. The new ceiling is permission, not a recommendation to move.

Migration path (strangler, not big-bang)

1. Extract a single low-risk service (read-heavy, no distributed transactions) behind webman as a proof of concept.
2. Keep Eloquent models and repository interfaces unchanged; swap only the bootstrap — Laravel service providers out, webman plugin config in.
3. Repoint migrations to webman/console; run a schema-parity check against the existing database before any cutover.
4. Run the existing model/repository unit tests against the webman pool to surface container-assumption breaks early. Extend the matrix across every illuminate/database major you claim to support — v2.1.10 makes 13.x a plausible target, so either test it or exclude it.
5. Cut over remaining services incrementally; keep the old path live until error budgets are clean.

Compatibility

• Connection-pool semantics break the "one connection per request" assumption. Transactions must pin an explicit connection (Db::connection(...)) and release in finally; naive DB::transaction() inside coroutines risks cross-request leakage on a reused connection.
• Long-lived connections retain server-side state (session variables, temp tables, LAST_INSERT_ID). Anything relying on implicit per-request reset needs auditing.
• Pool sizing math (workers × pool max ≤ MySQL max_connections − headroom) must be settled before load testing, not after.
• Cross-major nuance: illuminate/database 12→13 deprecations (query-builder internals, model attribute casting, schema API) propagate through this adapter. The adapter widening its constraint does not insulate you from those; it only stops Composer from stopping you.

Sequencing Pool design → PoC service → model-parity test suite → migration tooling swap → load test → incremental cutover → provider decommission. Migrations and pool sizing remain the two long-lead items; start both in week one. The v2.1.10 constraint bump adds no schedule work — except one half-day to confirm which illuminate/database major you are actually going to standardize on now that three majors are nominally open.

Operational Impact

Maintenance

• You inherit two upgrade cadences: illuminate/database (Laravel's minor/major deprecations) and webman's plugin versions. Pin both explicitly and treat minor bumps as reviewable changes, not routine. v2.1.10 widens the first cadence without narrowing the second — net effect is more supported combinations to reason about, so pinning discipline becomes more important, not less.
• With 5 stars and a single-maintainer footprint, budget for reading source and maintaining a patch queue or internal fork. Do not assume upstream will absorb your edge cases on your timeline.

Support

• Community-only: GitHub issues plus webman community channels. No vendor SLA. An internal runbook covering pool tuning, connection recycling, and transaction discipline is a prerequisite, not a nice-to-have.
• Add a runbook line for version drift: when a Laravel major lands, assume this adapter will accept it before it has validated it. Test first, trust the constraint second.

Scaling

• Capacity scales horizontally with workers, and every worker carries its own pool — connection count grows faster than instance count. This is the #1 surprise in production.
• Watch wait_timeout-driven stale connections, MySQL restarts, and failover: without ping/recycle logic, workers hold dead handles and surface errors until restart.
• Benchmark under sustained concurrency, not burst; resident workers mask cold-start costs that FPM deployments would have exposed.

Failure modes (ranked by likelihood × blast radius)

1. Connection leak on exception before pool release → gradual pool exhaustion, latency cliff, then hard timeouts.
2. Transaction state bleeding onto a reused connection → silent cross-request data corruption. Highest severity, hardest to detect.
3. Stale connection after DB restart/failover → error spike with no code change.
4. Pool exhaustion under load → request queueing that looks like an app slowdown but is a config problem.
5. Runtime divergence between Workerman/Swoole/Swow drivers → bugs that reproduce in one environment only.
6. (New, low severity) Silent major-version drift — a composer update slides illuminate/database from 12 to 13 on the strength of the widened constraint, exposing untested deprecation behavior in production. Cheap to prevent with an explicit root pin.

Instrument pool saturation, connection age, and per-request checkout duration from day one; these three metrics catch four of the six failure modes.

Ramp-up

• Engineers with Laravel experience are productive in ~2–3 days on the API, but need explicit training on pool and transaction discipline — this is where teams get burned.
• Ops/SRE need pool tuning and connection-budget literacy: 1–2 weeks including a load-test harness.
• Net: a small team reaches production confidence in roughly 3–4 weeks, contingent on standing up the parity test suite and load test in the first sprint. Absent those, defer adoption. v2.1.10 does not change this estimate; it only widens the set of Laravel versions you must decide not to use.