Weave Code
Db Connection Laravel Package
hyperf/db-connection
hyperf/db-connection provides coroutine-safe database connections and pooling for Hyperf applications. It manages PDO connections, supports transactions, reconnection, and pool configuration, helping build high-performance, concurrent PHP services with MySQL and other databases.
hyperf/db-connection integrates hyperf/database with Hyperf’s coroutine-native connection pool, providing efficient, reusable database connections. It supplies the Db facade and connection resolver used across Hyperf, so queries and transactions run safely within coroutines without creating a new PDO connection for every request.
- Coroutine-safe pooled connections with configurable pool sizing and timeouts
Dbfacade and connection resolver for multiple named connections- Transaction support scoped to the current coroutine/request
- Integration with Hyperf’s database and model layers
- Framework-native configuration and connection lifecycle management
Frequently asked questions about Db Connection
- How do I install hyperf/db-connection?
- Install it with Composer by running composer require hyperf/db-connection in your Hyperf project. In most cases it is pulled in automatically as a dependency of hyperf/database, so you rarely need to require it directly. After installing, define your connections in config/autoload/databases.php and make sure the config provider is registered in config/autoload/annotations.php or the skeleton's default config. Then restart your Swoole or Swow server so the pool is built at boot.
- Is hyperf/db-connection compatible with Laravel?
- No, this is a Hyperf component, not a Laravel package, and it cannot be dropped into a Laravel application. It deliberately mimics Laravel's database manager API so that Db::connection('name'), the query builder, and connection config keys feel familiar to Laravel developers. If you are building a Laravel app you should use illuminate/database instead, but the concepts translate almost one to one.
- How do I configure the connection pool size?
- Each connection in config/autoload/databases.php accepts a pool array with keys such as min_connections, max_connections, connect_timeout, wait_timeout, and heartbeats. Set min_connections to keep a small number of warm connections ready and max_connections to cap concurrency per worker. Remember that every Swoole worker process builds its own pool, so your total connections equal max_connections multiplied by the worker count, which must stay below the database server's connection limit.
- How does read/write splitting work in hyperf/db-connection?
- You define the primary connection as usual and add a read section containing one or more read-only hosts, and the manager routes write statements to the primary while distributing reads across the replicas. This happens transparently when you use the query builder or models through the default connection. Keep in mind that replica lag is not handled for you, so wrap read-after-write flows in an explicit connection to the primary when consistency matters.
- How do I run a query with hyperf/db-connection?
- Use the Db facade or the injected ConnectionFactory and call Db::connection('default') to obtain a connection, then chain query builder calls such as table(), select(), or insert(). The component only handles connection management, so the fluent builder and models come from hyperf/database, which sits on top of it. Multiple named connections defined in databases.php are all reachable with Db::connection('other').
- How does reconnection work when the database connection drops?
- The pool detects broken or timed-out connections and discards them rather than handing them back to your code, and heartbeats can be configured to keep idle connections alive. You can also force a fresh connection at runtime with Db::reconnect('default') or the equivalent on the connection instance. Because connections are checked out per coroutine, a dropped socket affects only the coroutine holding it and the next checkout builds a new one.
- Is hyperf/db-connection coroutine-safe?
- Yes, connection safety is the main reason the component exists. Each coroutine checks out its own connection from the pool and returns it when the coroutine finishes or the connection is released, so two coroutines never share the same underlying PDO handle. This is what makes it safe to run concurrent queries inside Swoole or Swow workers without connection state leaking between requests.
- How do I test code that uses hyperf/db-connection?
- Run your tests inside the Hyperf coroutine runtime using hyperf/testing, since pool checkout depends on coroutine context being available. For unit tests, mock the connection factory or ConnectionInterface rather than opening real sockets, or point the config at a throwaway SQLite or MySQL schema. Integration tests should assert that connections are released properly so pool exhaustion bugs surface early.
- What pool settings should I use in production?
- Start with a max_connections close to the concurrency you actually expect per worker, not an arbitrarily large number, and size min_connections to avoid a cold-start burst. Set connect_timeout and wait_timeout so a slow database fails fast instead of stalling coroutines, and enable heartbeats if your infrastructure closes idle TCP connections. Monitor pool wait times and database connection counts together, because tuning only one side usually moves the bottleneck rather than removing it.
- What is the difference between hyperf/db-connection and hyperf/database?
- hyperf/db-connection is the lower layer: it manages connection objects and coroutine-safe pools, read/write routing, and reconnection. hyperf/database builds on it to provide the query builder, schema builder, and model layer you actually code against. In practice you install hyperf/database and get db-connection automatically, but knowing the split helps when you need to tweak pooling or replace the connection layer.
Weaver
How can I help you explore Laravel packages today?