includes/libs/rdbms/lbfactory/LBFactoryMulti.php

   1 <?php
   2 /**
   3  * Advanced generator of database load balancing objects for database farms.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup Database
  22  */
  23
  24 namespace Wikimedia\Rdbms;
  25
  26 use InvalidArgumentException;
  27
  28 /**
  29  * A multi-database, multi-master factory for Wikimedia and similar installations.
  30  * Ignores the old configuration globals.
  31  *
  32  * @ingroup Database
  33  */
  34 class LBFactoryMulti extends LBFactory {
  35         /** @var array A map of database names to section names */
  36         private $sectionsByDB;
  37
  38         /**
  39          * @var array A 2-d map. For each section, gives a map of server names to
  40          * load ratios
  41          */
  42         private $sectionLoads;
  43
  44         /**
  45          * @var array[] Server info associative array
  46          * @note The host, hostName and load entries will be overridden
  47          */
  48         private $serverTemplate;
  49
  50         // Optional settings
  51
  52         /** @var array A 3-d map giving server load ratios for each section and group */
  53         private $groupLoadsBySection = [];
  54
  55         /** @var array A 3-d map giving server load ratios by DB name */
  56         private $groupLoadsByDB = [];
  57
  58         /** @var array A map of hostname to IP address */
  59         private $hostsByName = [];
  60
  61         /** @var array A map of external storage cluster name to server load map */
  62         private $externalLoads = [];
  63
  64         /**
  65          * @var array A set of server info keys overriding serverTemplate for
  66          * external storage
  67          */
  68         private $externalTemplateOverrides;
  69
  70         /**
  71          * @var array A 2-d map overriding serverTemplate and
  72          * externalTemplateOverrides on a server-by-server basis. Applies to both
  73          * core and external storage
  74          */
  75         private $templateOverridesByServer;
  76
  77         /** @var array A 2-d map overriding the server info by section */
  78         private $templateOverridesBySection;
  79
  80         /** @var array A 2-d map overriding the server info by external storage cluster */
  81         private $templateOverridesByCluster;
  82
  83         /** @var array An override array for all master servers */
  84         private $masterTemplateOverrides;
  85
  86         /**
  87          * @var array|bool A map of section name to read-only message. Missing or
  88          * false for read/write
  89          */
  90         private $readOnlyBySection = [];
  91
  92         /** @var array Load balancer factory configuration */
  93         private $conf;
  94
  95         /** @var LoadBalancer[] */
  96         private $mainLBs = [];
  97
  98         /** @var LoadBalancer[] */
  99         private $extLBs = [];
 100
 101         /** @var string */
 102         private $loadMonitorClass = 'LoadMonitor';
 103
 104         /** @var string */
 105         private $lastDomain;
 106
 107         /** @var string */
 108         private $lastSection;
 109
 110         /** @var int */
 111         private $maxLag = self::MAX_LAG_DEFAULT;
 112
 113         /** @var int Default 'maxLag' when unspecified */
 114         const MAX_LAG_DEFAULT = 10;
 115
 116         /**
 117          * @see LBFactory::__construct()
 118          *
 119          * Template override precedence (highest => lowest):
 120          *   - templateOverridesByServer
 121          *   - masterTemplateOverrides
 122          *   - templateOverridesBySection/templateOverridesByCluster
 123          *   - externalTemplateOverrides
 124          *   - serverTemplate
 125          * Overrides only work on top level keys (so nested values will not be merged).
 126          *
 127          * Server configuration maps should be of the format Database::factory() requires.
 128          * Additionally, a 'max lag' key should also be set on server maps, indicating how stale the
 129          * data can be before the load balancer tries to avoid using it. The map can have 'is static'
 130          * set to disable blocking  replication sync checks (intended for archive servers with
 131          * unchanging data).
 132          *
 133          * @param array $conf Parameters of LBFactory::__construct() as well as:
 134          *   - sectionsByDB                Map of database names to section names.
 135          *   - sectionLoads                2-d map. For each section, gives a map of server names to
 136          *                                 load ratios. For example:
 137          *                                 [
 138          *                                     'section1' => [
 139          *                                         'db1' => 100,
 140          *                                         'db2' => 100
 141          *                                     ]
 142          *                                 ]
 143          *   - serverTemplate              Server configuration map intended for Database::factory().
 144          *                                 Note that "host", "hostName" and "load" entries will be
 145          *                                 overridden by "sectionLoads" and "hostsByName".
 146          *   - groupLoadsBySection         3-d map giving server load ratios for each section/group.
 147          *                                 For example:
 148          *                                 [
 149          *                                     'section1' => [
 150          *                                         'group1' => [
 151          *                                             'db1' => 100,
 152          *                                             'db2' => 100
 153          *                                         ]
 154          *                                     ]
 155          *                                 ]
 156          *   - groupLoadsByDB              3-d map giving server load ratios by DB name.
 157          *   - hostsByName                 Map of hostname to IP address.
 158          *   - externalLoads               Map of external storage cluster name to server load map.
 159          *   - externalTemplateOverrides   Set of server configuration maps overriding
 160          *                                 "serverTemplate" for external storage.
 161          *   - templateOverridesByServer   2-d map overriding "serverTemplate" and
 162          *                                 "externalTemplateOverrides" on a server-by-server basis.
 163          *                                 Applies to both core and external storage.
 164          *   - templateOverridesBySection  2-d map overriding the server configuration maps by section.
 165          *   - templateOverridesByCluster  2-d map overriding the server configuration maps by external
 166          *                                 storage cluster.
 167          *   - masterTemplateOverrides     Server configuration map overrides for all master servers.
 168          *   - loadMonitorClass            Name of the LoadMonitor class to always use.
 169          *   - maxLag                      Avoid replica DBs with more lag than this many seconds.
 170          *   - readOnlyBySection           A map of section name to read-only message.
 171          *                                 Missing or false for read/write.
 172          */
 173         public function __construct( array $conf ) {
 174                 parent::__construct( $conf );
 175
 176                 $this->conf = $conf;
 177                 $required = [ 'sectionsByDB', 'sectionLoads', 'serverTemplate' ];
 178                 $optional = [ 'groupLoadsBySection', 'groupLoadsByDB', 'hostsByName',
 179                         'externalLoads', 'externalTemplateOverrides', 'templateOverridesByServer',
 180                         'templateOverridesByCluster', 'templateOverridesBySection', 'masterTemplateOverrides',
 181                         'readOnlyBySection', 'maxLag', 'loadMonitorClass' ];
 182
 183                 foreach ( $required as $key ) {
 184                         if ( !isset( $conf[$key] ) ) {
 185                                 throw new InvalidArgumentException( __CLASS__ . ": $key is required." );
 186                         }
 187                         $this->$key = $conf[$key];
 188                 }
 189
 190                 foreach ( $optional as $key ) {
 191                         if ( isset( $conf[$key] ) ) {
 192                                 $this->$key = $conf[$key];
 193                         }
 194                 }
 195         }
 196
 197         /**
 198          * @param bool|string $domain
 199          * @return string
 200          */
 201         private function getSectionForDomain( $domain = false ) {
 202                 if ( $this->lastDomain === $domain ) {
 203                         return $this->lastSection;
 204                 }
 205                 list( $dbName, ) = $this->getDBNameAndPrefix( $domain );
 206                 $section = $this->sectionsByDB[$dbName] ?? 'DEFAULT';
 207                 $this->lastSection = $section;
 208                 $this->lastDomain = $domain;
 209
 210                 return $section;
 211         }
 212
 213         /**
 214          * @param bool|string $domain
 215          * @return LoadBalancer
 216          */
 217         public function newMainLB( $domain = false ) {
 218                 list( $dbName, ) = $this->getDBNameAndPrefix( $domain );
 219                 $section = $this->getSectionForDomain( $domain );
 220                 $groupLoads = $this->groupLoadsByDB[$dbName] ?? [];
 221
 222                 if ( isset( $this->groupLoadsBySection[$section] ) ) {
 223                         $groupLoads = array_merge_recursive(
 224                                 $groupLoads, $this->groupLoadsBySection[$section] );
 225                 }
 226
 227                 $readOnlyReason = $this->readOnlyReason;
 228                 // Use the LB-specific read-only reason if everything isn't already read-only
 229                 if ( $readOnlyReason === false && isset( $this->readOnlyBySection[$section] ) ) {
 230                         $readOnlyReason = $this->readOnlyBySection[$section];
 231                 }
 232
 233                 $template = $this->serverTemplate;
 234                 if ( isset( $this->templateOverridesBySection[$section] ) ) {
 235                         $template = $this->templateOverridesBySection[$section] + $template;
 236                 }
 237
 238                 return $this->newLoadBalancer(
 239                         $template,
 240                         $this->sectionLoads[$section],
 241                         $groupLoads,
 242                         $readOnlyReason
 243                 );
 244         }
 245
 246         /**
 247          * @param DatabaseDomain|string|bool $domain Domain ID, or false for the current domain
 248          * @return LoadBalancer
 249          */
 250         public function getMainLB( $domain = false ) {
 251                 $section = $this->getSectionForDomain( $domain );
 252                 if ( !isset( $this->mainLBs[$section] ) ) {
 253                         $this->mainLBs[$section] = $this->newMainLB( $domain );
 254                 }
 255
 256                 return $this->mainLBs[$section];
 257         }
 258
 259         public function newExternalLB( $cluster ) {
 260                 if ( !isset( $this->externalLoads[$cluster] ) ) {
 261                         throw new InvalidArgumentException( __METHOD__ . ": Unknown cluster \"$cluster\"" );
 262                 }
 263                 $template = $this->serverTemplate;
 264                 if ( $this->externalTemplateOverrides ) {
 265                         $template = $this->externalTemplateOverrides + $template;
 266                 }
 267                 if ( isset( $this->templateOverridesByCluster[$cluster] ) ) {
 268                         $template = $this->templateOverridesByCluster[$cluster] + $template;
 269                 }
 270
 271                 return $this->newLoadBalancer(
 272                         $template,
 273                         $this->externalLoads[$cluster],
 274                         [],
 275                         $this->readOnlyReason
 276                 );
 277         }
 278
 279         public function getExternalLB( $cluster ) {
 280                 if ( !isset( $this->extLBs[$cluster] ) ) {
 281                         $this->extLBs[$cluster] = $this->newExternalLB( $cluster );
 282                 }
 283
 284                 return $this->extLBs[$cluster];
 285         }
 286
 287         public function getAllMainLBs() {
 288                 $lbs = [];
 289                 foreach ( $this->sectionsByDB as $db => $section ) {
 290                         if ( !isset( $lbs[$section] ) ) {
 291                                 $lbs[$section] = $this->getMainLB( $db );
 292                         }
 293                 }
 294
 295                 return $lbs;
 296         }
 297
 298         public function getAllExternalLBs() {
 299                 $lbs = [];
 300                 foreach ( $this->externalLoads as $cluster => $unused ) {
 301                         $lbs[$cluster] = $this->getExternalLB( $cluster );
 302                 }
 303
 304                 return $lbs;
 305         }
 306
 307         /**
 308          * Make a new load balancer object based on template and load array
 309          *
 310          * @param array $template
 311          * @param array $loads
 312          * @param array $groupLoads
 313          * @param string|bool $readOnlyReason
 314          * @return LoadBalancer
 315          */
 316         private function newLoadBalancer( $template, $loads, $groupLoads, $readOnlyReason ) {
 317                 $lb = new LoadBalancer( array_merge(
 318                         $this->baseLoadBalancerParams(),
 319                         [
 320                                 'servers' => $this->makeServerArray( $template, $loads, $groupLoads ),
 321                                 'maxLag' => $this->maxLag,
 322                                 'loadMonitor' => [ 'class' => $this->loadMonitorClass ],
 323                                 'readOnlyReason' => $readOnlyReason
 324                         ]
 325                 ) );
 326                 $this->initLoadBalancer( $lb );
 327
 328                 return $lb;
 329         }
 330
 331         /**
 332          * Make a server array as expected by LoadBalancer::__construct, using a template and load array
 333          *
 334          * @param array $template
 335          * @param array $loads
 336          * @param array $groupLoads
 337          * @return array
 338          */
 339         private function makeServerArray( $template, $loads, $groupLoads ) {
 340                 $servers = [];
 341                 $master = true;
 342                 $groupLoadsByServer = $this->reindexGroupLoads( $groupLoads );
 343                 foreach ( $groupLoadsByServer as $server => $stuff ) {
 344                         if ( !isset( $loads[$server] ) ) {
 345                                 $loads[$server] = 0;
 346                         }
 347                 }
 348                 foreach ( $loads as $serverName => $load ) {
 349                         $serverInfo = $template;
 350                         if ( $master ) {
 351                                 $serverInfo['master'] = true;
 352                                 if ( $this->masterTemplateOverrides ) {
 353                                         $serverInfo = $this->masterTemplateOverrides + $serverInfo;
 354                                 }
 355                                 $master = false;
 356                         } else {
 357                                 $serverInfo['replica'] = true;
 358                         }
 359                         if ( isset( $this->templateOverridesByServer[$serverName] ) ) {
 360                                 $serverInfo = $this->templateOverridesByServer[$serverName] + $serverInfo;
 361                         }
 362                         if ( isset( $groupLoadsByServer[$serverName] ) ) {
 363                                 $serverInfo['groupLoads'] = $groupLoadsByServer[$serverName];
 364                         }
 365                         $serverInfo['host'] = $this->hostsByName[$serverName] ?? $serverName;
 366                         $serverInfo['hostName'] = $serverName;
 367                         $serverInfo['load'] = $load;
 368                         $serverInfo += [ 'flags' => IDatabase::DBO_DEFAULT ];
 369
 370                         $servers[] = $serverInfo;
 371                 }
 372
 373                 return $servers;
 374         }
 375
 376         /**
 377          * Take a group load array indexed by group then server, and reindex it by server then group
 378          * @param array $groupLoads
 379          * @return array
 380          */
 381         private function reindexGroupLoads( $groupLoads ) {
 382                 $reindexed = [];
 383                 foreach ( $groupLoads as $group => $loads ) {
 384                         foreach ( $loads as $server => $load ) {
 385                                 $reindexed[$server][$group] = $load;
 386                         }
 387                 }
 388
 389                 return $reindexed;
 390         }
 391
 392         /**
 393          * @param DatabaseDomain|string|bool $domain Domain ID, or false for the current domain
 394          * @return array [database name, table prefix]
 395          */
 396         private function getDBNameAndPrefix( $domain = false ) {
 397                 $domain = ( $domain === false )
 398                         ? $this->localDomain
 399                         : DatabaseDomain::newFromId( $domain );
 400
 401                 return [ $domain->getDatabase(), $domain->getTablePrefix() ];
 402         }
 403
 404         /**
 405          * Execute a function for each tracked load balancer
 406          * The callback is called with the load balancer as the first parameter,
 407          * and $params passed as the subsequent parameters.
 408          * @param callable $callback
 409          * @param array $params
 410          */
 411         public function forEachLB( $callback, array $params = [] ) {
 412                 foreach ( $this->mainLBs as $lb ) {
 413                         $callback( $lb, ...$params );
 414                 }
 415                 foreach ( $this->extLBs as $lb ) {
 416                         $callback( $lb, ...$params );
 417                 }
 418         }
 419 }