Database Configuration

Purpose and Scope

This document explains the database configuration file used by the Hypervel Testbench environment. The configuration is defined in workbench/config/database.php and provides database connection settings for both traditional SQL databases (SQLite) and Redis for caching and queue operations.

For information about using database migrations in tests, see Database Migrations in Tests. For general application configuration, see Application Configuration. For environment variable setup, see Testbench Configuration.

Sources: workbench/config/database.php1-38

---

Configuration File Overview

The database configuration file returns an array with three main sections:

Section	Purpose	Default Value
default	Specifies the default database connection name	'sqlite'
connections	Defines available database connections	SQLite only
redis	Configures Redis connections and pooling	Default connection with pooling

The configuration is optimized for testing scenarios, using an in-memory SQLite database as the default connection to ensure fast, isolated test execution without external database dependencies.

Diagram: Database Configuration Structure

Sources: workbench/config/database.php7-37

---

Default Database Connection

The default database connection is specified at workbench/config/database.php8:

This setting determines which connection from the connections array will be used by default. The value is read from the DB_CONNECTION environment variable, falling back to 'sqlite' if not set.

Environment Variable:

• DB_CONNECTION: Override the default connection (default: 'sqlite')

Sources: workbench/config/database.php8

---

SQLite Connection Configuration

The SQLite connection is configured as an in-memory database, ideal for fast, isolated testing:

Configuration Options

Option	Value	Description
driver	'sqlite'	Specifies the SQLite database driver
database	':memory:'	Uses an in-memory database that is created and destroyed per test
prefix	''	Table name prefix (empty for tests)
foreign_key_constraints	env('DB_FOREIGN_KEYS', true)	Enables foreign key constraint enforcement

In-Memory Database Benefits

Using :memory: as the database path provides several advantages for testing:

1. Speed: No disk I/O operations, all data is stored in RAM
2. Isolation: Each test gets a fresh database instance
3. No Cleanup Required: Database is automatically destroyed when the connection closes
4. No External Dependencies: No need to configure external database servers

Foreign Key Constraints

Foreign key constraint enforcement is enabled by default at workbench/config/database.php14 This ensures referential integrity is maintained in tests, catching potential issues with database relationships. The behavior can be disabled via the DB_FOREIGN_KEYS environment variable if needed for specific test scenarios.

Environment Variables:

• DB_FOREIGN_KEYS: Enable/disable foreign key constraints (default: true)

Sources: workbench/config/database.php10-15

---

Redis Configuration

Redis is configured with connection pooling support for optimal performance in the Hyperf async environment. The configuration is split into two sections: global options and connection-specific settings.

Diagram: Redis Configuration Hierarchy

Sources: workbench/config/database.php17-36

Redis Global Options

The global options are defined at workbench/config/database.php18-20:

The prefix setting prepends a namespace to all Redis keys to prevent collisions when multiple applications share the same Redis instance. The default prefix is generated from the application name using Hypervel\Support\Str::slug(), resulting in a format like hypervel_database_.

Environment Variables:

• REDIS_PREFIX: Override the Redis key prefix
• APP_NAME: Application name used in prefix generation (default: 'hypervel')

Sources: workbench/config/database.php18-20 workbench/config/database.php5

Redis Default Connection

The default Redis connection is configured at workbench/config/database.php22-35:

Setting	Environment Variable	Default	Description
host	REDIS_HOST	'localhost'	Redis server hostname
auth	REDIS_AUTH	null	Redis authentication password
port	REDIS_PORT	6379	Redis server port
db	REDIS_DB	0	Redis database index

All values are configurable via environment variables, allowing easy adaptation to different testing or production environments.

Sources: workbench/config/database.php22-35

---

Connection Pool Configuration

The Redis connection pool is critical for Hyperf's coroutine-based architecture. Pool settings are defined at workbench/config/database.php27-34:

Pool Parameters

Parameter	Value	Description
min_connections	1	Minimum number of connections maintained in the pool
max_connections	10	Maximum number of concurrent connections allowed
connect_timeout	10.0	Seconds to wait when establishing a new connection
wait_timeout	3.0	Seconds to wait for an available connection from the pool
heartbeat	-1	Heartbeat interval in seconds (-1 disables heartbeat)
max_idle_time	env('REDIS_MAX_IDLE_TIME', 60)	Seconds before an idle connection is closed

Connection Pool Behavior

Diagram: Connection Pool Lifecycle

Sources: workbench/config/database.php27-34

Pool Tuning Considerations

1. min_connections=1: Maintains a single persistent connection for low-load scenarios, reducing connection overhead
2. max_connections=10: Limits concurrent connections to prevent overwhelming the Redis server
3. connect_timeout=10.0: Generous timeout for establishing connections, suitable for test environments
4. wait_timeout=3.0: Short wait time to quickly fail if the pool is exhausted
5. heartbeat=-1: Disabled to reduce unnecessary traffic in testing environments
6. max_idle_time=60: Closes idle connections after 60 seconds to conserve resources

Environment Variables:

• REDIS_MAX_IDLE_TIME: Maximum seconds a connection can remain idle (default: 60)

Sources: workbench/config/database.php27-34

---

Environment Variable Reference

Diagram: Environment Variable Flow

Complete Environment Variable List:

Variable	Type	Default	Description	Line Reference
DB_CONNECTION	string	'sqlite'	Default database connection name	8
DB_FOREIGN_KEYS	boolean	true	Enable SQLite foreign key constraints	14
APP_NAME	string	'hypervel'	Application name for Redis prefix	19
REDIS_PREFIX	string	{slug}_database_	Redis key prefix	19
REDIS_HOST	string	'localhost'	Redis server hostname	23
REDIS_AUTH	string/null	null	Redis authentication password	24
REDIS_PORT	integer	6379	Redis server port	25
REDIS_DB	integer	0	Redis database index	26
REDIS_MAX_IDLE_TIME	float	60	Maximum idle time for pooled connections	33

Sources: workbench/config/database.php8 workbench/config/database.php14 workbench/config/database.php19 workbench/config/database.php23-26 workbench/config/database.php33

---

Usage in Tests

The database configuration is automatically loaded when TestCase creates the application instance. Tests can interact with both SQLite and Redis connections without additional configuration.

SQLite Usage

The in-memory SQLite database is automatically available for tests that use the HandlesDatabases trait (see HandlesDatabases Trait). Migrations run against this database are automatically destroyed during test teardown.

Redis Usage

Redis connections from the pool can be accessed via the application container. The connection pool ensures that concurrent test operations (when using coroutines) have access to multiple connections without blocking.

Sources: workbench/config/database.php1-38