Multi-Pool Configuration

Purpose and Scope

This document explains how to configure multiple named Redis connection pools within a single Hyperf application. Multi-pool configuration enables applications to maintain separate Redis connections for different purposes (e.g., default operations, caching, session storage, queue management) with independent connection settings.

For information about the basic Hyperf integration mechanism, see Hyperf Integration. For details about how the Redis Factory manages pool instances, see Redis Factory.

---

Configuration File Structure

Multi-pool configuration is defined in Hyperf's standard Redis configuration file, typically located at config/autoload/redis.php. Each pool is defined as a top-level key in the configuration array.

Basic Structure

Sources: src/RedisFactory.php21-25

---

Configuration Loading and Pool Initialization

Factory Initialization Flow

The RedisFactory constructor iterates through the redis configuration array, creating a RedisProxy instance for each configured pool name. Each proxy is stored in the $proxies property indexed by its pool name.

Sources: src/RedisFactory.php19-26 src/RedisProxy.php11-16

---

Pool Configuration Architecture

Sources: src/RedisFactory.php1-37 src/RedisProxy.php1-17

---

Accessing Named Pools

Using RedisFactory

The primary method to access named pools is through the RedisFactory::get() method:

The get() method retrieves the RedisProxy instance for the specified pool name. If the pool name doesn't exist in the configuration, it throws an InvalidRedisProxyException.

Sources: src/RedisFactory.php28-36

---

Pool Name Propagation

The pool name is stored in the $poolName property inherited from the Redis base class. When RedisProxy is constructed, it calls the parent constructor and then sets the poolName property to the specified value. This pool name is used throughout the connection lifecycle to identify which connection pool to use.

Sources: src/RedisProxy.php11-16

---

Common Multi-Pool Patterns

Separation by Purpose

Pool Name	Purpose	Typical Configuration
default	General application operations	Moderate pool size (10-20 connections), standard timeout
cache	Dedicated caching layer	Large pool size (50+ connections), longer max_idle_time
session	User session storage	Medium pool size (20-30 connections), shorter wait_timeout
queue	Job queue backend	Moderate pool size (10-20 connections), longer connect_timeout
locks	Distributed locking	Small pool size (5-10 connections), short wait_timeout

Physical Separation

Pools can point to different Redis servers or different databases on the same server:

Different Servers:

Same Server, Different Databases:

Sources: src/RedisFactory.php21-25

---

Configuration Options Per Pool

Connection Settings

Option	Type	Description
host	string	Redis server hostname or IP address
port	int	Redis server port (default: 6379)
auth	string|null	Redis password for authentication
db	int	Redis database number (0-15)
timeout	float	Connection timeout in seconds
reserved	mixed	Reserved for future use
retry_interval	int	Retry interval in milliseconds
read_timeout	float	Read timeout in seconds

Pool Settings

Each pool has a nested pool configuration array:

Option	Type	Description
min_connections	int	Minimum number of persistent connections
max_connections	int	Maximum number of connections in the pool
connect_timeout	float	Timeout for establishing new connections
wait_timeout	float	Timeout for waiting when pool is exhausted
heartbeat	float	Heartbeat interval (-1 to disable)
max_idle_time	float	Maximum idle time before connection is closed

Sources: Configuration examples based on standard Hyperf Redis pool configuration

---

Error Handling

Invalid Pool Names

When requesting a pool that doesn't exist in the configuration, the factory throws an exception:

The validation occurs in the get() method, which checks if the requested pool exists in the $proxies array.

Sources: src/RedisFactory.php28-36

---

Integration with Dependency Injection

Service Provider Configuration

The ConfigProvider ensures that the custom RedisPool class is used instead of Hyperf's default pool implementation:

This binding allows the Hypervel Redis package to use custom connection pools that create RedisConnection instances with Laravel-compatible transformations enabled.

Sources: src/ConfigProvider.php14-16

---

Complete Multi-Pool Setup Example

Usage in Application

Sources: src/RedisFactory.php1-37 src/RedisProxy.php1-17

---

Performance Considerations

Pool Sizing Guidelines

Minimum Connections: Should be set based on typical concurrent usage to avoid connection creation overhead during normal operation.

Maximum Connections: Should account for peak load. Setting this too low causes requests to wait (wait_timeout), while setting it too high consumes unnecessary resources.

Wait Timeout: Balance between user experience (how long users wait) and resource protection (preventing thundering herd on exhausted pools).

Pool Isolation Benefits

1. Resource Isolation: Heavy cache operations don't impact session storage performance
2. Failure Isolation: Issues with one Redis server don't affect other pools
3. Configuration Flexibility: Different pools can have optimized settings for their use case
4. Monitoring Granularity: Track metrics per pool to identify bottlenecks

Sources: Based on connection pool architecture in src/RedisFactory.php1-37