PHP Luminova: Configuration for Database Fallback Connections

The Database configuration class supports defining optional shard or backup database servers. These servers act as fallbacks if the primary connection fails. Each backup must be defined as a nested associative array, where the keys specify standard connection parameters such as host, port, username, password, etc.

This enables automatic failover or sharded access based on region, user ID, or custom logic.

Class Definition

• Class namespace: \App\Config\Database
• File path: /app/Config/Database.php
• Parent class: \Luminova\Base\CoreDatabase

Properties

connectionSharding

Enable or disable connection-level database sharding.

When set to true, the application will attempt to route database connections based on shard configurations defined by the shard location identifier getShardServerKey. This allows for distributing database load across multiple shard serversfor better scalability and isolation (e.g., multi-tenant or geo-based setups).

public static bool $connectionSharding = false;

If false, all connections will be made to the default primary database configuration.

shardFallbackOnError

Whether to fallback to an available backup server if the selected shard is unreachable.

When enabled, the system will attempt to use a backup configuration from $databaseServers if the main shard server fails or is offline.

public static bool $shardFallbackOnError = false;

This is useful in distributed environments where high availability is required.

databaseServers

List of backup database configurations.

This serves two purposes:

• Provides alternative connections for sharded environments when a shard is unavailable.
• Acts as a failover mechanism for non-sharded environments when the main database fails.

Each backup should follow the same structure as the primary configuration.

protected static array<string,array<string,mixed>> $databaseServers = [];

Nested associative array with each database configuration keys and values.

Supported Configuration Keys

The following keys are supported when defining database connection settings. These settings apply to both .env configuration and the App\Config\Database class.

The default connection values can be defined in your .env file or directly in the App\Config\Database class.Example:

Copy

database.connection=pdo
database.pdo.version=mysql
database.host=127.0.0.1
database.port=3306
database.username=root
database.password=secret
database.name=my_database

Example:

// /app/Config/Database.php

namespace App\Config;

use Luminova\Core\CoreDatabase;

class Database extends CoreDatabase
{
    protected static array<string,array<string,mixed>> $databaseServers = [
        'DEFAULT' => [
            'host' => 'main.db.server',
            'port' => 3306,
            'database' => 'main_db',
            'username' => 'user_main',
            'password' => 'secret',
            'charset' => 'utf8mb4',
            'version' => 'mysql',
            'socket' => false,
            'socket_path' => '',
            'sqlite_path' => '', // Only used if version is sqlite
        ],
        'NG' => [
            'host' => 'ng.db.server',
            // ...
        ],
        'US' => [
            'host' => 'us.db.server',
            // ...
        ]
    ];
}

Always set the default connection as first index before other connection servers.