Sql Common Laravel Package

Product Decisions This Supports

• Not a direct build-vs-buy line item — it's plumbing. amphp/sql-common is the shared implementation layer beneath amphp/mysql and amphp/postgres (connection pooling, connection/config abstractions, query results, transactions). Product teams don't adopt it; they adopt one of the parent drivers, and this arrives transitively. Treat any evaluation as a proxy for "how healthy is the async SQL stack we're standardizing on?"
• Enables a specific architecture bet: long-running, concurrent PHP services. If the roadmap includes websocket servers, high-throughput queue consumers, real-time APIs, or fan-out aggregation services on AMPHP (or frameworks built on it, e.g. Revolt/AMPHP-based runtimes), connection pooling and non-blocking query execution are the enabling capability. That's a platform decision, not a feature decision.
• Shapes reliability and performance SLOs. Pool sizing, connection lifecycle, query cancellation/timeouts, and transaction semantics determine how the service behaves under saturation. PMs should care because these show up as customer-visible latency and 5xx rates, not as library choices.
• Informs the runtime standardization decision. Choosing AMPHP drivers constrains you away from a plain PDO/Laravel DB facade model in the same process. That has downstream consequences for hiring, on-call runbooks, observability tooling, and how much of the existing Eloquent-based codebase is reusable.
• Roadmap gating for "async migration" work. If a roadmap item depends on concurrent DB access, this package family is on the critical path; if it doesn't, this is noise and should be explicitly deprioritized to avoid architecture tourism.

When to Consider This Package

Consider the parent drivers (and therefore this package) when:

• You are building or maintaining a long-lived PHP process (AMPHP, Revolt, RoadRunner/Swoole-adjacent, websocket or worker daemons) that must issue concurrent MySQL/PostgreSQL queries without blocking the event loop.
• You need connection pooling with bounded concurrency, per-query timeouts, and cancellation — behaviors a blocking driver cannot give you in-process.
• You are already standardized on the AMPHP ecosystem and want one consistent SQL abstraction across MySQL and PostgreSQL rather than two divergent code paths.
• Your team has, or is willing to build, async PHP fluency and can own the operational complexity (pool tuning, backpressure, graceful shutdown).

Look elsewhere when:

• The product is a conventional Laravel request/response application. PDO/the DB facade, Eloquent, and the existing queue workers already meet the need; adding an async driver adds a second data-access paradigm for no user-facing gain.
• You depend on Eloquent/ORM features, migrations, or the broader Laravel database tooling — this package is a driver layer, not an ORM, and integrating it means hand-rolling what the framework gives you free.
• Vendor support, SOC 2 evidence, or a commercial SLA is a procurement requirement. MIT with a small maintainer base won't satisfy that.
• Your resilience model assumes a large, well-staffed dependency. 13 stars is not a red flag for an internal-style shared library, but it is a signal that you are one of very few consumers and the bus factor is low.
• You need capabilities outside the drivers' scope (read/write splitting, advanced failover, ORM-level query building). Evaluate whether the gap is a dealbreaker before committing the architecture.

Practical guidance: never add amphp/sql-common as a direct dependency. Depend on amphp/mysql or amphp/postgres, pin versions, and assume the shared internals may change between minor releases. Evaluate ecosystem health at the driver level, not here.

How to Pitch It (Stakeholders)

To executives: This is a free (MIT), low-level component that sits underneath two open-source database drivers. It is not a product we buy or a service we run — it's a transitive dependency that only becomes relevant if we commit to a particular performance architecture (long-running PHP services handling many concurrent database calls). There is no license cost and no direct commercial exposure. The real decision on the table is whether that architecture is worth the investment; this package is a consequence of that decision, not a reason for it. The risk to flag is concentration: a very small maintainer community means we would be a disproportionately large consumer, so any commitment should come with our own integration test coverage and a fallback plan.

To engineering: Don't take a direct dependency — pull it in via amphp/mysql or amphp/postgres and let Composer resolve it. Pin versions and treat the internal API as unstable across minor releases. What you get is a consistent pooling, connection, transaction, and query-result model shared across both engines, which reduces the cost of supporting MySQL and PostgreSQL side by side. What you take on is event-loop-native data access: pool sizing, backpressure, cancellation semantics, and graceful shutdown all become our responsibility, and none of it composes with Eloquent or the framework's database layer. If we go this route, we should budget for an internal abstraction boundary around the driver so we can swap it out without rewriting product code, plus load tests that exercise pool exhaustion and query timeout paths before we put customer traffic behind it.

Recommendation: Do not treat amphp/sql-common as a decision item. Decide on the async runtime and the parent driver on their merits; adopt this implicitly, wrap it, and re-evaluate if the maintainer base or release cadence deteriorates.