Sql Common Laravel Package

Technical Evaluation

Architecture fit: amphp/sql-common is not a Laravel package and has no Laravel integration surface. It is an internal shared implementation library used by amphp/postgres and amphp/mysql. Laravel’s default database stack is synchronous PDO-based, so this package does not fit a conventional Laravel architecture. It is only relevant if the application runs on an AMPHP/Revolt event loop and uses an AMPHP database driver. Even then, the application should integrate with the driver package, not with sql-common directly.

Integration feasibility: Direct integration is low-value and likely an anti-pattern. There is no service provider, facade, configuration, migration support, or Eloquent adapter. A TPM should treat it as a transitive dependency pulled in by amphp/mysql or amphp/postgres, not as a package to adopt. If async database access is being evaluated, the adoption unit is the driver package; sql-common arrives underneath it.

Technical risk: The main risk is coupling to a low-level shared implementation library with a small public footprint and limited community signal. It has only 13 stars, and its API stability is tied to sibling AMPHP packages rather than a broad user base. Breaking changes or behavioral shifts can propagate through parent driver upgrades. MIT licensing is low-risk. The recent release date suggests maintenance activity, but the bus factor and internal-library status remain concerns. Reaching into its internals would create upgrade and support risk.

Key questions:

• Are we actually running an AMPHP/Revolt event loop in a Laravel context, or is this only theoretical?
• Which parent driver are we evaluating: amphp/mysql or amphp/postgres, and at what version?
• Does our application depend on Eloquent, query builder, transactions, savepoints, or Laravel’s connection lifecycle in ways the async driver cannot satisfy?
• Is amphp/sql-common being pulled transitively, and who owns upgrades when the parent driver changes its constraints?
• Do we need any public API from this package, or are we only seeing it through Composer resolution?
• What is the fallback if the AMPHP maintainer path stalls or a transitive upgrade breaks compatibility?

Integration Approach

Stack fit: Poor for standard Laravel applications. Potential fit is limited to async-first services, long-running workers, streaming/websocket workloads, or high-concurrency I/O-bound paths where an AMPHP database driver is already justified. It should not be used to satisfy ordinary CRUD, reporting, or Eloquent-heavy requirements.

Migration path: Do not migrate to amphp/sql-common as a standalone step. If async database access is a real requirement, evaluate amphp/mysql or amphp/postgres as the adoption unit, pin both parent and transitive versions, and keep the existing PDO path as a fallback. Introduce the async path behind repository interfaces so application code is not coupled to AMPHP-specific types. Run a bounded proof of concept before any migration commitment.

Compatibility: Compatibility is indirect. Laravel version compatibility depends on the async driver and runtime, not this package. Expect constraints around PHP version, AMPHP family versions, and potentially Revolt. Composer conflicts are possible if other packages require different AMPHP versions. Use composer why amphp/sql-common to confirm whether it is transitive and which package controls the constraint. Verify that transaction semantics, connection reset behavior, and error handling meet Laravel operational expectations.

Sequencing:

1. Confirm whether an AMPHP event loop is an actual runtime requirement, not an aspirational one.
2. Inventory database usage, ORM dependencies, transaction patterns, and blocking assumptions.
3. Spike one bounded service against amphp/mysql or amphp/postgres; treat sql-common as an observed transitive dependency.
4. Benchmark throughput, latency, and failure behavior against the current PDO path.
5. Wrap the async driver behind interfaces and define a rollback path.
6. Make a go/no-go decision with an ADR.
7. If approved, pin versions, monitor parent-driver releases, and assign an owner for AMPHP stack upgrades.

Operational Impact

Maintenance: Direct maintenance should be near zero if the package remains transitive. The real maintenance burden is the AMPHP driver stack: version pinning, Composer audits, and upgrade testing when parent drivers change constraints. Because sql-common is a shared implementation library, it may change without a correspondingly obvious application-facing changelog.

Support: This is community open-source with no vendor SLA and a small maintainer base. Escalation is through GitHub issues and pull requests. A TPM should assume limited external support and require internal capability to diagnose driver-level issues. The MIT license is operationally clean, but licensing does not reduce runtime support risk.

Scaling: The package may contribute to scaling only indirectly, as part of an async database stack. It does not make Eloquent asynchronous and does not remove Laravel’s synchronous assumptions. Scaling benefits depend on event-loop behavior, connection pooling, and workload shape. Load testing should cover pool exhaustion, event-loop starvation, and transaction behavior under concurrency.

Failure modes: Likely failure modes include blocking calls stalling the event loop, connection pool exhaustion, transaction leaks, behavioral changes after Composer updates, driver-specific SQL differences, and observability gaps because Laravel’s database listeners and tooling may not see the async path. A transitive upgrade can change behavior without application code changing, so dependency monitoring is required.

Ramp-up: High for a typical Laravel team. Engineers need familiarity with AMPHP, Revolt, non-blocking I/O, async error handling, and the differences between PDO and async driver semantics. A TPM should budget for a spike, training, and a clear ownership model. This is not a quick-win dependency; the default recommendation should be to avoid direct adoption and allow it only as a pinned transitive dependency behind an approved AMPHP database driver.