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