MediaWiki  master
ILoadBalancer.php
Go to the documentation of this file.
1 <?php
23 namespace Wikimedia\Rdbms;
24 
25 use Exception;
26 use LogicException;
28 
81 interface ILoadBalancer {
83  const DB_REPLICA = -1;
85  const DB_MASTER = -2;
86 
88  const DOMAIN_ANY = '';
90  const GROUP_GENERIC = '';
91 
93  const CONN_TRX_AUTOCOMMIT = 1;
95  const CONN_SILENCE_ERRORS = 2;
97  const CONN_INTENT_WRITABLE = 4;
99  const CONN_REFRESH_READ_ONLY = 8;
100 
102  const STAGE_POSTCOMMIT_CALLBACKS = 'stage-postcommit-callbacks';
104  const STAGE_POSTROLLBACK_CALLBACKS = 'stage-postrollback-callbacks';
105 
134  public function __construct( array $params );
135 
143  public function getLocalDomainID();
144 
150  public function resolveDomainID( $domain );
151 
158  public function redefineLocalDomain( $domain );
159 
170  public function setTempTablesOnlyMode( $value, $domain );
171 
186  public function getReaderIndex( $group = false, $domain = false );
187 
200  public function waitFor( $pos );
201 
211  public function waitForOne( $pos, $timeout = null );
212 
220  public function waitForAll( $pos, $timeout = null );
221 
233  public function getAnyOpenConnection( $i, $flags = 0 );
234 
297  public function getConnection( $i, $groups = [], $domain = false, $flags = 0 );
298 
314  public function getServerConnection( $i, $domain, $flags = 0 );
315 
329  public function reuseConnection( IDatabase $conn );
330 
347  public function getConnectionRef( $i, $groups = [], $domain = false, $flags = 0 );
348 
368  public function getLazyConnectionRef( $i, $groups = [], $domain = false, $flags = 0 );
369 
390  public function getMaintenanceConnectionRef( $i, $groups = [], $domain = false, $flags = 0 );
391 
397  public function getWriterIndex();
398 
404  public function getServerCount();
405 
415  public function hasReplicaServers();
416 
436  public function hasStreamingReplicaServers();
437 
444  public function getServerName( $i );
445 
452  public function getServerInfo( $i );
453 
461  public function getServerType( $i );
462 
468  public function getServerAttributes( $i );
469 
476  public function getMasterPos();
477 
493  public function getReplicaResumePos();
494 
503  public function disable( $fname = __METHOD__, $owner = null );
504 
511  public function closeAll( $fname = __METHOD__, $owner = null );
512 
521  public function closeConnection( IDatabase $conn );
522 
529  public function commitAll( $fname = __METHOD__, $owner = null );
530 
540  public function finalizeMasterChanges( $fname = __METHOD__, $owner = null );
541 
553  public function approveMasterChanges( array $options, $fname, $owner = null );
554 
568  public function beginMasterChanges( $fname = __METHOD__, $owner = null );
569 
576  public function commitMasterChanges( $fname = __METHOD__, $owner = null );
577 
585  public function runMasterTransactionIdleCallbacks( $fname = __METHOD__, $owner = null );
586 
594  public function runMasterTransactionListenerCallbacks( $fname = __METHOD__, $owner = null );
595 
602  public function rollbackMasterChanges( $fname = __METHOD__, $owner = null );
603 
610  public function flushReplicaSnapshots( $fname = __METHOD__, $owner = null );
611 
620  public function flushMasterSnapshots( $fname = __METHOD__, $owner = null );
621 
625  public function hasMasterConnection();
626 
631  public function hasMasterChanges();
632 
637  public function lastMasterChangeTimestamp();
638 
646  public function hasOrMadeRecentMasterChanges( $age = null );
647 
653  public function pendingMasterChangeCallers();
654 
660  public function getLaggedReplicaMode( $domain = false );
661 
670  public function laggedReplicaUsed();
671 
677  public function getReadOnlyReason( $domain = false );
678 
684  public function allowLagged( $mode = null );
685 
689  public function pingAll();
690 
696  public function forEachOpenConnection( $callback, array $params = [] );
697 
703  public function forEachOpenMasterConnection( $callback, array $params = [] );
704 
710  public function forEachOpenReplicaConnection( $callback, array $params = [] );
711 
722  public function getMaxLag( $domain = false );
723 
734  public function getLagTimes( $domain = false );
735 
749  public function waitForMasterPos( IDatabase $conn, $pos = false, $timeout = 10 );
750 
758  public function setTransactionListener( $name, callable $callback = null );
759 
766  public function setLocalDomainPrefix( $prefix );
767 
780  public function setTableAliases( array $aliases );
781 
794  public function setIndexAliases( array $aliases );
795 }
commitMasterChanges( $fname=__METHOD__, $owner=null)
Issue COMMIT on all open master connections to flush changes and view snapshots.
waitFor( $pos)
Set the master position to reach before the next generic group DB handle query.
getAnyOpenConnection( $i, $flags=0)
Get any open connection to a given server index, local or foreign.
flushMasterSnapshots( $fname=__METHOD__, $owner=null)
Commit all master DB transactions so as to flush any REPEATABLE-READ or SSI snapshots.
forEachOpenMasterConnection( $callback, array $params=[])
Call a function with each open connection object to a master.
getConnection( $i, $groups=[], $domain=false, $flags=0)
Get a live handle for a real or virtual (DB_MASTER/DB_REPLICA) server index.
redefineLocalDomain( $domain)
Close all connection and redefine the local domain for testing or schema creation.
getLagTimes( $domain=false)
Get an estimate of replication lag (in seconds) for each server.
setLocalDomainPrefix( $prefix)
Set a new table prefix for the existing local domain ID for testing.
closeConnection(IDatabase $conn)
Close a connection.
getLazyConnectionRef( $i, $groups=[], $domain=false, $flags=0)
Get a database handle reference for a real or virtual (DB_MASTER/DB_REPLICA) server index...
runMasterTransactionIdleCallbacks( $fname=__METHOD__, $owner=null)
Consume and run all pending post-COMMIT/ROLLBACK callbacks and commit dangling transactions.
const DB_MASTER
Definition: defines.php:26
getServerType( $i)
Get DB type of the server with the specified index.
waitForAll( $pos, $timeout=null)
Set the master wait position and wait for ALL replica DBs to catch up to it.
getServerCount()
Get the number of servers defined in configuration.
getReaderIndex( $group=false, $domain=false)
Get the server index of the reader connection for a given group.
flushReplicaSnapshots( $fname=__METHOD__, $owner=null)
Commit all replica DB transactions so as to flush any REPEATABLE-READ or SSI snapshots.
lastMasterChangeTimestamp()
Get the timestamp of the latest write query done by this thread.
hasMasterChanges()
Whether there are pending changes or callbacks in a transaction by this thread.
allowLagged( $mode=null)
Disables/enables lag checks.
getServerName( $i)
Get the host name or IP address of the server with the specified index.
setIndexAliases(array $aliases)
Convert certain index names to alternative names before querying the DB.
forEachOpenReplicaConnection( $callback, array $params=[])
Call a function with each open replica DB connection object.
forEachOpenConnection( $callback, array $params=[])
Call a function with each open connection object.
laggedReplicaUsed()
Checks whether the database for generic connections this request was both:
rollbackMasterChanges( $fname=__METHOD__, $owner=null)
Issue ROLLBACK only on master, only if queries were done on connection.
hasStreamingReplicaServers()
Whether any replica servers use streaming replication from the master server.
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...
beginMasterChanges( $fname=__METHOD__, $owner=null)
Flush any master transaction snapshots and set DBO_TRX (if DBO_DEFAULT is set)
getServerConnection( $i, $domain, $flags=0)
Get a live handle for a server index.
disable( $fname=__METHOD__, $owner=null)
Close all connections and disable this load balancer.
getServerInfo( $i)
Return the server info structure for a given index or false if the index is invalid.
getReadOnlyReason( $domain=false)
hasOrMadeRecentMasterChanges( $age=null)
Check if this load balancer object had any recent or still pending writes issued against it by this P...
getConnectionRef( $i, $groups=[], $domain=false, $flags=0)
Get a live database handle reference for a real or virtual (DB_MASTER/DB_REPLICA) server index...
runMasterTransactionListenerCallbacks( $fname=__METHOD__, $owner=null)
Run all recurring post-COMMIT/ROLLBACK listener callbacks.
getLaggedReplicaMode( $domain=false)
getWriterIndex()
Get the server index of the master server.
Database cluster connection, tracking, load balancing, and transaction manager interface.
Basic database interface for live and lazy-loaded relation database handles.
Definition: IDatabase.php:38
hasReplicaServers()
Whether there are any replica servers configured.
getMasterPos()
Get the current master replication position.
reuseConnection(IDatabase $conn)
Mark a live handle as being available for reuse under a different database domain.
approveMasterChanges(array $options, $fname, $owner=null)
Perform all pre-commit checks for things like replication safety.
waitForOne( $pos, $timeout=null)
Set the master wait position and wait for a generic replica DB to catch up to it. ...
commitAll( $fname=__METHOD__, $owner=null)
Commit transactions on all open connections.
setTableAliases(array $aliases)
Make certain table names use their own database, schema, and table prefix when passed into SQL querie...
closeAll( $fname=__METHOD__, $owner=null)
Close all open connections.
getLocalDomainID()
Get the local (and default) database domain ID of connection handles.
const DB_REPLICA
Definition: defines.php:25
waitForMasterPos(IDatabase $conn, $pos=false, $timeout=10)
Wait for a replica DB to reach a specified master position.
__construct(array $params)
Construct a manager of IDatabase connection objects.
setTempTablesOnlyMode( $value, $domain)
Indicate whether the tables on this domain are only temporary tables for testing. ...
getReplicaResumePos()
Get the highest DB replication position for chronology control purposes.
finalizeMasterChanges( $fname=__METHOD__, $owner=null)
Run pre-commit callbacks and defer execution of post-commit callbacks.
pendingMasterChangeCallers()
Get the list of callers that have pending master changes.
getMaxLag( $domain=false)
Get the hostname and lag time of the most-lagged replica server.
setTransactionListener( $name, callable $callback=null)
Set a callback via IDatabase::setTransactionListener() on all current and future master connections o...