michaelschiemer/backups/docs-backup-20250731125004/database/master-slave-router.md

Master/Slave Router with Load Balancing

Der Master/Slave Router bietet fortgeschrittene Load Balancing und Monitoring Funktionen für optimale Database-Performance in High-Availability Setups.

✅ Implemented Features

Weighted Selection Algorithm

• Dynamic Weight Adjustment: Gewichte basierend auf aktueller Connection-Last und Response Time
• Load Factor: Reduziert Gewichtung bei hoher Connection-Auslastung (min. 10% Gewichtung)
• Response Time Factor: Bevorzugt schnelle Replicas basierend auf Moving Average
• Minimum Weight Protection: Alle Replicas behalten mindestens 1% Gewichtung

Connection Metrics & Monitoring

• Real-time Connection Counting: Tracking aktiver Connections pro Replica
• Response Time History: Moving Average der letzten 100 Response Times pro Replica
• Health Monitoring: Automatische Health Checks mit konfigurierbaren Intervallen
• Comprehensive Statistics: Detaillierte Routing-Statistiken für Monitoring

Load Balancing Strategies

• WEIGHTED: Intelligente gewichtete Auswahl mit Performance-Adjustierung
• LEAST_CONNECTIONS: Auswahl der Replica mit wenigsten aktiven Connections
• RESPONSE_TIME: Auswahl basierend auf bester durchschnittlicher Response Time
• ROUND_ROBIN: Traditionelle zyklische Auswahl
• RANDOM: Zufällige Auswahl für gleichmäßige Verteilung

Configuration

DriverConfig Extension

public readonly class DriverConfig
{
    public function __construct(
        // ... existing parameters ...
        public int $weight = 100,           // Load balancing weight
        public int $maxConnections = 100    // Max concurrent connections
    ) {}
}

ReadWriteConfig Methods

$config->getConnectionWeight($index);     // Get weight for replica
$config->getMaxConnections($index);      // Get max connections for replica
$config->getAllWeights();                // Get all weights indexed by position

Usage Examples

Weighted Load Balancing Setup

$readWriteConfig = new ReadWriteConfig(
    enabled: true,
    readConnections: [
        DriverConfig::fromArray([
            'host' => 'replica1.db.local',
            'weight' => 100,           // Normal weight
            'max_connections' => 50
        ]),
        DriverConfig::fromArray([
            'host' => 'replica2.db.local', 
            'weight' => 200,           // 2x higher capacity
            'max_connections' => 100
        ]),
        DriverConfig::fromArray([
            'host' => 'replica3.db.local',
            'weight' => 50,            // Lower capacity
            'max_connections' => 25
        ])
    ],
    loadBalancingStrategy: LoadBalancingStrategy::WEIGHTED
);

Connection Tracking

// Router tracks connections automatically
$replica = $router->route($sql);

// Manual connection management (if needed)
$router->incrementConnectionCount($replica);
// ... use connection ...
$router->decrementConnectionCount($replica);

// Track query performance
$startTime = microtime(true);
$result = $replica->query($sql);
$responseTime = (microtime(true) - $startTime) * 1000;
$router->recordResponseTime($replica, $responseTime);

Monitoring & Statistics

Comprehensive Routing Statistics

$stats = $router->getRoutingStatistics();
// Returns:
[
    'total_replicas' => 3,
    'healthy_replicas' => 2,
    'load_balancing_strategy' => 'WEIGHTED',
    'sticky_sessions' => false,
    'replica_details' => [
        0 => [
            'healthy' => true,
            'current_connections' => 15,
            'max_connections' => 50,
            'load_percentage' => 30.0,
            'config_weight' => 100,
            'adjusted_weight' => 85,      // Reduced due to load
            'weight_adjustment_factor' => 0.85,
            'avg_response_time_ms' => 120.5,
            'total_queries' => 1540,
            'failed_queries' => 3,
            'success_rate' => 99.81,
            'recent_response_samples' => 100
        ],
        // ... other replicas
    ]
]

Weight Distribution Analysis

$distribution = $router->getWeightDistribution();
// Returns current weight distribution for healthy replicas:
[
    0 => [
        'config_weight' => 100,
        'adjusted_weight' => 85,
        'current_connections' => 15,
        'avg_response_time' => 120.5,
        'weight_percentage' => 35.2    // % of total weight
    ],
    // ... other healthy replicas
]

Performance Benefits

Intelligent Load Distribution

• Load-based Adjustment: Überlastete Replicas erhalten weniger Traffic
• Performance-based Routing: Schnelle Replicas werden bevorzugt
• Connection Pool Optimization: Verhindert Connection-Überlastung
• Failover Protection: Automatischer Fallback bei Replica-Ausfallen

Monitoring Integration

• Real-time Metrics: Live-Statistiken für Performance-Monitoring
• Health Tracking: Continuous Health Checks mit Response Time Tracking
• Success Rate Monitoring: Tracking von Query Success/Failure Rates
• Load Analysis: Detaillierte Load-Verteilung für Capacity Planning

Weight Calculation Algorithm

// Dynamic weight adjustment based on current performance
$loadFactor = max(0.1, 1 - ($currentConnections / $maxConnections));
$responseFactor = max(0.1, min(1.0, 100 / $avgResponseTime));
$adjustedWeight = max(1, round($baseWeight * $loadFactor * $responseFactor));

Factors:

• Load Factor: 10-100% basierend auf Connection-Auslastung
• Response Factor: 10-100% basierend auf Response Time (100ms = Baseline)
• Minimum Protection: Jede Replica behält mindestens 10% Gewichtung

Testing

Comprehensive test suite covering:

• ✅ Weighted selection distribution accuracy
• ✅ Load factor calculation with edge cases
• ✅ Response time factor adjustment
• ✅ Connection counting accuracy
• ✅ Response time history window management
• ✅ Load balancing strategy logic
• ✅ Routing statistics generation

All tests pass with 78 assertions validating the complete implementation.

Migration from Simple Round Robin

// Vorher: Simple Round Robin
$router = new MasterSlaveRouter(
    $master, 
    $replicas, 
    new ReadWriteConfig(
        enabled: true,
        loadBalancingStrategy: LoadBalancingStrategy::ROUND_ROBIN
    )
);

// Nachher: Intelligent Weighted Balancing
$router = new MasterSlaveRouter(
    $master,
    $replicas,
    new ReadWriteConfig(
        enabled: true,
        readConnections: $configsWithWeights,
        loadBalancingStrategy: LoadBalancingStrategy::WEIGHTED
    )
);

Die Implementierung bietet vollständige Backward-Compatibility mit bestehenden Setups.