MediaWiki  master
LoadBalancer.php
Go to the documentation of this file.
1 <?php
22 namespace Wikimedia\Rdbms;
23 
24 use ArrayUtils;
25 use BagOStuff;
26 use EmptyBagOStuff;
27 use InvalidArgumentException;
28 use LogicException;
29 use Psr\Log\LoggerInterface;
30 use Psr\Log\NullLogger;
31 use RuntimeException;
32 use Throwable;
33 use UnexpectedValueException;
34 use WANObjectCache;
35 use Wikimedia\ScopedCallback;
36 
42 class LoadBalancer implements ILoadBalancer {
44  private $loadMonitor;
48  private $srvCache;
50  private $wanCache;
52  private $profiler;
54  private $trxProfiler;
56  private $connLogger;
58  private $queryLogger;
60  private $replLogger;
62  private $perfLogger;
64  private $errorLogger;
67 
69  private $localDomain;
70 
74  private $conns;
75 
77  private $servers;
79  private $groupLoads;
81  private $maxLagByIndex;
83  private $waitTimeout;
87  private $maxLag;
89  private $defaultGroup;
90 
92  private $hostname;
94  private $cliMode;
96  private $agent;
97 
99  private $tableAliases = [];
101  private $indexAliases = [];
103  private $domainAliases = [];
107  private $tempTablesOnlyMode = [];
108 
110  private $trxRoundId = false;
112  private $trxRoundStage = self::ROUND_CURSORY;
116  private $readIndexByGroup = [];
118  private $waitForPos;
120  private $allowLagged = false;
122  private $laggedReplicaMode = false;
124  private $lastError = 'Unknown error';
126  private $readOnlyReason = false;
128  private $connectionCounter = 0;
130  private $disabled = false;
132  private $connectionAttempted = false;
133 
135  private $id;
137  private $ownerId;
138 
140  private $nonLocalDomainCache = [];
141 
142  private static $INFO_SERVER_INDEX = 'serverIndex';
143  private static $INFO_AUTOCOMMIT_ONLY = 'autoCommitOnly';
144  private static $INFO_FORIEGN = 'foreign';
145  private static $INFO_FOREIGN_REF_COUNT = 'foreignPoolRefCount';
146 
148  private const CONN_HELD_WARN_THRESHOLD = 10;
149 
151  private const MAX_LAG_DEFAULT = 6;
153  private const MAX_WAIT_DEFAULT = 10;
155  private const TTL_CACHE_READONLY = 5;
156 
157  private const KEY_LOCAL = 'local';
158  private const KEY_FOREIGN_FREE = 'foreignFree';
159  private const KEY_FOREIGN_INUSE = 'foreignInUse';
160 
161  private const KEY_LOCAL_NOROUND = 'localAutoCommit';
162  private const KEY_FOREIGN_FREE_NOROUND = 'foreignFreeAutoCommit';
163  private const KEY_FOREIGN_INUSE_NOROUND = 'foreignInUseAutoCommit';
164 
166  private const ROUND_CURSORY = 'cursory';
168  private const ROUND_FINALIZED = 'finalized';
170  private const ROUND_APPROVED = 'approved';
172  private const ROUND_COMMIT_CALLBACKS = 'commit-callbacks';
174  private const ROUND_ROLLBACK_CALLBACKS = 'rollback-callbacks';
176  private const ROUND_ERROR = 'error';
177 
178  public function __construct( array $params ) {
179  if ( !isset( $params['servers'] ) || !count( $params['servers'] ) ) {
180  throw new InvalidArgumentException( 'Missing or empty "servers" parameter' );
181  }
182 
183  $localDomain = isset( $params['localDomain'] )
184  ? DatabaseDomain::newFromId( $params['localDomain'] )
186  $this->setLocalDomain( $localDomain );
187 
188  $this->maxLag = $params['maxLag'] ?? self::MAX_LAG_DEFAULT;
189 
190  $listKey = -1;
191  $this->servers = [];
192  $this->groupLoads = [ self::GROUP_GENERIC => [] ];
193  foreach ( $params['servers'] as $i => $server ) {
194  if ( ++$listKey !== $i ) {
195  throw new UnexpectedValueException( 'List expected for "servers" parameter' );
196  }
197  $this->servers[$i] = $server;
198  foreach ( ( $server['groupLoads'] ?? [] ) as $group => $ratio ) {
199  $this->groupLoads[$group][$i] = $ratio;
200  }
201  $this->groupLoads[self::GROUP_GENERIC][$i] = $server['load'];
202  $this->maxLagByIndex[$i] = $server['max lag'] ?? $this->maxLag;
203  }
204 
205  $this->waitTimeout = $params['waitTimeout'] ?? self::MAX_WAIT_DEFAULT;
206 
207  $this->conns = self::newTrackedConnectionsArray();
208 
209  if ( isset( $params['readOnlyReason'] ) && is_string( $params['readOnlyReason'] ) ) {
210  $this->readOnlyReason = $params['readOnlyReason'];
211  }
212 
213  $this->loadMonitorConfig = $params['loadMonitor'] ?? [ 'class' => 'LoadMonitorNull' ];
214  $this->loadMonitorConfig += [ 'lagWarnThreshold' => $this->maxLag ];
215 
216  $this->srvCache = $params['srvCache'] ?? new EmptyBagOStuff();
217  $this->wanCache = $params['wanCache'] ?? WANObjectCache::newEmpty();
218  $this->profiler = $params['profiler'] ?? null;
219  $this->trxProfiler = $params['trxProfiler'] ?? new TransactionProfiler();
220 
221  $this->errorLogger = $params['errorLogger'] ?? function ( Throwable $e ) {
222  trigger_error( get_class( $e ) . ': ' . $e->getMessage(), E_USER_WARNING );
223  };
224  $this->deprecationLogger = $params['deprecationLogger'] ?? function ( $msg ) {
225  trigger_error( $msg, E_USER_DEPRECATED );
226  };
227  foreach ( [ 'replLogger', 'connLogger', 'queryLogger', 'perfLogger' ] as $key ) {
228  $this->$key = $params[$key] ?? new NullLogger();
229  }
230 
231  $this->hostname = $params['hostname'] ?? ( gethostname() ?: 'unknown' );
232  $this->cliMode = $params['cliMode'] ?? ( PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg' );
233  $this->agent = $params['agent'] ?? '';
234 
235  if ( isset( $params['chronologyCallback'] ) ) {
236  $this->chronologyCallback = $params['chronologyCallback'];
237  }
238 
239  if ( isset( $params['roundStage'] ) ) {
240  if ( $params['roundStage'] === self::STAGE_POSTCOMMIT_CALLBACKS ) {
241  $this->trxRoundStage = self::ROUND_COMMIT_CALLBACKS;
242  } elseif ( $params['roundStage'] === self::STAGE_POSTROLLBACK_CALLBACKS ) {
243  $this->trxRoundStage = self::ROUND_ROLLBACK_CALLBACKS;
244  }
245  }
246 
247  $group = $params['defaultGroup'] ?? self::GROUP_GENERIC;
248  $this->defaultGroup = isset( $this->groupLoads[$group] ) ? $group : self::GROUP_GENERIC;
249 
250  static $nextId;
251  $this->id = $nextId = ( is_int( $nextId ) ? $nextId++ : mt_rand() );
252  $this->ownerId = $params['ownerId'] ?? null;
253  }
254 
255  private static function newTrackedConnectionsArray() {
256  return [
257  // Connection were transaction rounds may be applied
258  self::KEY_LOCAL => [],
259  self::KEY_FOREIGN_INUSE => [],
260  self::KEY_FOREIGN_FREE => [],
261  // Auto-committing counterpart connections that ignore transaction rounds
262  self::KEY_LOCAL_NOROUND => [],
263  self::KEY_FOREIGN_INUSE_NOROUND => [],
264  self::KEY_FOREIGN_FREE_NOROUND => []
265  ];
266  }
267 
268  public function getLocalDomainID() {
269  return $this->localDomain->getId();
270  }
271 
272  public function resolveDomainID( $domain ) {
273  return $this->resolveDomainInstance( $domain )->getId();
274  }
275 
280  final protected function resolveDomainInstance( $domain ) {
281  if ( $domain instanceof DatabaseDomain ) {
282  return $domain; // already a domain instance
283  } elseif ( $domain === false || $domain === $this->localDomain->getId() ) {
284  return $this->localDomain;
285  } elseif ( isset( $this->domainAliases[$domain] ) ) {
286  $this->domainAliases[$domain] =
287  DatabaseDomain::newFromId( $this->domainAliases[$domain] );
288 
289  return $this->domainAliases[$domain];
290  }
291 
292  $cachedDomain = $this->nonLocalDomainCache[$domain] ?? null;
293  if ( $cachedDomain === null ) {
294  $cachedDomain = DatabaseDomain::newFromId( $domain );
295  $this->nonLocalDomainCache = [ $domain => $cachedDomain ];
296  }
297 
298  return $cachedDomain;
299  }
300 
308  private function resolveGroups( $groups, $i ) {
309  // If a specific replica server was specified, then $groups makes no sense
310  if ( $i > 0 && $groups !== [] && $groups !== false ) {
311  $list = implode( ', ', (array)$groups );
312  throw new LogicException( "Query group(s) ($list) given with server index (#$i)" );
313  }
314 
315  if ( $groups === [] || $groups === false || $groups === $this->defaultGroup ) {
316  $resolvedGroups = [ $this->defaultGroup ]; // common case
317  } elseif ( is_string( $groups ) && isset( $this->groupLoads[$groups] ) ) {
318  $resolvedGroups = [ $groups, $this->defaultGroup ];
319  } elseif ( is_array( $groups ) ) {
320  $resolvedGroups = array_keys( array_flip( $groups ) + [ self::GROUP_GENERIC => 1 ] );
321  } else {
322  $resolvedGroups = [ $this->defaultGroup ];
323  }
324 
325  return $resolvedGroups;
326  }
327 
334  private function sanitizeConnectionFlags( $flags, $i, $domain ) {
335  // Whether an outside caller is explicitly requesting the master database server
336  if ( $i === self::DB_MASTER || $i === $this->getWriterIndex() ) {
337  $flags |= self::CONN_INTENT_WRITABLE;
338  }
339 
340  if ( ( $flags & self::CONN_TRX_AUTOCOMMIT ) == self::CONN_TRX_AUTOCOMMIT ) {
341  // Callers use CONN_TRX_AUTOCOMMIT to bypass REPEATABLE-READ staleness without
342  // resorting to row locks (e.g. FOR UPDATE) or to make small out-of-band commits
343  // during larger transactions. This is useful for avoiding lock contention.
344 
345  // Master DB server attributes (should match those of the replica DB servers)
346  $attributes = $this->getServerAttributes( $this->getWriterIndex() );
347  if ( $attributes[Database::ATTR_DB_LEVEL_LOCKING] ) {
348  // The RDBMS does not support concurrent writes (e.g. SQLite), so attempts
349  // to use separate connections would just cause self-deadlocks. Note that
350  // REPEATABLE-READ staleness is not an issue since DB-level locking means
351  // that transactions are Strict Serializable anyway.
352  $flags &= ~self::CONN_TRX_AUTOCOMMIT;
353  $type = $this->getServerType( $this->getWriterIndex() );
354  $this->connLogger->info( __METHOD__ . ": CONN_TRX_AUTOCOMMIT disallowed ($type)" );
355  } elseif ( isset( $this->tempTablesOnlyMode[$domain] ) ) {
356  // T202116: integration tests are active and queries should be all be using
357  // temporary clone tables (via prefix). Such tables are not visible accross
358  // different connections nor can there be REPEATABLE-READ snapshot staleness,
359  // so use the same connection for everything.
360  $flags &= ~self::CONN_TRX_AUTOCOMMIT;
361  }
362  }
363 
364  return $flags;
365  }
366 
372  private function enforceConnectionFlags( IDatabase $conn, $flags ) {
373  if ( ( $flags & self::CONN_TRX_AUTOCOMMIT ) == self::CONN_TRX_AUTOCOMMIT ) {
374  if ( $conn->trxLevel() ) { // sanity
375  throw new DBUnexpectedError(
376  $conn,
377  'Handle requested with CONN_TRX_AUTOCOMMIT yet it has a transaction'
378  );
379  }
380 
381  $conn->clearFlag( $conn::DBO_TRX ); // auto-commit mode
382  }
383  }
384 
390  private function getLoadMonitor() {
391  if ( !isset( $this->loadMonitor ) ) {
392  $compat = [
393  'LoadMonitor' => LoadMonitor::class,
394  'LoadMonitorNull' => LoadMonitorNull::class,
395  'LoadMonitorMySQL' => LoadMonitorMySQL::class,
396  ];
397 
398  $class = $this->loadMonitorConfig['class'];
399  if ( isset( $compat[$class] ) ) {
400  $class = $compat[$class];
401  }
402 
403  $this->loadMonitor = new $class(
404  $this, $this->srvCache, $this->wanCache, $this->loadMonitorConfig );
405  $this->loadMonitor->setLogger( $this->replLogger );
406  }
407 
408  return $this->loadMonitor;
409  }
410 
417  private function getRandomNonLagged( array $loads, $domain = false, $maxLag = INF ) {
418  $lags = $this->getLagTimes( $domain );
419 
420  # Unset excessively lagged servers
421  foreach ( $lags as $i => $lag ) {
422  if ( $i !== $this->getWriterIndex() ) {
423  # How much lag this server nominally is allowed to have
424  $maxServerLag = $this->servers[$i]['max lag'] ?? $this->maxLag; // default
425  # Constrain that futher by $maxLag argument
426  $maxServerLag = min( $maxServerLag, $maxLag );
427 
428  $host = $this->getServerName( $i );
429  if ( $lag === false && !is_infinite( $maxServerLag ) ) {
430  $this->replLogger->debug(
431  __METHOD__ .
432  ": server {dbserver} is not replicating?", [ 'dbserver' => $host ] );
433  unset( $loads[$i] );
434  } elseif ( $lag > $maxServerLag ) {
435  $this->replLogger->debug(
436  __METHOD__ .
437  ": server {dbserver} has {lag} seconds of lag (>= {maxlag})",
438  [ 'dbserver' => $host, 'lag' => $lag, 'maxlag' => $maxServerLag ]
439  );
440  unset( $loads[$i] );
441  }
442  }
443  }
444 
445  # Find out if all the replica DBs with non-zero load are lagged
446  $sum = 0;
447  foreach ( $loads as $load ) {
448  $sum += $load;
449  }
450  if ( $sum == 0 ) {
451  # No appropriate DB servers except maybe the master and some replica DBs with zero load
452  # Do NOT use the master
453  # Instead, this function will return false, triggering read-only mode,
454  # and a lagged replica DB will be used instead.
455  return false;
456  }
457 
458  if ( count( $loads ) == 0 ) {
459  return false;
460  }
461 
462  # Return a random representative of the remainder
463  return ArrayUtils::pickRandom( $loads );
464  }
465 
474  private function getConnectionIndex( $i, array $groups, $domain ) {
475  if ( $i === self::DB_MASTER ) {
476  $i = $this->getWriterIndex();
477  } elseif ( $i === self::DB_REPLICA ) {
478  foreach ( $groups as $group ) {
479  $groupIndex = $this->getReaderIndex( $group, $domain );
480  if ( $groupIndex !== false ) {
481  $i = $groupIndex; // group connection succeeded
482  break;
483  }
484  }
485  } elseif ( !isset( $this->servers[$i] ) ) {
486  throw new UnexpectedValueException( "Invalid server index index #$i" );
487  }
488 
489  if ( $i === self::DB_REPLICA ) {
490  $this->lastError = 'Unknown error'; // set here in case of worse failure
491  $this->lastError = 'No working replica DB server: ' . $this->lastError;
492  $this->reportConnectionError();
493  return null; // unreachable due to exception
494  }
495 
496  return $i;
497  }
498 
499  public function getReaderIndex( $group = false, $domain = false ) {
500  if ( $this->getServerCount() == 1 ) {
501  // Skip the load balancing if there's only one server
502  return $this->getWriterIndex();
503  }
504 
505  $group = is_string( $group ) ? $group : self::GROUP_GENERIC;
506 
507  $index = $this->getExistingReaderIndex( $group );
508  if ( $index >= 0 ) {
509  // A reader index was already selected and "waitForPos" was handled
510  return $index;
511  }
512 
513  // Use the server weight array for this load group
514  if ( isset( $this->groupLoads[$group] ) ) {
515  $loads = $this->groupLoads[$group];
516  } else {
517  $this->connLogger->info( __METHOD__ . ": no loads for group $group" );
518 
519  return false;
520  }
521 
522  // Scale the configured load ratios according to each server's load and state
523  $this->getLoadMonitor()->scaleLoads( $loads, $domain );
524 
525  // Pick a server to use, accounting for weights, load, lag, and "waitForPos"
526  $this->lazyLoadReplicationPositions(); // optimizes server candidate selection
527  list( $i, $laggedReplicaMode ) = $this->pickReaderIndex( $loads, $domain );
528  if ( $i === false ) {
529  // DB connection unsuccessful
530  return false;
531  }
532 
533  // If data seen by queries is expected to reflect the transactions committed as of
534  // or after a given replication position then wait for the DB to apply those changes
535  if ( $this->waitForPos && $i !== $this->getWriterIndex() && !$this->doWait( $i ) ) {
536  // Data will be outdated compared to what was expected
537  $laggedReplicaMode = true;
538  }
539 
540  // Cache the reader index for future DB_REPLICA handles
541  $this->setExistingReaderIndex( $group, $i );
542  // Record whether the generic reader index is in "lagged replica DB" mode
543  if ( $group === self::GROUP_GENERIC && $laggedReplicaMode ) {
544  $this->laggedReplicaMode = true;
545  }
546 
547  $serverName = $this->getServerName( $i );
548  $this->connLogger->debug( __METHOD__ . ": using server $serverName for group '$group'" );
549 
550  return $i;
551  }
552 
559  protected function getExistingReaderIndex( $group ) {
560  return $this->readIndexByGroup[$group] ?? -1;
561  }
562 
569  private function setExistingReaderIndex( $group, $index ) {
570  if ( $index < 0 ) {
571  throw new UnexpectedValueException( "Cannot set a negative read server index" );
572  }
573  $this->readIndexByGroup[$group] = $index;
574  }
575 
581  private function pickReaderIndex( array $loads, $domain = false ) {
582  if ( $loads === [] ) {
583  throw new InvalidArgumentException( "Server configuration array is empty" );
584  }
585 
587  $i = false;
589  $laggedReplicaMode = false;
590 
591  // Quickly look through the available servers for a server that meets criteria...
592  $currentLoads = $loads;
593  while ( count( $currentLoads ) ) {
594  if ( $this->allowLagged || $laggedReplicaMode ) {
595  $i = ArrayUtils::pickRandom( $currentLoads );
596  } else {
597  $i = false;
598  if ( $this->waitForPos && $this->waitForPos->asOfTime() ) {
599  $this->replLogger->debug( __METHOD__ . ": replication positions detected" );
600  // "chronologyCallback" sets "waitForPos" for session consistency.
601  // This triggers doWait() after connect, so it's especially good to
602  // avoid lagged servers so as to avoid excessive delay in that method.
603  $ago = microtime( true ) - $this->waitForPos->asOfTime();
604  // Aim for <= 1 second of waiting (being too picky can backfire)
605  $i = $this->getRandomNonLagged( $currentLoads, $domain, $ago + 1 );
606  }
607  if ( $i === false ) {
608  // Any server with less lag than it's 'max lag' param is preferable
609  $i = $this->getRandomNonLagged( $currentLoads, $domain );
610  }
611  if ( $i === false && count( $currentLoads ) ) {
612  // All replica DBs lagged. Switch to read-only mode
613  $this->replLogger->error(
614  __METHOD__ . ": all replica DBs lagged. Switch to read-only mode" );
615  $i = ArrayUtils::pickRandom( $currentLoads );
616  $laggedReplicaMode = true;
617  }
618  }
619 
620  if ( $i === false ) {
621  // pickRandom() returned false.
622  // This is permanent and means the configuration or the load monitor
623  // wants us to return false.
624  $this->connLogger->debug( __METHOD__ . ": pickRandom() returned false" );
625 
626  return [ false, false ];
627  }
628 
629  $serverName = $this->getServerName( $i );
630  $this->connLogger->debug( __METHOD__ . ": Using reader #$i: $serverName..." );
631 
632  // Get a connection to this server without triggering other server connections
633  $conn = $this->getServerConnection( $i, $domain, self::CONN_SILENCE_ERRORS );
634  if ( !$conn ) {
635  $this->connLogger->warning( __METHOD__ . ": Failed connecting to $i/$domain" );
636  unset( $currentLoads[$i] ); // avoid this server next iteration
637  $i = false;
638  continue;
639  }
640 
641  // Decrement reference counter, we are finished with this connection.
642  // It will be incremented for the caller later.
643  if ( $domain !== false ) {
644  $this->reuseConnection( $conn );
645  }
646 
647  // Return this server
648  break;
649  }
650 
651  // If all servers were down, quit now
652  if ( $currentLoads === [] ) {
653  $this->connLogger->error( __METHOD__ . ": all servers down" );
654  }
655 
656  return [ $i, $laggedReplicaMode ];
657  }
658 
659  public function waitFor( $pos ) {
660  $oldPos = $this->waitForPos;
661  try {
662  $this->waitForPos = $pos;
663  // If a generic reader connection was already established, then wait now
664  $i = $this->getExistingReaderIndex( self::GROUP_GENERIC );
665  if ( $i > 0 && !$this->doWait( $i ) ) {
666  $this->laggedReplicaMode = true;
667  }
668  // Otherwise, wait until a connection is established in getReaderIndex()
669  } finally {
670  // Restore the older position if it was higher since this is used for lag-protection
671  $this->setWaitForPositionIfHigher( $oldPos );
672  }
673  }
674 
675  public function waitForOne( $pos, $timeout = null ) {
676  $oldPos = $this->waitForPos;
677  try {
678  $this->waitForPos = $pos;
679 
680  $i = $this->getExistingReaderIndex( self::GROUP_GENERIC );
681  if ( $i <= 0 ) {
682  // Pick a generic replica DB if there isn't one yet
683  $readLoads = $this->groupLoads[self::GROUP_GENERIC];
684  unset( $readLoads[$this->getWriterIndex()] ); // replica DBs only
685  $readLoads = array_filter( $readLoads ); // with non-zero load
686  $i = ArrayUtils::pickRandom( $readLoads );
687  }
688 
689  if ( $i > 0 ) {
690  $ok = $this->doWait( $i, true, $timeout );
691  } else {
692  $ok = true; // no applicable loads
693  }
694  } finally {
695  // Restore the old position; this is used for throttling, not lag-protection
696  $this->waitForPos = $oldPos;
697  }
698 
699  return $ok;
700  }
701 
702  public function waitForAll( $pos, $timeout = null ) {
703  $timeout = $timeout ?: $this->waitTimeout;
704 
705  $oldPos = $this->waitForPos;
706  try {
707  $this->waitForPos = $pos;
708  $serverCount = $this->getServerCount();
709 
710  $ok = true;
711  for ( $i = 1; $i < $serverCount; $i++ ) {
712  if ( $this->serverHasLoadInAnyGroup( $i ) ) {
713  $start = microtime( true );
714  $ok = $this->doWait( $i, true, $timeout ) && $ok;
715  $timeout -= intval( microtime( true ) - $start );
716  if ( $timeout <= 0 ) {
717  break; // timeout reached
718  }
719  }
720  }
721  } finally {
722  // Restore the old position; this is used for throttling, not lag-protection
723  $this->waitForPos = $oldPos;
724  }
725 
726  return $ok;
727  }
728 
733  private function serverHasLoadInAnyGroup( $i ) {
734  foreach ( $this->groupLoads as $loadsByIndex ) {
735  if ( ( $loadsByIndex[$i] ?? 0 ) > 0 ) {
736  return true;
737  }
738  }
739 
740  return false;
741  }
742 
746  private function setWaitForPositionIfHigher( $pos ) {
747  if ( !$pos ) {
748  return;
749  }
750 
751  if ( !$this->waitForPos || $pos->hasReached( $this->waitForPos ) ) {
752  $this->waitForPos = $pos;
753  }
754  }
755 
756  public function getAnyOpenConnection( $i, $flags = 0 ) {
757  $i = ( $i === self::DB_MASTER ) ? $this->getWriterIndex() : $i;
758  // Connection handles required to be in auto-commit mode use a separate connection
759  // pool since the main pool is effected by implicit and explicit transaction rounds
760  $autocommit = ( ( $flags & self::CONN_TRX_AUTOCOMMIT ) == self::CONN_TRX_AUTOCOMMIT );
761 
762  $conn = false;
763  foreach ( $this->conns as $connsByServer ) {
764  // Get the connection array server indexes to inspect
765  if ( $i === self::DB_REPLICA ) {
766  $indexes = array_keys( $connsByServer );
767  } else {
768  $indexes = isset( $connsByServer[$i] ) ? [ $i ] : [];
769  }
770 
771  foreach ( $indexes as $index ) {
772  $conn = $this->pickAnyOpenConnection( $connsByServer[$index], $autocommit );
773  if ( $conn ) {
774  break;
775  }
776  }
777  }
778 
779  if ( $conn ) {
780  $this->enforceConnectionFlags( $conn, $flags );
781  }
782 
783  return $conn;
784  }
785 
791  private function pickAnyOpenConnection( $candidateConns, $autocommit ) {
792  $conn = false;
793 
794  foreach ( $candidateConns as $candidateConn ) {
795  if ( !$candidateConn->isOpen() ) {
796  continue; // some sort of error occurred?
797  } elseif (
798  $autocommit &&
799  (
800  // Connection is transaction round aware
801  !$candidateConn->getLBInfo( self::$INFO_AUTOCOMMIT_ONLY ) ||
802  // Some sort of error left a transaction open?
803  $candidateConn->trxLevel()
804  )
805  ) {
806  continue; // some sort of error left a transaction open?
807  }
808 
809  $conn = $candidateConn;
810  }
811 
812  return $conn;
813  }
814 
822  protected function doWait( $index, $open = false, $timeout = null ) {
823  $timeout = max( 1, intval( $timeout ?: $this->waitTimeout ) );
824 
825  // Check if we already know that the DB has reached this point
826  $server = $this->getServerName( $index );
827  $key = $this->srvCache->makeGlobalKey( __CLASS__, 'last-known-pos', $server, 'v1' );
829  $knownReachedPos = $this->srvCache->get( $key );
830  if (
831  $knownReachedPos instanceof DBMasterPos &&
832  $knownReachedPos->hasReached( $this->waitForPos )
833  ) {
834  $this->replLogger->debug(
835  __METHOD__ .
836  ": replica DB {dbserver} known to be caught up (pos >= $knownReachedPos).",
837  [ 'dbserver' => $server ]
838  );
839  return true;
840  }
841 
842  // Find a connection to wait on, creating one if needed and allowed
843  $close = false; // close the connection afterwards
844  $flags = self::CONN_SILENCE_ERRORS;
845  $conn = $this->getAnyOpenConnection( $index, $flags );
846  if ( !$conn ) {
847  if ( !$open ) {
848  $this->replLogger->debug(
849  __METHOD__ . ': no connection open for {dbserver}',
850  [ 'dbserver' => $server ]
851  );
852 
853  return false;
854  }
855  // Get a connection to this server without triggering other server connections
856  $conn = $this->getServerConnection( $index, self::DOMAIN_ANY, $flags );
857  if ( !$conn ) {
858  $this->replLogger->warning(
859  __METHOD__ . ': failed to connect to {dbserver}',
860  [ 'dbserver' => $server ]
861  );
862 
863  return false;
864  }
865  // Avoid connection spam in waitForAll() when connections
866  // are made just for the sake of doing this lag check.
867  $close = true;
868  }
869 
870  $this->replLogger->info(
871  __METHOD__ .
872  ': waiting for replica DB {dbserver} to catch up...',
873  [ 'dbserver' => $server ]
874  );
875 
876  $result = $conn->masterPosWait( $this->waitForPos, $timeout );
877 
878  $ok = ( $result !== null && $result != -1 );
879  if ( $ok ) {
880  // Remember that the DB reached this point
881  $this->srvCache->set( $key, $this->waitForPos, BagOStuff::TTL_DAY );
882  }
883 
884  if ( $close ) {
885  $this->closeConnection( $conn );
886  }
887 
888  return $ok;
889  }
890 
891  public function getConnection( $i, $groups = [], $domain = false, $flags = 0 ) {
892  $domain = $this->resolveDomainID( $domain );
893  $groups = $this->resolveGroups( $groups, $i );
894  $flags = $this->sanitizeConnectionFlags( $flags, $i, $domain );
895  // If given DB_MASTER/DB_REPLICA, resolve it to a specific server index. Resolving
896  // DB_REPLICA might trigger getServerConnection() calls due to the getReaderIndex()
897  // connectivity checks or LoadMonitor::scaleLoads() server state cache regeneration.
898  // The use of getServerConnection() instead of getConnection() avoids infinite loops.
899  $serverIndex = $this->getConnectionIndex( $i, $groups, $domain );
900  // Get an open connection to that server (might trigger a new connection)
901  $conn = $this->getServerConnection( $serverIndex, $domain, $flags );
902  // Set master DB handles as read-only if there is high replication lag
903  if (
904  $serverIndex === $this->getWriterIndex() &&
905  $this->getLaggedReplicaMode( $domain ) &&
906  !is_string( $conn->getLBInfo( $conn::LB_READ_ONLY_REASON ) )
907  ) {
908  $reason = ( $this->getExistingReaderIndex( self::GROUP_GENERIC ) >= 0 )
909  ? 'The database is read-only until replication lag decreases.'
910  : 'The database is read-only until replica database servers becomes reachable.';
911  $conn->setLBInfo( $conn::LB_READ_ONLY_REASON, $reason );
912  }
913 
914  return $conn;
915  }
916 
924  public function getServerConnection( $i, $domain, $flags = 0 ) {
925  // Number of connections made before getting the server index and handle
926  $priorConnectionsMade = $this->connectionCounter;
927  // Get an open connection to this server (might trigger a new connection)
928  $conn = $this->localDomain->equals( $domain )
929  ? $this->getLocalConnection( $i, $flags )
930  : $this->getForeignConnection( $i, $domain, $flags );
931  // Throw an error or otherwise bail out if the connection attempt failed
932  if ( !( $conn instanceof IDatabase ) ) {
933  if ( ( $flags & self::CONN_SILENCE_ERRORS ) != self::CONN_SILENCE_ERRORS ) {
934  $this->reportConnectionError();
935  }
936 
937  return false;
938  }
939 
940  // Profile any new connections caused by this method
941  if ( $this->connectionCounter > $priorConnectionsMade ) {
942  $this->trxProfiler->recordConnection(
943  $conn->getServer(),
944  $conn->getDBname(),
945  ( ( $flags & self::CONN_INTENT_WRITABLE ) == self::CONN_INTENT_WRITABLE )
946  );
947  }
948 
949  if ( !$conn->isOpen() ) {
950  $this->errorConnection = $conn;
951  // Connection was made but later unrecoverably lost for some reason.
952  // Do not return a handle that will just throw exceptions on use, but
953  // let the calling code, e.g. getReaderIndex(), try another server.
954  return false;
955  }
956 
957  // Make sure that flags like CONN_TRX_AUTOCOMMIT are respected by this handle
958  $this->enforceConnectionFlags( $conn, $flags );
959  // Set master DB handles as read-only if the load balancer is configured as read-only
960  // or the master database server is running in server-side read-only mode. Note that
961  // replica DB handles are always read-only via Database::assertIsWritableMaster().
962  // Read-only mode due to replication lag is *avoided* here to avoid recursion.
963  if ( $i === $this->getWriterIndex() ) {
964  if ( $this->readOnlyReason !== false ) {
966  } elseif ( $this->isMasterConnectionReadOnly( $conn, $flags ) ) {
967  $readOnlyReason = 'The master database server is running in read-only mode.';
968  } else {
969  $readOnlyReason = false;
970  }
971  $conn->setLBInfo( $conn::LB_READ_ONLY_REASON, $readOnlyReason );
972  }
973 
974  return $conn;
975  }
976 
977  public function reuseConnection( IDatabase $conn ) {
978  $serverIndex = $conn->getLBInfo( self::$INFO_SERVER_INDEX );
979  $refCount = $conn->getLBInfo( self::$INFO_FOREIGN_REF_COUNT );
980  if ( $serverIndex === null || $refCount === null ) {
981  return; // non-foreign connection; no domain-use tracking to update
982  } elseif ( $conn instanceof DBConnRef ) {
983  // DBConnRef already handles calling reuseConnection() and only passes the live
984  // Database instance to this method. Any caller passing in a DBConnRef is broken.
985  $this->connLogger->error(
986  __METHOD__ . ": got DBConnRef instance.\n" .
987  ( new LogicException() )->getTraceAsString() );
988 
989  return;
990  }
991 
992  if ( $this->disabled ) {
993  return; // DBConnRef handle probably survived longer than the LoadBalancer
994  }
995 
996  if ( $conn->getLBInfo( self::$INFO_AUTOCOMMIT_ONLY ) ) {
997  $connFreeKey = self::KEY_FOREIGN_FREE_NOROUND;
998  $connInUseKey = self::KEY_FOREIGN_INUSE_NOROUND;
999  } else {
1000  $connFreeKey = self::KEY_FOREIGN_FREE;
1001  $connInUseKey = self::KEY_FOREIGN_INUSE;
1002  }
1003 
1004  $domain = $conn->getDomainID();
1005  if ( !isset( $this->conns[$connInUseKey][$serverIndex][$domain] ) ) {
1006  throw new InvalidArgumentException(
1007  "Connection $serverIndex/$domain not found; it may have already been freed" );
1008  } elseif ( $this->conns[$connInUseKey][$serverIndex][$domain] !== $conn ) {
1009  throw new InvalidArgumentException(
1010  "Connection $serverIndex/$domain mismatched; it may have already been freed" );
1011  }
1012 
1013  $conn->setLBInfo( self::$INFO_FOREIGN_REF_COUNT, --$refCount );
1014  if ( $refCount <= 0 ) {
1015  $this->conns[$connFreeKey][$serverIndex][$domain] = $conn;
1016  unset( $this->conns[$connInUseKey][$serverIndex][$domain] );
1017  if ( !$this->conns[$connInUseKey][$serverIndex] ) {
1018  unset( $this->conns[$connInUseKey][$serverIndex] ); // clean up
1019  }
1020  $this->connLogger->debug( __METHOD__ . ": freed connection $serverIndex/$domain" );
1021  } else {
1022  $this->connLogger->debug( __METHOD__ .
1023  ": reference count for $serverIndex/$domain reduced to $refCount" );
1024  }
1025  }
1026 
1027  public function getConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ) {
1028  $domain = $this->resolveDomainID( $domain );
1029  $role = $this->getRoleFromIndex( $i );
1030 
1031  return new DBConnRef( $this, $this->getConnection( $i, $groups, $domain, $flags ), $role );
1032  }
1033 
1034  public function getLazyConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ) {
1035  $domain = $this->resolveDomainID( $domain );
1036  $role = $this->getRoleFromIndex( $i );
1037 
1038  return new DBConnRef( $this, [ $i, $groups, $domain, $flags ], $role );
1039  }
1040 
1041  public function getMaintenanceConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ) {
1042  $domain = $this->resolveDomainID( $domain );
1043  $role = $this->getRoleFromIndex( $i );
1044 
1045  return new MaintainableDBConnRef(
1046  $this, $this->getConnection( $i, $groups, $domain, $flags ), $role );
1047  }
1048 
1053  private function getRoleFromIndex( $i ) {
1054  return ( $i === self::DB_MASTER || $i === $this->getWriterIndex() )
1055  ? self::DB_MASTER
1056  : self::DB_REPLICA;
1057  }
1058 
1066  public function openConnection( $i, $domain = false, $flags = 0 ) {
1067  return $this->getConnection( $i, [], $domain, $flags | self::CONN_SILENCE_ERRORS );
1068  }
1069 
1084  private function getLocalConnection( $i, $flags = 0 ) {
1085  $autoCommit = ( ( $flags & self::CONN_TRX_AUTOCOMMIT ) == self::CONN_TRX_AUTOCOMMIT );
1086  // Connection handles required to be in auto-commit mode use a separate connection
1087  // pool since the main pool is effected by implicit and explicit transaction rounds
1088  $connKey = $autoCommit ? self::KEY_LOCAL_NOROUND : self::KEY_LOCAL;
1089 
1090  if ( isset( $this->conns[$connKey][$i][0] ) ) {
1091  $conn = $this->conns[$connKey][$i][0];
1092  } else {
1093  $conn = $this->reallyOpenConnection(
1094  $i,
1095  $this->localDomain,
1096  [ self::$INFO_AUTOCOMMIT_ONLY => $autoCommit ]
1097  );
1098  if ( $conn->isOpen() ) {
1099  $this->connLogger->debug( __METHOD__ . ": opened new connection for $i" );
1100  $this->conns[$connKey][$i][0] = $conn;
1101  } else {
1102  $this->connLogger->warning( __METHOD__ . ": connection error for $i" );
1103  $this->errorConnection = $conn;
1104  $conn = false;
1105  }
1106  }
1107 
1108  // Sanity check to make sure that the right domain is selected
1109  if (
1110  $conn instanceof IDatabase &&
1111  !$this->localDomain->isCompatible( $conn->getDomainID() )
1112  ) {
1113  throw new UnexpectedValueException(
1114  "Got connection to '{$conn->getDomainID()}', " .
1115  "but expected local domain ('{$this->localDomain}')"
1116  );
1117  }
1118 
1119  return $conn;
1120  }
1121 
1146  private function getForeignConnection( $i, $domain, $flags = 0 ) {
1147  $domainInstance = DatabaseDomain::newFromId( $domain );
1148  $autoCommit = ( ( $flags & self::CONN_TRX_AUTOCOMMIT ) == self::CONN_TRX_AUTOCOMMIT );
1149  // Connection handles required to be in auto-commit mode use a separate connection
1150  // pool since the main pool is effected by implicit and explicit transaction rounds
1151  if ( $autoCommit ) {
1152  $connFreeKey = self::KEY_FOREIGN_FREE_NOROUND;
1153  $connInUseKey = self::KEY_FOREIGN_INUSE_NOROUND;
1154  } else {
1155  $connFreeKey = self::KEY_FOREIGN_FREE;
1156  $connInUseKey = self::KEY_FOREIGN_INUSE;
1157  }
1158 
1160  $conn = null;
1161 
1162  if ( isset( $this->conns[$connInUseKey][$i][$domain] ) ) {
1163  // Reuse an in-use connection for the same domain
1164  $conn = $this->conns[$connInUseKey][$i][$domain];
1165  $this->connLogger->debug( __METHOD__ . ": reusing connection $i/$domain" );
1166  } elseif ( isset( $this->conns[$connFreeKey][$i][$domain] ) ) {
1167  // Reuse a free connection for the same domain
1168  $conn = $this->conns[$connFreeKey][$i][$domain];
1169  unset( $this->conns[$connFreeKey][$i][$domain] );
1170  $this->conns[$connInUseKey][$i][$domain] = $conn;
1171  $this->connLogger->debug( __METHOD__ . ": reusing free connection $i/$domain" );
1172  } elseif ( !empty( $this->conns[$connFreeKey][$i] ) ) {
1173  // Reuse a free connection from another domain if possible
1174  foreach ( $this->conns[$connFreeKey][$i] as $oldDomain => $oldConn ) {
1175  if ( $domainInstance->getDatabase() !== null ) {
1176  // Check if changing the database will require a new connection.
1177  // In that case, leave the connection handle alone and keep looking.
1178  // This prevents connections from being closed mid-transaction and can
1179  // also avoid overhead if the same database will later be requested.
1180  if (
1181  $oldConn->databasesAreIndependent() &&
1182  $oldConn->getDBname() !== $domainInstance->getDatabase()
1183  ) {
1184  continue;
1185  }
1186  // Select the new database, schema, and prefix
1187  $conn = $oldConn;
1188  $conn->selectDomain( $domainInstance );
1189  } else {
1190  // Stay on the current database, but update the schema/prefix
1191  $conn = $oldConn;
1192  $conn->dbSchema( $domainInstance->getSchema() );
1193  $conn->tablePrefix( $domainInstance->getTablePrefix() );
1194  }
1195  unset( $this->conns[$connFreeKey][$i][$oldDomain] );
1196  // Note that if $domain is an empty string, getDomainID() might not match it
1197  $this->conns[$connInUseKey][$i][$conn->getDomainID()] = $conn;
1198  $this->connLogger->debug( __METHOD__ .
1199  ": reusing free connection from $oldDomain for $domain" );
1200  break;
1201  }
1202  }
1203 
1204  if ( !$conn ) {
1205  $conn = $this->reallyOpenConnection(
1206  $i,
1207  $domainInstance,
1208  [
1209  self::$INFO_AUTOCOMMIT_ONLY => $autoCommit,
1210  self::$INFO_FORIEGN => true,
1211  self::$INFO_FOREIGN_REF_COUNT => 0
1212  ]
1213  );
1214  if ( $conn->isOpen() ) {
1215  // Note that if $domain is an empty string, getDomainID() might not match it
1216  $this->conns[$connInUseKey][$i][$conn->getDomainID()] = $conn;
1217  $this->connLogger->debug( __METHOD__ . ": opened new connection for $i/$domain" );
1218  } else {
1219  $this->connLogger->warning( __METHOD__ . ": connection error for $i/$domain" );
1220  $this->errorConnection = $conn;
1221  $conn = false;
1222  }
1223  }
1224 
1225  if ( $conn instanceof IDatabase ) {
1226  // Sanity check to make sure that the right domain is selected
1227  if ( !$domainInstance->isCompatible( $conn->getDomainID() ) ) {
1228  throw new UnexpectedValueException(
1229  "Got connection to '{$conn->getDomainID()}', but expected '$domain'" );
1230  }
1231  // Increment reference count
1232  $refCount = $conn->getLBInfo( self::$INFO_FOREIGN_REF_COUNT );
1233  $conn->setLBInfo( self::$INFO_FOREIGN_REF_COUNT, $refCount + 1 );
1234  }
1235 
1236  return $conn;
1237  }
1238 
1239  public function getServerAttributes( $i ) {
1241  $this->getServerType( $i ),
1242  $this->servers[$i]['driver'] ?? null
1243  );
1244  }
1245 
1252  private function isOpen( $index ) {
1253  return (bool)$this->getAnyOpenConnection( $index );
1254  }
1255 
1268  protected function reallyOpenConnection( $i, DatabaseDomain $domain, array $lbInfo ) {
1269  if ( $this->disabled ) {
1270  throw new DBAccessError();
1271  }
1272 
1273  $server = $this->getServerInfoStrict( $i );
1274 
1275  $conn = Database::factory(
1276  $server['type'],
1277  array_merge( $server, [
1278  // Basic replication role information
1279  'topologyRole' => $this->getTopologyRole( $i, $server ),
1280  'topologicalMaster' => $this->getMasterServerName(),
1281  // Use the database specified in $domain (null means "none or entrypoint DB");
1282  // fallback to the $server default if the RDBMs is an embedded library using a
1283  // file on disk since there would be nothing to access to without a DB/file name.
1284  'dbname' => $this->getServerAttributes( $i )[Database::ATTR_DB_IS_FILE]
1285  ? ( $domain->getDatabase() ?? $server['dbname'] ?? null )
1286  : $domain->getDatabase(),
1287  // Override the $server default schema with that of $domain if specified
1288  'schema' => $domain->getSchema() ?? $server['schema'] ?? null,
1289  // Use the table prefix specified in $domain
1290  'tablePrefix' => $domain->getTablePrefix(),
1291  // Participate in transaction rounds if $server does not specify otherwise
1292  'flags' => $this->initConnFlags( $server['flags'] ?? IDatabase::DBO_DEFAULT ),
1293  // Inject the PHP execution mode and the agent string
1294  'cliMode' => $this->cliMode,
1295  'agent' => $this->agent,
1296  'ownerId' => $this->id,
1297  // Inject object and callback dependencies
1298  'lazyMasterHandle' => $this->getLazyConnectionRef(
1300  [],
1301  $domain->getId()
1302  ),
1303  'srvCache' => $this->srvCache,
1304  'connLogger' => $this->connLogger,
1305  'queryLogger' => $this->queryLogger,
1306  'replLogger' => $this->replLogger,
1307  'errorLogger' => $this->errorLogger,
1308  'deprecationLogger' => $this->deprecationLogger,
1309  'profiler' => $this->profiler,
1310  'trxProfiler' => $this->trxProfiler
1311  ] ),
1312  Database::NEW_UNCONNECTED
1313  );
1314  // Attach load balancer information to the handle
1315  $conn->setLBInfo( [ self::$INFO_SERVER_INDEX => $i ] + $lbInfo );
1316  // Set alternative table/index names before any queries can be issued
1317  $conn->setTableAliases( $this->tableAliases );
1318  $conn->setIndexAliases( $this->indexAliases );
1319  // Account for any active transaction round and listeners
1320  if ( $i === $this->getWriterIndex() ) {
1321  if ( $this->trxRoundId !== false ) {
1322  $this->applyTransactionRoundFlags( $conn );
1323  }
1324  foreach ( $this->trxRecurringCallbacks as $name => $callback ) {
1325  $conn->setTransactionListener( $name, $callback );
1326  }
1327  }
1328 
1329  // Make the connection handle live
1330  try {
1331  $conn->initConnection();
1333  } catch ( DBConnectionError $e ) {
1334  // ignore; let the DB handle the logging
1335  }
1336 
1337  // Try to maintain session consistency for clients that trigger write transactions
1338  // in a request or script and then return soon after in another request or script.
1339  // This requires cooperation with ChronologyProtector and the application wiring.
1340  if ( $conn->isOpen() ) {
1342  }
1343 
1344  // Log when many connection are made during a single request/script
1345  $count = $this->getCurrentConnectionCount();
1346  if ( $count >= self::CONN_HELD_WARN_THRESHOLD ) {
1347  $this->perfLogger->warning(
1348  __METHOD__ . ": {connections}+ connections made (master={masterdb})",
1349  [
1350  'connections' => $count,
1351  'dbserver' => $conn->getServer(),
1352  'masterdb' => $this->getMasterServerName()
1353  ]
1354  );
1355  }
1356 
1357  return $conn;
1358  }
1359 
1365  private function getTopologyRole( $i, array $server ) {
1366  if ( !empty( $server['is static'] ) ) {
1367  return IDatabase::ROLE_STATIC_CLONE;
1368  }
1369 
1370  return ( $i === $this->getWriterIndex() )
1371  ? IDatabase::ROLE_STREAMING_MASTER
1372  : IDatabase::ROLE_STREAMING_REPLICA;
1373  }
1374 
1380  private function initConnFlags( $flags ) {
1381  if ( ( $flags & IDatabase::DBO_DEFAULT ) === IDatabase::DBO_DEFAULT ) {
1382  if ( $this->cliMode ) {
1383  $flags &= ~IDatabase::DBO_TRX;
1384  } else {
1385  $flags |= IDatabase::DBO_TRX;
1386  }
1387  }
1388 
1389  return $flags;
1390  }
1391 
1395  private function lazyLoadReplicationPositions() {
1396  if ( !$this->connectionAttempted && $this->chronologyCallback ) {
1397  $this->connectionAttempted = true;
1398  ( $this->chronologyCallback )( $this ); // generally calls waitFor()
1399  $this->connLogger->debug( __METHOD__ . ': executed chronology callback.' );
1400  }
1401  }
1402 
1406  private function reportConnectionError() {
1407  $conn = $this->errorConnection; // the connection which caused the error
1408  $context = [
1409  'method' => __METHOD__,
1410  'last_error' => $this->lastError,
1411  ];
1412 
1413  if ( $conn instanceof IDatabase ) {
1414  $context['db_server'] = $conn->getServer();
1415  $this->connLogger->warning(
1416  __METHOD__ . ": connection error: {last_error} ({db_server})",
1417  $context
1418  );
1419 
1420  throw new DBConnectionError( $conn, "{$this->lastError} ({$context['db_server']})" );
1421  } else {
1422  // No last connection, probably due to all servers being too busy
1423  $this->connLogger->error(
1424  __METHOD__ .
1425  ": LB failure with no last connection. Connection error: {last_error}",
1426  $context
1427  );
1428 
1429  // If all servers were busy, "lastError" will contain something sensible
1430  throw new DBConnectionError( null, $this->lastError );
1431  }
1432  }
1433 
1434  public function getWriterIndex() {
1435  return 0;
1436  }
1437 
1445  public function haveIndex( $i ) {
1446  return array_key_exists( $i, $this->servers );
1447  }
1448 
1456  public function isNonZeroLoad( $i ) {
1457  return ( isset( $this->servers[$i] ) && $this->groupLoads[self::GROUP_GENERIC][$i] > 0 );
1458  }
1459 
1460  public function getServerCount() {
1461  return count( $this->servers );
1462  }
1463 
1464  public function hasReplicaServers() {
1465  return ( $this->getServerCount() > 1 );
1466  }
1467 
1468  public function hasStreamingReplicaServers() {
1469  foreach ( $this->servers as $i => $server ) {
1470  if ( $i !== $this->getWriterIndex() && empty( $server['is static'] ) ) {
1471  return true;
1472  }
1473  }
1474 
1475  return false;
1476  }
1477 
1478  public function getServerName( $i ) {
1479  $name = $this->servers[$i]['hostName'] ?? ( $this->servers[$i]['host'] ?? '' );
1480 
1481  return ( $name != '' ) ? $name : 'localhost';
1482  }
1483 
1484  public function getServerInfo( $i ) {
1485  return $this->servers[$i] ?? false;
1486  }
1487 
1488  public function getServerType( $i ) {
1489  return $this->servers[$i]['type'] ?? 'unknown';
1490  }
1491 
1492  public function getMasterPos() {
1493  $index = $this->getWriterIndex();
1494 
1495  $conn = $this->getAnyOpenConnection( $index );
1496  if ( $conn ) {
1497  return $conn->getMasterPos();
1498  }
1499 
1500  $conn = $this->getConnection( $index, self::CONN_SILENCE_ERRORS );
1501  if ( !$conn ) {
1502  $this->reportConnectionError();
1503  return null; // unreachable due to exception
1504  }
1505 
1506  try {
1507  $pos = $conn->getMasterPos();
1508  } finally {
1509  $this->closeConnection( $conn );
1510  }
1511 
1512  return $pos;
1513  }
1514 
1515  public function getReplicaResumePos() {
1516  // Get the position of any existing master server connection
1517  $masterConn = $this->getAnyOpenConnection( $this->getWriterIndex() );
1518  if ( $masterConn ) {
1519  return $masterConn->getMasterPos();
1520  }
1521 
1522  // Get the highest position of any existing replica server connection
1523  $highestPos = false;
1524  $serverCount = $this->getServerCount();
1525  for ( $i = 1; $i < $serverCount; $i++ ) {
1526  if ( !empty( $this->servers[$i]['is static'] ) ) {
1527  continue; // server does not use replication
1528  }
1529 
1530  $conn = $this->getAnyOpenConnection( $i );
1531  $pos = $conn ? $conn->getReplicaPos() : false;
1532  if ( !$pos ) {
1533  continue; // no open connection or could not get position
1534  }
1535 
1536  $highestPos = $highestPos ?: $pos;
1537  if ( $pos->hasReached( $highestPos ) ) {
1538  $highestPos = $pos;
1539  }
1540  }
1541 
1542  return $highestPos;
1543  }
1544 
1545  public function disable( $fname = __METHOD__, $owner = null ) {
1546  $this->assertOwnership( $fname, $owner );
1547  $this->closeAll( $fname, $owner );
1548  $this->disabled = true;
1549  }
1550 
1551  public function closeAll( $fname = __METHOD__, $owner = null ) {
1552  $this->assertOwnership( $fname, $owner );
1553  if ( $this->ownerId === null ) {
1555  $scope = ScopedCallback::newScopedIgnoreUserAbort();
1556  }
1557  $this->forEachOpenConnection( function ( IDatabase $conn ) use ( $fname ) {
1558  $host = $conn->getServer();
1559  $this->connLogger->debug( "$fname: closing connection to database '$host'." );
1560  $conn->close( $fname, $this->id );
1561  } );
1562 
1563  $this->conns = self::newTrackedConnectionsArray();
1564  }
1565 
1566  public function closeConnection( IDatabase $conn ) {
1567  if ( $conn instanceof DBConnRef ) {
1568  // Avoid calling close() but still leaving the handle in the pool
1569  throw new RuntimeException( 'Cannot close DBConnRef instance; it must be shareable' );
1570  }
1571 
1572  $serverIndex = $conn->getLBInfo( self::$INFO_SERVER_INDEX );
1573  foreach ( $this->conns as $type => $connsByServer ) {
1574  if ( !isset( $connsByServer[$serverIndex] ) ) {
1575  continue;
1576  }
1577 
1578  foreach ( $connsByServer[$serverIndex] as $i => $trackedConn ) {
1579  if ( $conn === $trackedConn ) {
1580  $host = $this->getServerName( $i );
1581  $this->connLogger->debug(
1582  __METHOD__ . ": closing connection to database $i at '$host'." );
1583  unset( $this->conns[$type][$serverIndex][$i] );
1584  break 2;
1585  }
1586  }
1587  }
1588 
1589  $conn->close( __METHOD__ );
1590  }
1591 
1592  public function commitAll( $fname = __METHOD__, $owner = null ) {
1593  $this->commitMasterChanges( $fname, $owner );
1594  $this->flushMasterSnapshots( $fname, $owner );
1595  $this->flushReplicaSnapshots( $fname, $owner );
1596  }
1597 
1598  public function finalizeMasterChanges( $fname = __METHOD__, $owner = null ) {
1599  $this->assertOwnership( $fname, $owner );
1600  $this->assertTransactionRoundStage( [ self::ROUND_CURSORY, self::ROUND_FINALIZED ] );
1601  if ( $this->ownerId === null ) {
1603  $scope = ScopedCallback::newScopedIgnoreUserAbort();
1604  }
1605 
1606  $this->trxRoundStage = self::ROUND_ERROR; // "failed" until proven otherwise
1607  // Loop until callbacks stop adding callbacks on other connections
1608  $total = 0;
1609  do {
1610  $count = 0; // callbacks execution attempts
1611  $this->forEachOpenMasterConnection( function ( Database $conn ) use ( &$count ) {
1612  // Run any pre-commit callbacks while leaving the post-commit ones suppressed.
1613  // Any error should cause all (peer) transactions to be rolled back together.
1614  $count += $conn->runOnTransactionPreCommitCallbacks();
1615  } );
1616  $total += $count;
1617  } while ( $count > 0 );
1618  // Defer post-commit callbacks until after COMMIT/ROLLBACK happens on all handles
1619  $this->forEachOpenMasterConnection( function ( Database $conn ) {
1620  $conn->setTrxEndCallbackSuppression( true );
1621  } );
1622  $this->trxRoundStage = self::ROUND_FINALIZED;
1623 
1624  return $total;
1625  }
1626 
1627  public function approveMasterChanges( array $options, $fname = __METHOD__, $owner = null ) {
1628  $this->assertOwnership( $fname, $owner );
1629  $this->assertTransactionRoundStage( self::ROUND_FINALIZED );
1630  if ( $this->ownerId === null ) {
1632  $scope = ScopedCallback::newScopedIgnoreUserAbort();
1633  }
1634 
1635  $limit = $options['maxWriteDuration'] ?? 0;
1636 
1637  $this->trxRoundStage = self::ROUND_ERROR; // "failed" until proven otherwise
1638  $this->forEachOpenMasterConnection( function ( IDatabase $conn ) use ( $limit ) {
1639  // If atomic sections or explicit transactions are still open, some caller must have
1640  // caught an exception but failed to properly rollback any changes. Detect that and
1641  // throw an error (causing rollback).
1642  $conn->assertNoOpenTransactions();
1643  // Assert that the time to replicate the transaction will be sane.
1644  // If this fails, then all DB transactions will be rollback back together.
1645  $time = $conn->pendingWriteQueryDuration( $conn::ESTIMATE_DB_APPLY );
1646  if ( $limit > 0 && $time > $limit ) {
1647  throw new DBTransactionSizeError(
1648  $conn,
1649  "Transaction spent $time second(s) in writes, exceeding the limit of $limit",
1650  [ $time, $limit ]
1651  );
1652  }
1653  // If a connection sits idle while slow queries execute on another, that connection
1654  // may end up dropped before the commit round is reached. Ping servers to detect this.
1655  if ( $conn->writesOrCallbacksPending() && !$conn->ping() ) {
1656  throw new DBTransactionError(
1657  $conn,
1658  "A connection to the {$conn->getDBname()} database was lost before commit"
1659  );
1660  }
1661  } );
1662  $this->trxRoundStage = self::ROUND_APPROVED;
1663  }
1664 
1665  public function beginMasterChanges( $fname = __METHOD__, $owner = null ) {
1666  $this->assertOwnership( $fname, $owner );
1667  if ( $this->trxRoundId !== false ) {
1668  throw new DBTransactionError(
1669  null,
1670  "$fname: Transaction round '{$this->trxRoundId}' already started"
1671  );
1672  }
1673  $this->assertTransactionRoundStage( self::ROUND_CURSORY );
1674  if ( $this->ownerId === null ) {
1676  $scope = ScopedCallback::newScopedIgnoreUserAbort();
1677  }
1678 
1679  // Clear any empty transactions (no writes/callbacks) from the implicit round
1680  $this->flushMasterSnapshots( $fname, $owner );
1681 
1682  $this->trxRoundId = $fname;
1683  $this->trxRoundStage = self::ROUND_ERROR; // "failed" until proven otherwise
1684  // Mark applicable handles as participating in this explicit transaction round.
1685  // For each of these handles, any writes and callbacks will be tied to a single
1686  // transaction. The (peer) handles will reject begin()/commit() calls unless they
1687  // are part of an en masse commit or an en masse rollback.
1688  $this->forEachOpenMasterConnection( function ( Database $conn ) {
1689  $this->applyTransactionRoundFlags( $conn );
1690  } );
1691  $this->trxRoundStage = self::ROUND_CURSORY;
1692  }
1693 
1694  public function commitMasterChanges( $fname = __METHOD__, $owner = null ) {
1695  $this->assertOwnership( $fname, $owner );
1696  $this->assertTransactionRoundStage( self::ROUND_APPROVED );
1697  if ( $this->ownerId === null ) {
1699  $scope = ScopedCallback::newScopedIgnoreUserAbort();
1700  }
1701 
1702  $failures = [];
1703 
1704  $restore = ( $this->trxRoundId !== false );
1705  $this->trxRoundId = false;
1706  $this->trxRoundStage = self::ROUND_ERROR; // "failed" until proven otherwise
1707  // Commit any writes and clear any snapshots as well (callbacks require AUTOCOMMIT).
1708  // Note that callbacks should already be suppressed due to finalizeMasterChanges().
1710  function ( IDatabase $conn ) use ( $fname, &$failures ) {
1711  try {
1712  $conn->commit( $fname, $conn::FLUSHING_ALL_PEERS );
1713  } catch ( DBError $e ) {
1714  ( $this->errorLogger )( $e );
1715  $failures[] = "{$conn->getServer()}: {$e->getMessage()}";
1716  }
1717  }
1718  );
1719  if ( $failures ) {
1720  throw new DBTransactionError(
1721  null,
1722  "$fname: Commit failed on server(s) " . implode( "\n", array_unique( $failures ) )
1723  );
1724  }
1725  if ( $restore ) {
1726  // Unmark handles as participating in this explicit transaction round
1727  $this->forEachOpenMasterConnection( function ( Database $conn ) {
1728  $this->undoTransactionRoundFlags( $conn );
1729  } );
1730  }
1731  $this->trxRoundStage = self::ROUND_COMMIT_CALLBACKS;
1732  }
1733 
1734  public function runMasterTransactionIdleCallbacks( $fname = __METHOD__, $owner = null ) {
1735  $this->assertOwnership( $fname, $owner );
1736  if ( $this->trxRoundStage === self::ROUND_COMMIT_CALLBACKS ) {
1737  $type = IDatabase::TRIGGER_COMMIT;
1738  } elseif ( $this->trxRoundStage === self::ROUND_ROLLBACK_CALLBACKS ) {
1739  $type = IDatabase::TRIGGER_ROLLBACK;
1740  } else {
1741  throw new DBTransactionError(
1742  null,
1743  "Transaction should be in the callback stage (not '{$this->trxRoundStage}')"
1744  );
1745  }
1746  if ( $this->ownerId === null ) {
1748  $scope = ScopedCallback::newScopedIgnoreUserAbort();
1749  }
1750 
1751  $oldStage = $this->trxRoundStage;
1752  $this->trxRoundStage = self::ROUND_ERROR; // "failed" until proven otherwise
1753 
1754  // Now that the COMMIT/ROLLBACK step is over, enable post-commit callback runs
1755  $this->forEachOpenMasterConnection( function ( Database $conn ) {
1756  $conn->setTrxEndCallbackSuppression( false );
1757  } );
1758 
1759  $e = null; // first exception
1760  $fname = __METHOD__;
1761  // Loop until callbacks stop adding callbacks on other connections
1762  do {
1763  // Run any pending callbacks for each connection...
1764  $count = 0; // callback execution attempts
1766  function ( Database $conn ) use ( $type, &$e, &$count ) {
1767  if ( $conn->trxLevel() ) {
1768  return; // retry in the next iteration, after commit() is called
1769  }
1770  try {
1771  $count += $conn->runOnTransactionIdleCallbacks( $type );
1772  } catch ( Throwable $ex ) {
1773  $e = $e ?: $ex;
1774  }
1775  }
1776  );
1777  // Clear out any active transactions left over from callbacks...
1778  $this->forEachOpenMasterConnection( function ( Database $conn ) use ( &$e, $fname ) {
1779  if ( $conn->writesPending() ) {
1780  // A callback from another handle wrote to this one and DBO_TRX is set
1781  $this->queryLogger->warning( $fname . ": found writes pending." );
1782  $fnames = implode( ', ', $conn->pendingWriteAndCallbackCallers() );
1783  $this->queryLogger->warning(
1784  "$fname: found writes pending ($fnames).",
1785  [
1786  'db_server' => $conn->getServer(),
1787  'db_name' => $conn->getDBname(),
1788  'exception' => new RuntimeException()
1789  ]
1790  );
1791  } elseif ( $conn->trxLevel() ) {
1792  // A callback from another handle read from this one and DBO_TRX is set,
1793  // which can easily happen if there is only one DB (no replicas)
1794  $this->queryLogger->debug( "$fname: found empty transaction." );
1795  }
1796  try {
1797  $conn->commit( $fname, $conn::FLUSHING_ALL_PEERS );
1798  } catch ( Throwable $ex ) {
1799  $e = $e ?: $ex;
1800  }
1801  } );
1802  } while ( $count > 0 );
1803 
1804  $this->trxRoundStage = $oldStage;
1805 
1806  return $e;
1807  }
1808 
1809  public function runMasterTransactionListenerCallbacks( $fname = __METHOD__, $owner = null ) {
1810  $this->assertOwnership( $fname, $owner );
1811  if ( $this->trxRoundStage === self::ROUND_COMMIT_CALLBACKS ) {
1812  $type = IDatabase::TRIGGER_COMMIT;
1813  } elseif ( $this->trxRoundStage === self::ROUND_ROLLBACK_CALLBACKS ) {
1814  $type = IDatabase::TRIGGER_ROLLBACK;
1815  } else {
1816  throw new DBTransactionError(
1817  null,
1818  "Transaction should be in the callback stage (not '{$this->trxRoundStage}')"
1819  );
1820  }
1821  if ( $this->ownerId === null ) {
1823  $scope = ScopedCallback::newScopedIgnoreUserAbort();
1824  }
1825 
1826  $e = null;
1827 
1828  $this->trxRoundStage = self::ROUND_ERROR; // "failed" until proven otherwise
1829  $this->forEachOpenMasterConnection( function ( Database $conn ) use ( $type, &$e ) {
1830  try {
1832  } catch ( Throwable $ex ) {
1833  $e = $e ?: $ex;
1834  }
1835  } );
1836  $this->trxRoundStage = self::ROUND_CURSORY;
1837 
1838  return $e;
1839  }
1840 
1841  public function rollbackMasterChanges( $fname = __METHOD__, $owner = null ) {
1842  $this->assertOwnership( $fname, $owner );
1843  if ( $this->ownerId === null ) {
1845  $scope = ScopedCallback::newScopedIgnoreUserAbort();
1846  }
1847 
1848  $restore = ( $this->trxRoundId !== false );
1849  $this->trxRoundId = false;
1850  $this->trxRoundStage = self::ROUND_ERROR; // "failed" until proven otherwise
1851  $this->forEachOpenMasterConnection( function ( IDatabase $conn ) use ( $fname ) {
1852  $conn->rollback( $fname, $conn::FLUSHING_ALL_PEERS );
1853  } );
1854  if ( $restore ) {
1855  // Unmark handles as participating in this explicit transaction round
1856  $this->forEachOpenMasterConnection( function ( Database $conn ) {
1857  $this->undoTransactionRoundFlags( $conn );
1858  } );
1859  }
1860  $this->trxRoundStage = self::ROUND_ROLLBACK_CALLBACKS;
1861  }
1862 
1867  private function assertTransactionRoundStage( $stage ) {
1868  $stages = (array)$stage;
1869 
1870  if ( !in_array( $this->trxRoundStage, $stages, true ) ) {
1871  $stageList = implode(
1872  '/',
1873  array_map( function ( $v ) {
1874  return "'$v'";
1875  }, $stages )
1876  );
1877  throw new DBTransactionError(
1878  null,
1879  "Transaction round stage must be $stageList (not '{$this->trxRoundStage}')"
1880  );
1881  }
1882  }
1883 
1896  private function assertOwnership( $fname, $owner ) {
1897  if ( $this->ownerId !== null && $owner !== $this->ownerId && $owner !== $this->id ) {
1898  throw new DBTransactionError(
1899  null,
1900  "$fname: LoadBalancer is owned by ID '{$this->ownerId}' (got '$owner')."
1901  );
1902  }
1903  }
1904 
1914  private function applyTransactionRoundFlags( Database $conn ) {
1915  if ( $conn->getLBInfo( self::$INFO_AUTOCOMMIT_ONLY ) ) {
1916  return; // transaction rounds do not apply to these connections
1917  }
1918 
1919  if ( $conn->getFlag( $conn::DBO_DEFAULT ) ) {
1920  // DBO_TRX is controlled entirely by CLI mode presence with DBO_DEFAULT.
1921  // Force DBO_TRX even in CLI mode since a commit round is expected soon.
1922  $conn->setFlag( $conn::DBO_TRX, $conn::REMEMBER_PRIOR );
1923  }
1924 
1925  if ( $conn->getFlag( $conn::DBO_TRX ) ) {
1926  $conn->setLBInfo( $conn::LB_TRX_ROUND_ID, $this->trxRoundId );
1927  }
1928  }
1929 
1933  private function undoTransactionRoundFlags( Database $conn ) {
1934  if ( $conn->getLBInfo( self::$INFO_AUTOCOMMIT_ONLY ) ) {
1935  return; // transaction rounds do not apply to these connections
1936  }
1937 
1938  if ( $conn->getFlag( $conn::DBO_TRX ) ) {
1939  $conn->setLBInfo( $conn::LB_TRX_ROUND_ID, null ); // remove the round ID
1940  }
1941 
1942  if ( $conn->getFlag( $conn::DBO_DEFAULT ) ) {
1943  $conn->restoreFlags( $conn::RESTORE_PRIOR );
1944  }
1945  }
1946 
1947  public function flushReplicaSnapshots( $fname = __METHOD__, $owner = null ) {
1948  $this->assertOwnership( $fname, $owner );
1949  $this->forEachOpenReplicaConnection( function ( IDatabase $conn ) use ( $fname ) {
1950  $conn->flushSnapshot( $fname );
1951  } );
1952  }
1953 
1954  public function flushMasterSnapshots( $fname = __METHOD__, $owner = null ) {
1955  $this->assertOwnership( $fname, $owner );
1956  $this->forEachOpenMasterConnection( function ( IDatabase $conn ) use ( $fname ) {
1957  $conn->flushSnapshot( $fname );
1958  } );
1959  }
1960 
1965  public function getTransactionRoundStage() {
1966  return $this->trxRoundStage;
1967  }
1968 
1969  public function hasMasterConnection() {
1970  return $this->isOpen( $this->getWriterIndex() );
1971  }
1972 
1973  public function hasMasterChanges() {
1974  $pending = 0;
1975  $this->forEachOpenMasterConnection( function ( IDatabase $conn ) use ( &$pending ) {
1976  $pending |= $conn->writesOrCallbacksPending();
1977  } );
1978 
1979  return (bool)$pending;
1980  }
1981 
1982  public function lastMasterChangeTimestamp() {
1983  $lastTime = false;
1984  $this->forEachOpenMasterConnection( function ( IDatabase $conn ) use ( &$lastTime ) {
1985  $lastTime = max( $lastTime, $conn->lastDoneWrites() );
1986  } );
1987 
1988  return $lastTime;
1989  }
1990 
1991  public function hasOrMadeRecentMasterChanges( $age = null ) {
1992  $age = ( $age === null ) ? $this->waitTimeout : $age;
1993 
1994  return ( $this->hasMasterChanges()
1995  || $this->lastMasterChangeTimestamp() > microtime( true ) - $age );
1996  }
1997 
1998  public function pendingMasterChangeCallers() {
1999  $fnames = [];
2000  $this->forEachOpenMasterConnection( function ( IDatabase $conn ) use ( &$fnames ) {
2001  $fnames = array_merge( $fnames, $conn->pendingWriteCallers() );
2002  } );
2003 
2004  return $fnames;
2005  }
2006 
2007  public function getLaggedReplicaMode( $domain = false ) {
2008  if ( $this->laggedReplicaMode ) {
2009  return true; // stay in lagged replica mode
2010  }
2011 
2012  if ( $this->hasStreamingReplicaServers() ) {
2013  // This will set "laggedReplicaMode" as needed
2014  $this->getReaderIndex( self::GROUP_GENERIC, $domain );
2015  }
2016 
2017  return $this->laggedReplicaMode;
2018  }
2019 
2020  public function laggedReplicaUsed() {
2021  return $this->laggedReplicaMode;
2022  }
2023 
2024  public function getReadOnlyReason( $domain = false ) {
2025  $domainInstance = DatabaseDomain::newFromId( $this->resolveDomainID( $domain ) );
2026 
2027  if ( $this->readOnlyReason !== false ) {
2028  return $this->readOnlyReason;
2029  } elseif ( $this->isMasterRunningReadOnly( $domainInstance ) ) {
2030  return 'The master database server is running in read-only mode.';
2031  } elseif ( $this->getLaggedReplicaMode( $domain ) ) {
2032  return ( $this->getExistingReaderIndex( self::GROUP_GENERIC ) >= 0 )
2033  ? 'The database is read-only until replication lag decreases.'
2034  : 'The database is read-only until a replica database server becomes reachable.';
2035  }
2036 
2037  return false;
2038  }
2039 
2045  private function isMasterConnectionReadOnly( IDatabase $conn, $flags = 0 ) {
2046  // Note that table prefixes are not related to server-side read-only mode
2047  $key = $this->srvCache->makeGlobalKey(
2048  'rdbms-server-readonly',
2049  $conn->getServer(),
2050  $conn->getDBname(),
2051  $conn->dbSchema()
2052  );
2053 
2054  if ( ( $flags & self::CONN_REFRESH_READ_ONLY ) == self::CONN_REFRESH_READ_ONLY ) {
2055  try {
2056  $readOnly = (int)$conn->serverIsReadOnly();
2057  } catch ( DBError $e ) {
2058  $readOnly = 0;
2059  }
2060  $this->srvCache->set( $key, $readOnly, BagOStuff::TTL_PROC_SHORT );
2061  } else {
2062  $readOnly = $this->srvCache->getWithSetCallback(
2063  $key,
2064  BagOStuff::TTL_PROC_SHORT,
2065  function () use ( $conn ) {
2066  try {
2067  return (int)$conn->serverIsReadOnly();
2068  } catch ( DBError $e ) {
2069  return 0;
2070  }
2071  }
2072  );
2073  }
2074 
2075  return (bool)$readOnly;
2076  }
2077 
2082  private function isMasterRunningReadOnly( DatabaseDomain $domain ) {
2083  // Context will often be HTTP GET/HEAD; heavily cache the results
2084  return (bool)$this->wanCache->getWithSetCallback(
2085  // Note that table prefixes are not related to server-side read-only mode
2086  $this->wanCache->makeGlobalKey(
2087  'rdbms-server-readonly',
2088  $this->getMasterServerName(),
2089  $domain->getDatabase(),
2090  $domain->getSchema()
2091  ),
2092  self::TTL_CACHE_READONLY,
2093  function () use ( $domain ) {
2094  $old = $this->trxProfiler->setSilenced( true );
2095  try {
2096  $index = $this->getWriterIndex();
2097  // Reset the cache for isMasterConnectionReadOnly()
2098  $flags = self::CONN_REFRESH_READ_ONLY;
2099  $conn = $this->getServerConnection( $index, $domain->getId(), $flags );
2100  // Reuse the process cache set above
2101  $readOnly = (int)$this->isMasterConnectionReadOnly( $conn );
2102  $this->reuseConnection( $conn );
2103  } catch ( DBError $e ) {
2104  $readOnly = 0;
2105  }
2106  $this->trxProfiler->setSilenced( $old );
2107 
2108  return $readOnly;
2109  },
2110  [ 'pcTTL' => WANObjectCache::TTL_PROC_LONG, 'lockTSE' => 10, 'busyValue' => 0 ]
2111  );
2112  }
2113 
2114  public function allowLagged( $mode = null ) {
2115  if ( $mode === null ) {
2116  return $this->allowLagged;
2117  }
2118  $this->allowLagged = $mode;
2119 
2120  return $this->allowLagged;
2121  }
2122 
2123  public function pingAll() {
2124  $success = true;
2125  $this->forEachOpenConnection( function ( IDatabase $conn ) use ( &$success ) {
2126  if ( !$conn->ping() ) {
2127  $success = false;
2128  }
2129  } );
2130 
2131  return $success;
2132  }
2133 
2134  public function forEachOpenConnection( $callback, array $params = [] ) {
2135  foreach ( $this->conns as $connsByServer ) {
2136  foreach ( $connsByServer as $serverConns ) {
2137  foreach ( $serverConns as $conn ) {
2138  $callback( $conn, ...$params );
2139  }
2140  }
2141  }
2142  }
2143 
2144  public function forEachOpenMasterConnection( $callback, array $params = [] ) {
2145  $masterIndex = $this->getWriterIndex();
2146  foreach ( $this->conns as $connsByServer ) {
2147  if ( isset( $connsByServer[$masterIndex] ) ) {
2149  foreach ( $connsByServer[$masterIndex] as $conn ) {
2150  $callback( $conn, ...$params );
2151  }
2152  }
2153  }
2154  }
2155 
2156  public function forEachOpenReplicaConnection( $callback, array $params = [] ) {
2157  foreach ( $this->conns as $connsByServer ) {
2158  foreach ( $connsByServer as $i => $serverConns ) {
2159  if ( $i === $this->getWriterIndex() ) {
2160  continue; // skip master
2161  }
2162  foreach ( $serverConns as $conn ) {
2163  $callback( $conn, ...$params );
2164  }
2165  }
2166  }
2167  }
2168 
2172  private function getCurrentConnectionCount() {
2173  $count = 0;
2174  foreach ( $this->conns as $connsByServer ) {
2175  foreach ( $connsByServer as $serverConns ) {
2176  $count += count( $serverConns );
2177  }
2178  }
2179 
2180  return $count;
2181  }
2182 
2183  public function getMaxLag( $domain = false ) {
2184  $host = '';
2185  $maxLag = -1;
2186  $maxIndex = 0;
2187 
2188  if ( $this->hasReplicaServers() ) {
2189  $lagTimes = $this->getLagTimes( $domain );
2190  foreach ( $lagTimes as $i => $lag ) {
2191  if ( $this->groupLoads[self::GROUP_GENERIC][$i] > 0 && $lag > $maxLag ) {
2192  $maxLag = $lag;
2193  $host = $this->getServerInfoStrict( $i, 'host' );
2194  $maxIndex = $i;
2195  }
2196  }
2197  }
2198 
2199  return [ $host, $maxLag, $maxIndex ];
2200  }
2201 
2202  public function getLagTimes( $domain = false ) {
2203  if ( !$this->hasReplicaServers() ) {
2204  return [ $this->getWriterIndex() => 0 ]; // no replication = no lag
2205  }
2206 
2207  $knownLagTimes = []; // map of (server index => 0 seconds)
2208  $indexesWithLag = [];
2209  foreach ( $this->servers as $i => $server ) {
2210  if ( empty( $server['is static'] ) ) {
2211  $indexesWithLag[] = $i; // DB server might have replication lag
2212  } else {
2213  $knownLagTimes[$i] = 0; // DB server is a non-replicating and read-only archive
2214  }
2215  }
2216 
2217  return $this->getLoadMonitor()->getLagTimes( $indexesWithLag, $domain ) + $knownLagTimes;
2218  }
2219 
2235  public function safeGetLag( IDatabase $conn ) {
2236  return $conn->getLag();
2237  }
2238 
2239  public function waitForMasterPos( IDatabase $conn, $pos = false, $timeout = null ) {
2240  $timeout = max( 1, $timeout ?: $this->waitTimeout );
2241 
2242  if ( $conn->getLBInfo( self::$INFO_SERVER_INDEX ) === $this->getWriterIndex() ) {
2243  return true; // not a replica DB server
2244  }
2245 
2246  if ( !$pos ) {
2247  // Get the current master position, opening a connection if needed
2248  $index = $this->getWriterIndex();
2249  $flags = self::CONN_SILENCE_ERRORS;
2250  $masterConn = $this->getAnyOpenConnection( $index, $flags );
2251  if ( $masterConn ) {
2252  $pos = $masterConn->getMasterPos();
2253  } else {
2254  $masterConn = $this->getServerConnection( $index, self::DOMAIN_ANY, $flags );
2255  if ( !$masterConn ) {
2256  throw new DBReplicationWaitError(
2257  null,
2258  "Could not obtain a master database connection to get the position"
2259  );
2260  }
2261  $pos = $masterConn->getMasterPos();
2262  $this->closeConnection( $masterConn );
2263  }
2264  }
2265 
2266  if ( $pos instanceof DBMasterPos ) {
2267  $start = microtime( true );
2268  $result = $conn->masterPosWait( $pos, $timeout );
2269  $seconds = max( microtime( true ) - $start, 0 );
2270 
2271  $ok = ( $result !== null && $result != -1 );
2272  if ( $ok ) {
2273  $this->replLogger->warning(
2274  __METHOD__ . ': timed out waiting on {dbserver} pos {pos} [{seconds}s]',
2275  [
2276  'dbserver' => $conn->getServer(),
2277  'pos' => $pos,
2278  'seconds' => round( $seconds, 6 ),
2279  'trace' => ( new RuntimeException() )->getTraceAsString()
2280  ]
2281  );
2282  } else {
2283  $this->replLogger->debug( __METHOD__ . ': done waiting' );
2284  }
2285  } else {
2286  $ok = false; // something is misconfigured
2287  $this->replLogger->error(
2288  __METHOD__ . ': could not get master pos for {dbserver}',
2289  [
2290  'dbserver' => $conn->getServer(),
2291  'trace' => ( new RuntimeException() )->getTraceAsString()
2292  ]
2293  );
2294  }
2295 
2296  return $ok;
2297  }
2298 
2311  public function safeWaitForMasterPos( IDatabase $conn, $pos = false, $timeout = null ) {
2312  return $this->waitForMasterPos( $conn, $pos, $timeout );
2313  }
2314 
2315  public function setTransactionListener( $name, callable $callback = null ) {
2316  if ( $callback ) {
2317  $this->trxRecurringCallbacks[$name] = $callback;
2318  } else {
2319  unset( $this->trxRecurringCallbacks[$name] );
2320  }
2322  function ( IDatabase $conn ) use ( $name, $callback ) {
2323  $conn->setTransactionListener( $name, $callback );
2324  }
2325  );
2326  }
2327 
2328  public function setTableAliases( array $aliases ) {
2329  $this->tableAliases = $aliases;
2330  }
2331 
2332  public function setIndexAliases( array $aliases ) {
2333  $this->indexAliases = $aliases;
2334  }
2335 
2336  public function setDomainAliases( array $aliases ) {
2337  $this->domainAliases = $aliases;
2338  }
2339 
2340  public function setLocalDomainPrefix( $prefix ) {
2341  // Find connections to explicit foreign domains still marked as in-use...
2342  $domainsInUse = [];
2343  $this->forEachOpenConnection( function ( IDatabase $conn ) use ( &$domainsInUse ) {
2344  // Once reuseConnection() is called on a handle, its reference count goes from 1 to 0.
2345  // Until then, it is still in use by the caller (explicitly or via DBConnRef scope).
2346  if ( $conn->getLBInfo( self::$INFO_FOREIGN_REF_COUNT ) > 0 ) {
2347  $domainsInUse[] = $conn->getDomainID();
2348  }
2349  } );
2350 
2351  // Do not switch connections to explicit foreign domains unless marked as safe
2352  if ( $domainsInUse ) {
2353  $domains = implode( ', ', $domainsInUse );
2354  throw new DBUnexpectedError( null,
2355  "Foreign domain connections are still in use ($domains)" );
2356  }
2357 
2358  $this->setLocalDomain( new DatabaseDomain(
2359  $this->localDomain->getDatabase(),
2360  $this->localDomain->getSchema(),
2361  $prefix
2362  ) );
2363 
2364  // Update the prefix for all local connections...
2365  $this->forEachOpenConnection( function ( IDatabase $conn ) use ( $prefix ) {
2366  if ( !$conn->getLBInfo( self::$INFO_FORIEGN ) ) {
2367  $conn->tablePrefix( $prefix );
2368  }
2369  } );
2370  }
2371 
2372  public function redefineLocalDomain( $domain ) {
2373  $this->closeAll( __METHOD__, $this->id );
2374 
2375  $this->setLocalDomain( DatabaseDomain::newFromId( $domain ) );
2376  }
2377 
2378  public function setTempTablesOnlyMode( $value, $domain ) {
2379  $old = $this->tempTablesOnlyMode[$domain] ?? false;
2380  if ( $value ) {
2381  $this->tempTablesOnlyMode[$domain] = true;
2382  } else {
2383  unset( $this->tempTablesOnlyMode[$domain] );
2384  }
2385 
2386  return $old;
2387  }
2388 
2392  private function setLocalDomain( DatabaseDomain $domain ) {
2393  $this->localDomain = $domain;
2394  }
2395 
2402  private function getServerInfoStrict( $i, $field = null ) {
2403  if ( !isset( $this->servers[$i] ) || !is_array( $this->servers[$i] ) ) {
2404  throw new InvalidArgumentException( "No server with index '$i'" );
2405  }
2406 
2407  if ( $field !== null ) {
2408  if ( !array_key_exists( $field, $this->servers[$i] ) ) {
2409  throw new InvalidArgumentException( "No field '$field' in server index '$i'" );
2410  }
2411 
2412  return $this->servers[$i][$field];
2413  }
2414 
2415  return $this->servers[$i];
2416  }
2417 
2421  private function getMasterServerName() {
2422  return $this->getServerName( $this->getWriterIndex() );
2423  }
2424 
2425  public function __destruct() {
2426  // Avoid connection leaks for sanity
2427  $this->disable( __METHOD__, $this->ownerId );
2428  }
2429 }
2430 
2434 class_alias( LoadBalancer::class, 'LoadBalancer' );
Wikimedia\Rdbms\LoadBalancer\$allowLagged
bool $allowLagged
Whether to disregard replica DB lag as a factor in replica DB selection.
Definition: LoadBalancer.php:120
Wikimedia\Rdbms\LoadBalancer\getServerType
getServerType( $i)
Get DB type of the server with the specified index.
Definition: LoadBalancer.php:1488
Wikimedia\Rdbms\LoadBalancer\getExistingReaderIndex
getExistingReaderIndex( $group)
Get the server index chosen by the load balancer for use with the given query group.
Definition: LoadBalancer.php:559
Wikimedia\Rdbms\LoadBalancer\setWaitForPositionIfHigher
setWaitForPositionIfHigher( $pos)
Definition: LoadBalancer.php:746
Wikimedia\Rdbms\LoadBalancer\waitForMasterPos
waitForMasterPos(IDatabase $conn, $pos=false, $timeout=null)
Wait for a replica DB to reach a specified master position.
Definition: LoadBalancer.php:2239
Wikimedia\Rdbms\DBTransactionSizeError
Definition: DBTransactionSizeError.php:27
Wikimedia\Rdbms\Database
Relational database abstraction object.
Definition: Database.php:50
Wikimedia\Rdbms\LoadBalancer\getServerInfo
getServerInfo( $i)
Return the server info structure for a given index or false if the index is invalid.
Definition: LoadBalancer.php:1484
Wikimedia\Rdbms\LoadBalancer\newTrackedConnectionsArray
static newTrackedConnectionsArray()
Definition: LoadBalancer.php:255
Wikimedia\Rdbms\LoadBalancer\$trxProfiler
TransactionProfiler $trxProfiler
Definition: LoadBalancer.php:54
Wikimedia\Rdbms\LoadBalancer\isOpen
isOpen( $index)
Test if the specified index represents an open connection.
Definition: LoadBalancer.php:1252
Wikimedia\Rdbms\LoadBalancer\$trxRoundId
string bool $trxRoundId
Explicit DBO_TRX transaction round active or false if none.
Definition: LoadBalancer.php:110
Wikimedia\Rdbms\IDatabase\getServer
getServer()
Get the server hostname or IP address.
Wikimedia\Rdbms\LoadBalancer\hasOrMadeRecentMasterChanges
hasOrMadeRecentMasterChanges( $age=null)
Check if this load balancer object had any recent or still pending writes issued against it by this P...
Definition: LoadBalancer.php:1991
Wikimedia\Rdbms\LoadBalancer\assertOwnership
assertOwnership( $fname, $owner)
Assure that if this instance is owned, the caller is either the owner or is internal.
Definition: LoadBalancer.php:1896
Wikimedia\Rdbms\DatabaseDomain\getId
getId()
Definition: DatabaseDomain.php:196
Wikimedia\Rdbms\IDatabase\pendingWriteQueryDuration
pendingWriteQueryDuration( $type=self::ESTIMATE_TOTAL)
Get the time spend running write queries for this transaction.
Wikimedia\Rdbms\DatabaseDomain\newFromId
static newFromId( $domain)
Definition: DatabaseDomain.php:77
Wikimedia\Rdbms\LoadBalancer\getWriterIndex
getWriterIndex()
Get the server index of the master server.
Definition: LoadBalancer.php:1434
EmptyBagOStuff
A BagOStuff object with no objects in it.
Definition: EmptyBagOStuff.php:29
Wikimedia\Rdbms\LoadBalancer\serverHasLoadInAnyGroup
serverHasLoadInAnyGroup( $i)
Definition: LoadBalancer.php:733
Wikimedia\Rdbms\IDatabase\rollback
rollback( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
Rollback a transaction previously started using begin()
Wikimedia\Rdbms\DBAccessError
Exception class for attempted DB access.
Definition: DBAccessError.php:28
Wikimedia\Rdbms\LoadBalancer\lazyLoadReplicationPositions
lazyLoadReplicationPositions()
Make sure that any "waitForPos" positions are loaded and available to doWait()
Definition: LoadBalancer.php:1395
Wikimedia\Rdbms\IDatabase\setLBInfo
setLBInfo( $nameOrArray, $value=null)
Set the entire array or a particular key of the managing load balancer info array.
Wikimedia\Rdbms\LoadBalancer\$waitTimeout
int $waitTimeout
Seconds to spend waiting on replica DB lag to resolve.
Definition: LoadBalancer.php:83
Wikimedia\Rdbms\LoadBalancer\getConnectionIndex
getConnectionIndex( $i, array $groups, $domain)
Get the server index to use for a specified server index and query group list.
Definition: LoadBalancer.php:474
Wikimedia\Rdbms\ILoadMonitor
An interface for database load monitoring.
Definition: ILoadMonitor.php:35
Wikimedia\Rdbms\LoadBalancer\getCurrentConnectionCount
getCurrentConnectionCount()
Definition: LoadBalancer.php:2172
Wikimedia\Rdbms\LoadBalancer\getMasterPos
getMasterPos()
Get the current master replication position.
Definition: LoadBalancer.php:1492
Wikimedia\Rdbms\IDatabase\ping
ping(&$rtt=null)
Ping the server and try to reconnect if it there is no connection.
Wikimedia\Rdbms\Database\factory
static factory( $type, $params=[], $connect=self::NEW_CONNECTED)
Construct a Database subclass instance given a database type and parameters.
Definition: Database.php:395
Wikimedia\Rdbms\LoadBalancer\safeGetLag
safeGetLag(IDatabase $conn)
Get the lag in seconds for a given connection, or zero if this load balancer does not have replicatio...
Definition: LoadBalancer.php:2235
Wikimedia\Rdbms\DBReplicationWaitError
Exception class for replica DB wait errors.
Definition: DBReplicationWaitError.php:28
Wikimedia\Rdbms\LoadBalancer\getServerInfoStrict
getServerInfoStrict( $i, $field=null)
Definition: LoadBalancer.php:2402
Wikimedia\Rdbms\DatabaseDomain\getTablePrefix
getTablePrefix()
Definition: DatabaseDomain.php:189
Wikimedia\Rdbms\LoadBalancer\approveMasterChanges
approveMasterChanges(array $options, $fname=__METHOD__, $owner=null)
Perform all pre-commit checks for things like replication safety.
Definition: LoadBalancer.php:1627
Wikimedia\Rdbms\LoadBalancer\$domainAliases
DatabaseDomain[] string[] $domainAliases
Map of (domain alias => DB domain)
Definition: LoadBalancer.php:103
Wikimedia\Rdbms\IDatabase\trxLevel
trxLevel()
Gets the current transaction level.
Wikimedia\Rdbms\LoadBalancer\setLocalDomainPrefix
setLocalDomainPrefix( $prefix)
Set a new table prefix for the existing local domain ID for testing.
Definition: LoadBalancer.php:2340
Wikimedia\Rdbms\LoadBalancer\$nonLocalDomainCache
DatabaseDomain[] $nonLocalDomainCache
Map of (domain ID => domain instance)
Definition: LoadBalancer.php:140
Wikimedia\Rdbms
Definition: ChronologyProtector.php:24
Wikimedia\Rdbms\LoadBalancer\$loadMonitorConfig
array $loadMonitorConfig
The LoadMonitor configuration.
Definition: LoadBalancer.php:85
Wikimedia\Rdbms\LoadBalancer\getServerName
getServerName( $i)
Get the host name or IP address of the server with the specified index.
Definition: LoadBalancer.php:1478
Wikimedia\Rdbms\DBMasterPos
An object representing a master or replica DB position in a replicated setup.
Definition: DBMasterPos.php:14
Wikimedia\Rdbms\LoadBalancer\initConnFlags
initConnFlags( $flags)
Definition: LoadBalancer.php:1380
Wikimedia\Rdbms\LoadBalancer\forEachOpenMasterConnection
forEachOpenMasterConnection( $callback, array $params=[])
Call a function with each open connection object to a master.
Definition: LoadBalancer.php:2144
BagOStuff
Class representing a cache/ephemeral data store.
Definition: BagOStuff.php:70
Wikimedia\Rdbms\LoadBalancer\getConnectionRef
getConnectionRef( $i, $groups=[], $domain=false, $flags=0)
Get a live database handle reference for a real or virtual (DB_MASTER/DB_REPLICA) server index.
Definition: LoadBalancer.php:1027
Wikimedia\Rdbms\LoadBalancer\$maxLag
int $maxLag
Definition: LoadBalancer.php:87
Wikimedia\Rdbms\LoadBalancer\$conns
IDatabase[][][] Database[][][] $conns
Map of (connection category => server index => IDatabase[])
Definition: LoadBalancer.php:74
Wikimedia\Rdbms\LoadBalancer\sanitizeConnectionFlags
sanitizeConnectionFlags( $flags, $i, $domain)
Definition: LoadBalancer.php:334
Wikimedia\Rdbms\LoadBalancer\getConnection
getConnection( $i, $groups=[], $domain=false, $flags=0)
Get a live handle for a real or virtual (DB_MASTER/DB_REPLICA) server index.
Definition: LoadBalancer.php:891
Wikimedia\Rdbms\DatabaseDomain\getDatabase
getDatabase()
Definition: DatabaseDomain.php:175
Wikimedia\Rdbms\LoadBalancer\enforceConnectionFlags
enforceConnectionFlags(IDatabase $conn, $flags)
Definition: LoadBalancer.php:372
Wikimedia\Rdbms\LoadBalancer\setExistingReaderIndex
setExistingReaderIndex( $group, $index)
Set the server index chosen by the load balancer for use with the given query group.
Definition: LoadBalancer.php:569
Wikimedia\Rdbms\LoadBalancer\getLagTimes
getLagTimes( $domain=false)
Get an estimate of replication lag (in seconds) for each server.
Definition: LoadBalancer.php:2202
$success
$success
Definition: NoLocalSettings.php:42
Wikimedia\Rdbms\IDatabase\getLag
getLag()
Get the amount of replication lag for this database server.
Wikimedia\Rdbms\LoadBalancer\$perfLogger
LoggerInterface $perfLogger
Definition: LoadBalancer.php:62
Wikimedia\Rdbms\LoadBalancer\$ownerId
int null $ownerId
Integer ID of the managing LBFactory instance or null if none.
Definition: LoadBalancer.php:137
Wikimedia\Rdbms\LoadBalancer\KEY_FOREIGN_INUSE
const KEY_FOREIGN_INUSE
Definition: LoadBalancer.php:159
Wikimedia\Rdbms\LoadBalancer\finalizeMasterChanges
finalizeMasterChanges( $fname=__METHOD__, $owner=null)
Run pre-commit callbacks and defer execution of post-commit callbacks.
Definition: LoadBalancer.php:1598
Wikimedia\Rdbms\LoadBalancer\$replLogger
LoggerInterface $replLogger
Definition: LoadBalancer.php:60
Wikimedia\Rdbms\LoadBalancer\doWait
doWait( $index, $open=false, $timeout=null)
Wait for a given replica DB to catch up to the master pos stored in "waitForPos".
Definition: LoadBalancer.php:822
Wikimedia\Rdbms\Database\getFlag
getFlag( $flag)
Returns a boolean whether the flag $flag is set for this connection.
Definition: Database.php:745
Wikimedia\Rdbms\LoadBalancer\flushMasterSnapshots
flushMasterSnapshots( $fname=__METHOD__, $owner=null)
Commit all master DB transactions so as to flush any REPEATABLE-READ or SSI snapshots.
Definition: LoadBalancer.php:1954
Wikimedia\Rdbms\DBError
Database error base class @newable.
Definition: DBError.php:31
Wikimedia\Rdbms\LoadBalancer\hasMasterChanges
hasMasterChanges()
Whether there are pending changes or callbacks in a transaction by this thread.
Definition: LoadBalancer.php:1973
Wikimedia\Rdbms\LoadBalancer\getServerAttributes
getServerAttributes( $i)
Definition: LoadBalancer.php:1239
Wikimedia\Rdbms\LoadBalancer\resolveDomainID
resolveDomainID( $domain)
Definition: LoadBalancer.php:272
DBO_TRX
const DBO_TRX
Definition: defines.php:12
Wikimedia\Rdbms\LoadBalancer\KEY_FOREIGN_INUSE_NOROUND
const KEY_FOREIGN_INUSE_NOROUND
Definition: LoadBalancer.php:163
Wikimedia\Rdbms\IDatabase\dbSchema
dbSchema( $schema=null)
Get/set the db schema.
Wikimedia\Rdbms\LoadBalancer\commitMasterChanges
commitMasterChanges( $fname=__METHOD__, $owner=null)
Issue COMMIT on all open master connections to flush changes and view snapshots.
Definition: LoadBalancer.php:1694
Wikimedia\Rdbms\LoadBalancer\getMaxLag
getMaxLag( $domain=false)
Get the hostname and lag time of the most-lagged replica server.
Definition: LoadBalancer.php:2183
Wikimedia\Rdbms\IDatabase
Basic database interface for live and lazy-loaded relation database handles.
Definition: IDatabase.php:38
Wikimedia\Rdbms\IDatabase\lastDoneWrites
lastDoneWrites()
Get the last time the connection may have been used for a write query.
Wikimedia\Rdbms\LoadBalancer\$INFO_SERVER_INDEX
static $INFO_SERVER_INDEX
Definition: LoadBalancer.php:142
Wikimedia\Rdbms\LoadBalancer\$deprecationLogger
callable $deprecationLogger
Deprecation logger.
Definition: LoadBalancer.php:66
Wikimedia\Rdbms\DatabaseDomain\newUnspecified
static newUnspecified()
Definition: DatabaseDomain.php:114
Wikimedia\Rdbms\LoadBalancer\$connectionAttempted
bool $connectionAttempted
Whether any connection has been attempted yet.
Definition: LoadBalancer.php:132
Wikimedia\Rdbms\LoadBalancer\allowLagged
allowLagged( $mode=null)
Disables/enables lag checks.
Definition: LoadBalancer.php:2114
WANObjectCache\newEmpty
static newEmpty()
Get an instance that wraps EmptyBagOStuff.
Definition: WANObjectCache.php:348
Wikimedia\Rdbms\MaintainableDBConnRef
Helper class to handle automatically marking connections as reusable (via RAII pattern) as well handl...
Definition: MaintainableDBConnRef.php:13
Wikimedia\Rdbms\LoadBalancer\setLocalDomain
setLocalDomain(DatabaseDomain $domain)
Definition: LoadBalancer.php:2392
Wikimedia\Rdbms\LoadBalancer\getReaderIndex
getReaderIndex( $group=false, $domain=false)
Get the server index of the reader connection for a given group.
Definition: LoadBalancer.php:499
Wikimedia\Rdbms\LoadBalancer\KEY_LOCAL_NOROUND
const KEY_LOCAL_NOROUND
Definition: LoadBalancer.php:161
Wikimedia\Rdbms\Database\runOnTransactionPreCommitCallbacks
runOnTransactionPreCommitCallbacks()
Actually consume and run any "on transaction pre-commit" callbacks.
Definition: Database.php:3901
Wikimedia\Rdbms\LoadBalancer\KEY_LOCAL
const KEY_LOCAL
Definition: LoadBalancer.php:157
Wikimedia\Rdbms\LoadBalancer\$tempTablesOnlyMode
bool[] $tempTablesOnlyMode
Map of (domain => whether to use "temp tables only" mode)
Definition: LoadBalancer.php:107
Wikimedia\Rdbms\LoadBalancer\$groupLoads
array[] $groupLoads
Map of (group => server index => weight)
Definition: LoadBalancer.php:79
Wikimedia\Rdbms\LoadBalancer\KEY_FOREIGN_FREE
const KEY_FOREIGN_FREE
Definition: LoadBalancer.php:158
Wikimedia\Rdbms\LoadBalancer\$id
$id
var int An identifier for this class instance
Definition: LoadBalancer.php:135
Wikimedia\Rdbms\LoadBalancer\getRandomNonLagged
getRandomNonLagged(array $loads, $domain=false, $maxLag=INF)
Definition: LoadBalancer.php:417
Wikimedia\Rdbms\LoadBalancer\$maxLagByIndex
int[] $maxLagByIndex
Map of (server index => seconds of lag considered "high")
Definition: LoadBalancer.php:81
Wikimedia\Rdbms\LoadBalancer\pickReaderIndex
pickReaderIndex(array $loads, $domain=false)
Definition: LoadBalancer.php:581
Wikimedia\Rdbms\LoadBalancer\pendingMasterChangeCallers
pendingMasterChangeCallers()
Get the list of callers that have pending master changes.
Definition: LoadBalancer.php:1998
Wikimedia\Rdbms\LoadBalancer\flushReplicaSnapshots
flushReplicaSnapshots( $fname=__METHOD__, $owner=null)
Commit all replica DB transactions so as to flush any REPEATABLE-READ or SSI snapshots.
Definition: LoadBalancer.php:1947
Wikimedia\Rdbms\LoadBalancer\closeAll
closeAll( $fname=__METHOD__, $owner=null)
Close all open connections.
Definition: LoadBalancer.php:1551
Wikimedia\Rdbms\Database\trxLevel
trxLevel()
Gets the current transaction level.
Definition: Database.php:493
Wikimedia\Rdbms\LoadBalancer\getMasterServerName
getMasterServerName()
Definition: LoadBalancer.php:2421
Wikimedia\Rdbms\Database\setFlag
setFlag( $flag, $remember=self::REMEMBER_NOTHING)
Set a flag for this connection.
Definition: Database.php:702
Wikimedia\Rdbms\LoadBalancer\setTempTablesOnlyMode
setTempTablesOnlyMode( $value, $domain)
Indicate whether the tables on this domain are only temporary tables for testing.
Definition: LoadBalancer.php:2378
Wikimedia\Rdbms\LoadBalancer\__destruct
__destruct()
Definition: LoadBalancer.php:2425
Wikimedia\Rdbms\LoadBalancer\reallyOpenConnection
reallyOpenConnection( $i, DatabaseDomain $domain, array $lbInfo)
Open a new network connection to a server (uncached)
Definition: LoadBalancer.php:1268
Wikimedia\Rdbms\LoadBalancer\hasMasterConnection
hasMasterConnection()
Definition: LoadBalancer.php:1969
Wikimedia\Rdbms\LoadBalancer\disable
disable( $fname=__METHOD__, $owner=null)
Close all connections and disable this load balancer.
Definition: LoadBalancer.php:1545
Wikimedia\Rdbms\LoadBalancer\applyTransactionRoundFlags
applyTransactionRoundFlags(Database $conn)
Make all DB servers with DBO_DEFAULT/DBO_TRX set join the transaction round.
Definition: LoadBalancer.php:1914
Wikimedia\Rdbms\LoadBalancer\forEachOpenConnection
forEachOpenConnection( $callback, array $params=[])
Call a function with each open connection object.
Definition: LoadBalancer.php:2134
Wikimedia\Rdbms\LoadBalancer\$srvCache
BagOStuff $srvCache
Definition: LoadBalancer.php:48
Wikimedia\Rdbms\LoadBalancer\isNonZeroLoad
isNonZeroLoad( $i)
Returns true if the specified index is valid and has non-zero load.
Definition: LoadBalancer.php:1456
Wikimedia\Rdbms\LoadBalancer\__construct
__construct(array $params)
Construct a manager of IDatabase connection objects.
Definition: LoadBalancer.php:178
Wikimedia\Rdbms\IDatabase\close
close( $fname=__METHOD__, $owner=null)
Close the database connection.
Wikimedia\Rdbms\LoadBalancer\waitForOne
waitForOne( $pos, $timeout=null)
Set the master wait position and wait for a generic replica DB to catch up to it.
Definition: LoadBalancer.php:675
Wikimedia\Rdbms\LoadBalancer\$hostname
string $hostname
Current server name.
Definition: LoadBalancer.php:92
Wikimedia\Rdbms\LoadBalancer\$errorLogger
callable $errorLogger
Exception logger.
Definition: LoadBalancer.php:64
Wikimedia\Rdbms\LoadBalancer\pingAll
pingAll()
Definition: LoadBalancer.php:2123
DB_REPLICA
const DB_REPLICA
Definition: defines.php:25
Wikimedia\Rdbms\LoadBalancer\$lastError
string $lastError
The last DB selection or connection error.
Definition: LoadBalancer.php:124
Wikimedia\Rdbms\LoadBalancer\forEachOpenReplicaConnection
forEachOpenReplicaConnection( $callback, array $params=[])
Call a function with each open replica DB connection object.
Definition: LoadBalancer.php:2156
Wikimedia\Rdbms\Database\restoreFlags
restoreFlags( $state=self::RESTORE_PRIOR)
Restore the flags to their prior state before the last setFlag/clearFlag call.
Definition: Database.php:732
DB_MASTER
const DB_MASTER
Definition: defines.php:26
Wikimedia\Rdbms\Database\setLBInfo
setLBInfo( $nameOrArray, $value=null)
Set the entire array or a particular key of the managing load balancer info array.
Definition: Database.php:559
Wikimedia\Rdbms\Database\getLBInfo
getLBInfo( $name=null)
Get properties passed down from the server info array of the load balancer.
Definition: Database.php:547
Wikimedia\Rdbms\IDatabase\assertNoOpenTransactions
assertNoOpenTransactions()
Assert that all explicit transactions or atomic sections have been closed.
Wikimedia\Rdbms\LoadBalancer
Database connection, tracking, load balancing, and transaction manager for a cluster.
Definition: LoadBalancer.php:42
Wikimedia\Rdbms\LoadBalancer\resolveGroups
resolveGroups( $groups, $i)
Resolve $groups into a list of query groups defining as having database servers.
Definition: LoadBalancer.php:308
Wikimedia\Rdbms\LoadBalancer\getMaintenanceConnectionRef
getMaintenanceConnectionRef( $i, $groups=[], $domain=false, $flags=0)
Get a live database handle for a real or virtual (DB_MASTER/DB_REPLICA) server index that can be used...
Definition: LoadBalancer.php:1041
Wikimedia\Rdbms\LoadBalancer\redefineLocalDomain
redefineLocalDomain( $domain)
Close all connection and redefine the local domain for testing or schema creation.
Definition: LoadBalancer.php:2372
Wikimedia\Rdbms\LoadBalancer\runMasterTransactionIdleCallbacks
runMasterTransactionIdleCallbacks( $fname=__METHOD__, $owner=null)
Consume and run all pending post-COMMIT/ROLLBACK callbacks and commit dangling transactions.
Definition: LoadBalancer.php:1734
Wikimedia\Rdbms\LoadBalancer\$chronologyCallback
callable null $chronologyCallback
Callback to run before the first connection attempt.
Definition: LoadBalancer.php:46
Wikimedia\Rdbms\LoadBalancer\getLoadMonitor
getLoadMonitor()
Get a LoadMonitor instance.
Definition: LoadBalancer.php:390
Wikimedia\Rdbms\LoadBalancer\$servers
array[] $servers
Map of (server index => server config array)
Definition: LoadBalancer.php:77
Wikimedia\Rdbms\LoadBalancer\setTransactionListener
setTransactionListener( $name, callable $callback=null)
Set a callback via IDatabase::setTransactionListener() on all current and future master connections o...
Definition: LoadBalancer.php:2315
Wikimedia\Rdbms\IDatabase\getDomainID
getDomainID()
Return the currently selected domain ID.
Wikimedia\Rdbms\IDatabase\setTransactionListener
setTransactionListener( $name, callable $callback=null)
Run a callback after each time any transaction commits or rolls back.
Wikimedia\Rdbms\IDatabase\getDBname
getDBname()
Get the current DB name.
WANObjectCache
Multi-datacenter aware caching interface.
Definition: WANObjectCache.php:125
Wikimedia\Rdbms\LoadBalancer\getLocalDomainID
getLocalDomainID()
Get the local (and default) database domain ID of connection handles.
Definition: LoadBalancer.php:268
Wikimedia\Rdbms\Database\setTrxEndCallbackSuppression
setTrxEndCallbackSuppression( $suppress)
Whether to disable running of post-COMMIT/ROLLBACK callbacks.
Definition: Database.php:3818
Wikimedia\Rdbms\LoadBalancer\getLocalConnection
getLocalConnection( $i, $flags=0)
Open a connection to a local DB, or return one if it is already open.
Definition: LoadBalancer.php:1084
Wikimedia\Rdbms\IDatabase\pendingWriteCallers
pendingWriteCallers()
Get the list of method names that did write queries for this transaction.
Wikimedia\Rdbms\LoadBalancer\setDomainAliases
setDomainAliases(array $aliases)
Convert certain database domains to alternative ones.
Definition: LoadBalancer.php:2336
Wikimedia\Rdbms\LoadBalancer\$connectionCounter
int $connectionCounter
Total number of new connections ever made with this instance.
Definition: LoadBalancer.php:128
Wikimedia\Rdbms\LoadBalancer\safeWaitForMasterPos
safeWaitForMasterPos(IDatabase $conn, $pos=false, $timeout=null)
Wait for a replica DB to reach a specified master position.
Definition: LoadBalancer.php:2311
Wikimedia\Rdbms\LoadBalancer\rollbackMasterChanges
rollbackMasterChanges( $fname=__METHOD__, $owner=null)
Issue ROLLBACK only on master, only if queries were done on connection.
Definition: LoadBalancer.php:1841
Wikimedia\Rdbms\LoadBalancer\getServerConnection
getServerConnection( $i, $domain, $flags=0)
Definition: LoadBalancer.php:924
Wikimedia\Rdbms\Database\getServer
getServer()
Get the server hostname or IP address.
Definition: Database.php:2649
Wikimedia\Rdbms\DBUnexpectedError
Definition: DBUnexpectedError.php:27
Wikimedia\Rdbms\LoadBalancer\getLazyConnectionRef
getLazyConnectionRef( $i, $groups=[], $domain=false, $flags=0)
Get a database handle reference for a real or virtual (DB_MASTER/DB_REPLICA) server index.
Definition: LoadBalancer.php:1034
Wikimedia\Rdbms\IDatabase\masterPosWait
masterPosWait(DBMasterPos $pos, $timeout)
Wait for the replica DB to catch up to a given master position.
Wikimedia\Rdbms\LoadBalancer\$trxRoundStage
string $trxRoundStage
Stage of the current transaction round in the transaction round life-cycle.
Definition: LoadBalancer.php:112
Wikimedia\Rdbms\LoadBalancer\$indexAliases
string[] $indexAliases
Map of (index alias => index)
Definition: LoadBalancer.php:101
Wikimedia\Rdbms\LoadBalancer\beginMasterChanges
beginMasterChanges( $fname=__METHOD__, $owner=null)
Flush any master transaction snapshots and set DBO_TRX (if DBO_DEFAULT is set)
Definition: LoadBalancer.php:1665
Wikimedia\Rdbms\LoadBalancer\$readOnlyReason
string bool $readOnlyReason
Reason this instance is read-only or false if not.
Definition: LoadBalancer.php:126
Wikimedia\Rdbms\LoadBalancer\getTransactionRoundStage
getTransactionRoundStage()
Definition: LoadBalancer.php:1965
Wikimedia\Rdbms\LoadBalancer\hasStreamingReplicaServers
hasStreamingReplicaServers()
Whether any replica servers use streaming replication from the master server.
Definition: LoadBalancer.php:1468
Wikimedia\Rdbms\LoadBalancer\getForeignConnection
getForeignConnection( $i, $domain, $flags=0)
Open a connection to a foreign DB, or return one if it is already open.
Definition: LoadBalancer.php:1146
Wikimedia\Rdbms\LoadBalancer\$defaultGroup
string null $defaultGroup
Default query group to use with getConnection()
Definition: LoadBalancer.php:89
Wikimedia\Rdbms\DBConnRef
Helper class used for automatically marking an IDatabase connection as reusable (once it no longer ma...
Definition: DBConnRef.php:29
Wikimedia\Rdbms\LoadBalancer\setTableAliases
setTableAliases(array $aliases)
Make certain table names use their own database, schema, and table prefix when passed into SQL querie...
Definition: LoadBalancer.php:2328
Wikimedia\Rdbms\DBTransactionError
Definition: DBTransactionError.php:27
Wikimedia\Rdbms\LoadBalancer\assertTransactionRoundStage
assertTransactionRoundStage( $stage)
Definition: LoadBalancer.php:1867
Wikimedia\Rdbms\LoadBalancer\isMasterRunningReadOnly
isMasterRunningReadOnly(DatabaseDomain $domain)
Definition: LoadBalancer.php:2082
Wikimedia\Rdbms\LoadBalancer\$localDomain
DatabaseDomain $localDomain
Local DB domain ID and default for selectDB() calls.
Definition: LoadBalancer.php:69
Wikimedia\Rdbms\LoadBalancer\pickAnyOpenConnection
pickAnyOpenConnection( $candidateConns, $autocommit)
Definition: LoadBalancer.php:791
Wikimedia\Rdbms\LoadBalancer\$waitForPos
bool DBMasterPos $waitForPos
Replication sync position or false if not set.
Definition: LoadBalancer.php:118
ArrayUtils\pickRandom
static pickRandom( $weights)
Given an array of non-normalised probabilities, this function will select an element and return the a...
Definition: ArrayUtils.php:66
Wikimedia\Rdbms\LoadBalancer\getAnyOpenConnection
getAnyOpenConnection( $i, $flags=0)
Get any open connection to a given server index, local or foreign.
Definition: LoadBalancer.php:756
ArrayUtils
A collection of static methods to play with arrays.
Definition: ArrayUtils.php:28
Wikimedia\Rdbms\LoadBalancer\$disabled
bool $disabled
Definition: LoadBalancer.php:130
Wikimedia\Rdbms\LoadBalancer\getLaggedReplicaMode
getLaggedReplicaMode( $domain=false)
Definition: LoadBalancer.php:2007
Wikimedia\Rdbms\LoadBalancer\commitAll
commitAll( $fname=__METHOD__, $owner=null)
Commit transactions on all open connections.
Definition: LoadBalancer.php:1592
Wikimedia\Rdbms\LoadBalancer\$INFO_FORIEGN
static $INFO_FORIEGN
Definition: LoadBalancer.php:144
Wikimedia\Rdbms\Database\writesPending
writesPending()
Definition: Database.php:595
Wikimedia\Rdbms\LoadBalancer\hasReplicaServers
hasReplicaServers()
Whether there are any replica servers configured.
Definition: LoadBalancer.php:1464
Wikimedia\Rdbms\DatabaseDomain\getSchema
getSchema()
Definition: DatabaseDomain.php:182
Wikimedia\Rdbms\LoadBalancer\runMasterTransactionListenerCallbacks
runMasterTransactionListenerCallbacks( $fname=__METHOD__, $owner=null)
Run all recurring post-COMMIT/ROLLBACK listener callbacks.
Definition: LoadBalancer.php:1809
Wikimedia\Rdbms\Database\runTransactionListenerCallbacks
runTransactionListenerCallbacks( $trigger)
Actually run any "transaction listener" callbacks.
Definition: Database.php:3977
Wikimedia\Rdbms\LoadBalancer\$errorConnection
Database $errorConnection
Connection handle that caused a problem.
Definition: LoadBalancer.php:114
Wikimedia\Rdbms\DBConnectionError
Definition: DBConnectionError.php:26
Wikimedia\Rdbms\IDatabase\getLBInfo
getLBInfo( $name=null)
Get properties passed down from the server info array of the load balancer.
Wikimedia\Rdbms\LoadBalancer\$profiler
mixed $profiler
Class name or object With profileIn/profileOut methods.
Definition: LoadBalancer.php:52
Wikimedia\Rdbms\LoadBalancer\getTopologyRole
getTopologyRole( $i, array $server)
Definition: LoadBalancer.php:1365
Wikimedia\Rdbms\LoadBalancer\resolveDomainInstance
resolveDomainInstance( $domain)
Definition: LoadBalancer.php:280
Wikimedia\Rdbms\LoadBalancer\haveIndex
haveIndex( $i)
Returns true if the specified index is a valid server index.
Definition: LoadBalancer.php:1445
Wikimedia\Rdbms\LoadBalancer\getReplicaResumePos
getReplicaResumePos()
Get the highest DB replication position for chronology control purposes.
Definition: LoadBalancer.php:1515
Wikimedia\Rdbms\DBMasterPos\hasReached
hasReached(DBMasterPos $pos)
Wikimedia\Rdbms\LoadBalancer\$trxRecurringCallbacks
callable[] $trxRecurringCallbacks
Map of (name => callable)
Definition: LoadBalancer.php:105
Wikimedia\Rdbms\LoadBalancer\getReadOnlyReason
getReadOnlyReason( $domain=false)
Definition: LoadBalancer.php:2024
Wikimedia\Rdbms\Database\attributesFromType
static attributesFromType( $dbType, $driver=null)
Definition: Database.php:450
Wikimedia\Rdbms\LoadBalancer\$INFO_AUTOCOMMIT_ONLY
static $INFO_AUTOCOMMIT_ONLY
Definition: LoadBalancer.php:143
Wikimedia\Rdbms\IDatabase\serverIsReadOnly
serverIsReadOnly()
Wikimedia\Rdbms\LoadBalancer\reuseConnection
reuseConnection(IDatabase $conn)
Mark a live handle as being available for reuse under a different database domain.
Definition: LoadBalancer.php:977
Wikimedia\Rdbms\LoadBalancer\$readIndexByGroup
int[] $readIndexByGroup
The group replica server indexes keyed by group.
Definition: LoadBalancer.php:116
Wikimedia\Rdbms\LoadBalancer\setIndexAliases
setIndexAliases(array $aliases)
Convert certain index names to alternative names before querying the DB.
Definition: LoadBalancer.php:2332
Wikimedia\Rdbms\LoadBalancer\laggedReplicaUsed
laggedReplicaUsed()
Checks whether the database for generic connections this request was both:
Definition: LoadBalancer.php:2020
Wikimedia\Rdbms\LoadBalancer\$wanCache
WANObjectCache $wanCache
Definition: LoadBalancer.php:50
Wikimedia\Rdbms\LoadBalancer\undoTransactionRoundFlags
undoTransactionRoundFlags(Database $conn)
Definition: LoadBalancer.php:1933
Wikimedia\Rdbms\LoadBalancer\$agent
string $agent
Agent name for query profiling.
Definition: LoadBalancer.php:96
Wikimedia\Rdbms\DatabaseDomain
Class to handle database/schema/prefix specifications for IDatabase.
Definition: DatabaseDomain.php:40
Wikimedia\Rdbms\TransactionProfiler
Detect high-contention DB queries via profiling calls.
Definition: TransactionProfiler.php:38
Wikimedia\Rdbms\LoadBalancer\$laggedReplicaMode
bool $laggedReplicaMode
Whether the generic reader fell back to a lagged replica DB.
Definition: LoadBalancer.php:122
Wikimedia\Rdbms\LoadBalancer\$queryLogger
LoggerInterface $queryLogger
Definition: LoadBalancer.php:58
Wikimedia\Rdbms\LoadBalancer\$loadMonitor
ILoadMonitor $loadMonitor
Definition: LoadBalancer.php:44
Wikimedia\Rdbms\LoadBalancer\openConnection
openConnection( $i, $domain=false, $flags=0)
Definition: LoadBalancer.php:1066
DBO_DEFAULT
const DBO_DEFAULT
Definition: defines.php:13
Wikimedia\Rdbms\LoadBalancer\waitForAll
waitForAll( $pos, $timeout=null)
Set the master wait position and wait for ALL replica DBs to catch up to it.
Definition: LoadBalancer.php:702
Wikimedia\Rdbms\LoadBalancer\isMasterConnectionReadOnly
isMasterConnectionReadOnly(IDatabase $conn, $flags=0)
Definition: LoadBalancer.php:2045
Wikimedia\Rdbms\LoadBalancer\$connLogger
LoggerInterface $connLogger
Definition: LoadBalancer.php:56
Wikimedia\Rdbms\LoadBalancer\waitFor
waitFor( $pos)
Set the master position to reach before the next generic group DB handle query.
Definition: LoadBalancer.php:659
Wikimedia\Rdbms\LoadBalancer\lastMasterChangeTimestamp
lastMasterChangeTimestamp()
Get the timestamp of the latest write query done by this thread.
Definition: LoadBalancer.php:1982
Wikimedia\Rdbms\LoadBalancer\$cliMode
bool $cliMode
Whether this PHP instance is for a CLI script.
Definition: LoadBalancer.php:94
Wikimedia\Rdbms\ILoadBalancer
Database cluster connection, tracking, load balancing, and transaction manager interface.
Definition: ILoadBalancer.php:81
Wikimedia\Rdbms\LoadBalancer\getServerCount
getServerCount()
Get the number of servers defined in configuration.
Definition: LoadBalancer.php:1460
Wikimedia\Rdbms\IDatabase\commit
commit( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
Commits a transaction previously started using begin()
Wikimedia\Rdbms\LoadBalancer\closeConnection
closeConnection(IDatabase $conn)
Close a connection.
Definition: LoadBalancer.php:1566
Wikimedia\Rdbms\LoadBalancer\KEY_FOREIGN_FREE_NOROUND
const KEY_FOREIGN_FREE_NOROUND
Definition: LoadBalancer.php:162
Wikimedia\Rdbms\IDatabase\flushSnapshot
flushSnapshot( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
Commit any transaction but error out if writes or callbacks are pending.
Wikimedia\Rdbms\LoadBalancer\reportConnectionError
reportConnectionError()
Definition: LoadBalancer.php:1406
Wikimedia\Rdbms\LoadBalancer\$INFO_FOREIGN_REF_COUNT
static $INFO_FOREIGN_REF_COUNT
Definition: LoadBalancer.php:145
Wikimedia\Rdbms\IDatabase\clearFlag
clearFlag( $flag, $remember=self::REMEMBER_NOTHING)
Clear a flag for this connection.
Wikimedia\Rdbms\LoadBalancer\$tableAliases
array[] $tableAliases
$aliases Map of (table => (dbname, schema, prefix) map)
Definition: LoadBalancer.php:99
$type
$type
Definition: testCompression.php:52
Wikimedia\Rdbms\LoadBalancer\getRoleFromIndex
getRoleFromIndex( $i)
Definition: LoadBalancer.php:1053
Wikimedia\Rdbms\IDatabase\writesOrCallbacksPending
writesOrCallbacksPending()
Whether there is a transaction open with either possible write queries or unresolved pre-commit/commi...