Database Pgsql Laravel Package

Technical Evaluation

Architecture fit. hyperf/database-pgsql is not a Laravel package in any meaningful sense — it is the PostgreSQL driver adapter for hyperf/database, Hyperf's coroutine-aware fork of illuminate/database. Its job is narrow: register a Postgres connection resolver, grammar, and post-processor so Hyperf's ORM can speak to PostgreSQL. Hyperf runs on Swoole/Swow with persistent, connection-pooled, coroutine-shared state; Laravel runs on a shared-nothing PHP-FPM/Octane request lifecycle. Those are different execution models with different assumptions about connection reuse, transaction isolation across coroutines, and static state. For a product that is Laravel-based, this package has zero direct architectural fit — Laravel already ships first-party PostgreSQL support in illuminate/database, and pulling in the Hyperf driver would be a parallel, non-functional dependency at best and a namespace/static-state collision at worst. The realistic lens is: this package matters only if we are (a) already committed to Hyperf for a service, or (b) evaluating Hyperf's database layer as a component we might adopt or fork.

Integration feasibility. Mechanically trivial in the right context: Composer install, ensure the connection factory registers the pgsql driver, configure host/port/database/username/password plus pool sizing in config/autoload/databases.php. There is no service provider, no facade, no publishable config — it's wiring, not application surface. In the wrong context (Laravel, Symfony, vanilla PHP), integration feasibility is effectively nil without forking and re-homing the connection classes.

Technical risk. Three credible risks, ranked:

1. Ecosystem mismatch (high, structural). Adopting this is not a package decision, it's a runtime decision. Any team that "just adds PostgreSQL support" via this package on a non-Hyperf stack will discover the dependency graph drags in hyperf/database, hyperf/support, PSR/coroutine contracts, and a Swoole extension requirement. That is a platform migration disguised as a library install.
2. Maintainership and signal quality (high). 12 stars and an opportunity score of 1.72 indicate a near-zero independent user base. The [READ ONLY] prefix strongly suggests a subtree-split mirror of the Hyperf monorepo — meaning issues and PRs likely are not triaged in this repository at all. Combined with an unverifiable repository URL in the metadata and a last release timestamp of 2026-07-26 (a future date, i.e. bad or synthetic metadata), the provenance signal is weak. Anyone relying on this must track the upstream monorepo, not this repo.
3. Correctness surface (low-to-moderate, bounded). The code volume is small and the surface is well-understood (grammar, processor, connection, DSN parsing, type mapping). It is auditable in hours. The real correctness exposure lives in hyperf/database itself — coroutine-safe connection pooling, transaction-per-coroutine semantics, COPY/RETURNING handling, JSON/array/interval type round-tripping — not in this adapter.

Key questions.

• Is any part of our roadmap actually on Hyperf/Swoole, now or in the next 12 months? If no, this is a close-out.
• If yes: are we standardizing on Hyperf's ORM, or tunneling Eloquent-compatible code through it? The latter is where coroutine-safety bugs hide.
• Which upstream commit/version does this split correspond to, and where is the authoritative issue tracker?
• Do we need PostgreSQL-specific behavior (advisory locks, LISTEN/NOTIFY, COPY, partitioned tables, jsonb operators) that this adapter does or does not expose?
• What is our connection-pool budget per coroutine worker under peak concurrency, and who owns that capacity planning?

Integration Approach

Stack fit. Classify the package as platform-conditional, not stack-additive. It fits only a Hyperf service. For our Laravel services, the correct answer is illuminate/database's native pgsql driver — no third-party package, no added supply-chain surface. Do not attempt to use this package as a way to "get better PostgreSQL support" in Laravel; it provides no such thing.

Migration path. There is no incremental migration path from Laravel to this package, and pretending otherwise is the main delivery risk. If we ever move a service to Hyperf, the sequence is: prove the runtime (Swoole/Swow extension availability in our images, coroutine-safe third-party clients) → port config and connection pooling → port queries → only then does this adapter appear, as a one-line dependency. Treat it as the last mile of a platform migration, never the first step.

Compatibility. Verify against a pinned hyperf/database minor, PHP 8.1+, and the ext-swoole/ext-swow version in our base image. Because it is a split mirror, version constraints should be pinned exactly rather than ranged; a floating constraint against an auto-split repo can silently drift from the monorepo. Also confirm PSR-3/PSR-11/PSR-16 alignment with whatever else we run, and test jsonb, arrays, numeric, timestamps with timezones, and NULL semantics explicitly — those are where fork drift shows up.

Sequencing. (1) Decision gate on Hyperf in the stack at all. (2) If no — record a "no-adopt" decision with rationale and stop; do not carry it as a backlog item. (3) If yes — sponsor a spike that stands up a Hyperf service against our PostgreSQL instance, exercises pooled connections under coroutine concurrency, and measures leak/state-bleed behavior. (4) Only after the spike passes, add the dependency and pin it.

Operational Impact

Maintenance. Low code-maintenance burden, high tracking burden. We will not be patching this adapter; we will be watching the Hyperf monorepo. Budget a recurring line item: "monitor upstream releases, re-pin, re-run PostgreSQL integration suite." If we fork, that flips to genuine ownership — a fork means we own grammar and type-mapping correctness forever, which is a poor trade for 12 stars of community validation.

Support. No vendor, no meaningful community, and a read-only repo that likely redirects contributions upstream. Internal expertise must be developed, not hired. Realistically, support for this package is one or two engineers who understand coroutine connection semantics — a bus-factor of two. Document that explicitly.

Scaling. The adapter is not the scaling lever; the connection pool and worker count are. Under Swoole, each worker holds persistent pooled connections, so total backend connections scale as workers × pool_size per node — a number that surprises teams coming from PHP-FPM. PostgreSQL's max_connections and any PgBouncer in front of it become the binding constraint. Size this before load testing, and validate behavior under connection exhaustion rather than assuming graceful degradation.

Failure modes. Watch for: (a) connection state bleeding between coroutines — the highest-severity failure, presenting as nondeterministic wrong-query results; (b) transactions leaking across coroutine boundaries under high concurrency; (c) pool starvation producing latency cliffs rather than errors; (d) silent version drift between this split and the upstream monorepo; (e) type-mapping regressions on jsonb/arrays that only surface in production data shapes.

Ramp-up. For an engineer already fluent in Eloquent, the query-builder API is familiar — hours, not weeks. The real ramp is coroutine and pooling literacy: days to weeks, and it is not transferable from Laravel experience. Plan for one engineer to own the Hyperf data layer end-to-end and to write the internal runbook covering pool sizing, transaction scoping rules, and connection-exhaustion triage.

Bottom line. For a Laravel-based product, do not adopt — Laravel's built-in PostgreSQL driver is the correct, supported, zero-risk choice, and this package offers no capability Laravel lacks. The only defensible reason to take this dependency is a deliberate, already-funded move to Hyperf, in which case it is a reasonable, small, auditable component — but adopt it with an exact pin and a documented upstream-tracking process, not as a lightly-considered Composer add.