Database Laravel Package

Product Decisions This Supports

• Build vs. buy on the data access layer. If webman is our runtime, this is the "buy" answer: we inherit Eloquent (models, relationships, casts, soft deletes), the query builder, pagination, and multi-connection handling instead of writing and owning a persistence layer. The PM decision is really "do we accept a framework-shaped data layer in exchange for zero maintenance cost," and this package is the concrete artifact of that trade.
• Framework standardization / roadmap commitment. Adopting this effectively ratifies webman as the runtime for the service(s) in question. It is a coupling decision, not a library decision — worth calling out explicitly on the roadmap as an architectural commitment with a multi-quarter tail.
• Connection pooling as a first-class requirement. Because webman keeps processes resident and serves many requests per process, naive per-request connections cause exhaustion and stale-connection failures in production. This package's pool is the difference between "works in dev, falls over at 200 rps" and "works." That is a reliability/roadmap input the PM should own, not delegate.
• Migration cost modelling. Eloquent is the most widely understood PHP ORM. If we have Laravel code or Laravel-trained engineers, porting models is close to copy-paste — a materially lower estimate than a Doctrine or hand-rolled rewrite, and a strong input to "rewrite vs. port" sequencing.
• Feature scoping for CRUD-heavy surfaces. Admin panels, internal tools, REST/JSON APIs, and reporting endpoints are the sweet spot. The PM can greenlight these without a data-layer design spike; anything needing async/non-blocking DB I/O is a separate conversation.
• Upstream-currency as a roadmap input (strengthened by v2.1.10). The v2.1.10 release widens the illuminate/database constraint to ^10.0 || ^11.0 || ^12.0 || ^13.0, i.e. it now declares support through the next major Laravel line. That is a maintenance-signal data point the PM can use: the dependency is being tracked forward, not pinned to a fading branch. It also means we can plan a Laravel 13-era upgrade without waiting on a fork or a patch of our own.
• Compliance and procurement. MIT license, no attribution burden, no commercial dependency — removes legal review from the critical path.
• Hiring and onboarding economics. "Laravel-shaped" is a recruiting and ramp-time advantage; it also means code review standards and internal style guides can be reused rather than invented.

When to Consider This Package

Adopt when:

• The runtime is webman/Workerman (or will be). This is close to a prerequisite — the pool and container bindings are built for that process model and offer little value outside it.
• We need an ORM at all — i.e., relationships, eager loading, model events, pagination, query-builder expressiveness — rather than 20 hand-written prepared statements.
• The team already knows Laravel/Eloquent, or we want to hire against that skill pool.
• We need multiple connections, read/write splitting, or per-connection configuration, and want that solved without bespoke code.
• We need production survivability under concurrency in a resident-process server and don't want to build pooling ourselves.
• We are on, or planning onto, a modern Laravel line. As of v2.1.10 the supported illuminate/database range is ^10.0 || ^11.0 || ^12.0 || ^13.0, so Laravel 10 through 13 are all in-scope. Services older than Laravel 10 are out of range.

Look elsewhere when:

• We're not on webman. On plain Laravel/Symfony, use illuminate/database directly; on a Doctrine shop, use Doctrine. This package's value is the webman integration, not the ORM.
• We need genuinely non-blocking database I/O. This is PDO-backed; pooling bounds resource usage but does not make queries async. If the workload is I/O-bound at high concurrency, evaluate Swoole coroutine clients, AMPHP, or ReactPHP-based stacks instead. Be honest about this in the ADR — it is the single most common mismatch. Note that v2.1.10 does not change this; the release is a compatibility-range update only, and no async/coroutine execution model was added.
• We need enterprise ORM capabilities — unit of work, identity map, mature migration/diff tooling, DBAL-level schema management. Doctrine wins there; Eloquent's migration story under webman is thinner and typically requires additional ecosystem plugins.
• We need heavy first-class CLI/migration scaffolding out of the box. Verify what's actually shipped versus what lives in adjacent webman plugins before committing the delivery plan.
• Footprint matters — minimal-dependency services, CLI scripts, or single-request apps where pooling and a container buy nothing.
• We are pinned below Laravel 10. The v2.1.10 constraint floor is ^10.0; there is no stated support path for EOL illuminate majors, so that becomes a hard constraint on any legacy-service migration.

Adoption caveats to gate on:

• Public signals remain weak (5 stars, 0 tracked dependents). Treat that as an artifact of ecosystem packaging rather than proof of abandonment — the package is effectively first-party to webman — but do not skip diligence. Run a two-day spike: pin the version, confirm PHP/illuminate/* version compatibility, and load-test the pool under realistic concurrency including connection-drop recovery.
• Upstream tracking — partially de-risked by v2.1.10. The widened constraint to ^13.0 is direct evidence that the maintainer is following illuminate majors rather than letting the package drift onto a frozen Laravel branch. That materially lowers the "our security-patch lag becomes their release cadence" concern, but it is one data point, so keep the check in the review process: on each Laravel major, confirm a matching constraint bump lands within a reasonable window. Do not assume v2.1.10 was a functional change — it reads as a constraint-only release, so nothing in the runtime behavior, pooling, or API surface should be assumed to have moved.
• Define the exit path up front: because this is a thin adaptation layer over illuminate/database, swapping the container binding and connection resolver is a bounded effort. That keeps the lock-in argument honest and small.

How to Pitch It (Stakeholders)

To executives: This is an MIT-licensed, first-party component of the webman ecosystem, maintained by the framework's own author. Adopting it means we don't build or maintain a database layer, we don't pay license or support fees, and we don't create vendor lock-in — it's a thin, replaceable layer over a widely used open-source ORM. The latest release (v2.1.10) extends declared compatibility to the newest major Laravel database package, which is a concrete signal that the dependency is being kept current rather than left to rot — and it means we can take upstream security patches on the normal cadence instead of scrambling. It also lets us staff against the largest PHP ORM skill pool, which reduces ramp time and delivery risk. Cost of adoption is low; cost of the alternative (bespoke persistence code) is ongoing and invisible until it breaks.

To engineering: Drop-in Eloquent models, query builder, and pagination, plus a connection pool designed for webman's resident-process model — which is what stops us from shipping a service that exhausts MySQL connections under load or serves stale connections after an idle period. Multi-connection and read/write split are supported. The API is familiar, so review and onboarding costs are near zero. Heads up on v2.1.10: it is a dependency-constraint release only — illuminate/database is now ^10.0 || ^11.0 || ^12.0 || ^13.0 — so treat it as a compatibility widening, not a feature drop. Practical implication: confirm our PHP version against the Laravel 13 requirement matrix before we claim that upper bound, and pin deliberately rather than floating on ^ if we want reproducible builds.

Risks to state plainly, not bury: small public footprint, PDO-blocking under the hood (not async), and a dependency on the webman ecosystem's release cadence — the last of which v2.1.10 improves but does not eliminate. Mitigations: a short validation spike with pinned versions, a load test that includes failure/recovery, and a documented exit path via the illuminate/database binding. Net recommendation: adopt for webman-hosted, CRUD-centric services on Laravel 10+; do not adopt as a general-purpose ORM or as a way to get async database access.