MediaWiki  master
ILoadBalancer.php
Go to the documentation of this file.
1 <?php
23 namespace Wikimedia\Rdbms;
24 
25 use Exception;
26 use InvalidArgumentException;
27 use LogicException;
28 
81 interface ILoadBalancer {
83  public const DB_REPLICA = -1;
88  public const DB_PRIMARY = -2;
89 
90  // phpcs:disable MediaWiki.Usage.DeprecatedConstantUsage.DB_MASTER
95  public const DB_MASTER = self::DB_PRIMARY;
96  // phpcs:enable MediaWiki.Usage.DeprecatedConstantUsage.DB_MASTER
97 
99  public const DOMAIN_ANY = '';
101  public const GROUP_GENERIC = '';
102 
104  public const CONN_TRX_AUTOCOMMIT = 1;
106  public const CONN_SILENCE_ERRORS = 2;
108  public const CONN_INTENT_WRITABLE = 4;
110  public const CONN_REFRESH_READ_ONLY = 8;
111 
113  public const STAGE_POSTCOMMIT_CALLBACKS = 'stage-postcommit-callbacks';
115  public const STAGE_POSTROLLBACK_CALLBACKS = 'stage-postrollback-callbacks';
116 
147  public function __construct( array $params );
148 
163  public function getClusterName();
164 
172  public function getLocalDomainID();
173 
179  public function resolveDomainID( $domain );
180 
187  public function redefineLocalDomain( $domain );
188 
199  public function setTempTablesOnlyMode( $value, $domain );
200 
215  public function getReaderIndex( $group = false, $domain = false );
216 
230  public function waitFor( $pos );
231 
244  public function waitForOne( $pos, $timeout = null );
245 
256  public function waitForAll( $pos, $timeout = null );
257 
271  public function getAnyOpenConnection( $i, $flags = 0 );
272 
335  public function getConnection( $i, $groups = [], $domain = false, $flags = 0 );
336 
352  public function getServerConnection( $i, $domain, $flags = 0 );
353 
367  public function reuseConnection( IDatabase $conn );
368 
385  public function getConnectionRef( $i, $groups = [], $domain = false, $flags = 0 );
386 
408  public function getLazyConnectionRef( $i, $groups = [], $domain = false, $flags = 0 );
409 
431  public function getMaintenanceConnectionRef( $i, $groups = [], $domain = false, $flags = 0 );
432 
438  public function getWriterIndex();
439 
445  public function getServerCount();
446 
456  public function hasReplicaServers();
457 
477  public function hasStreamingReplicaServers();
478 
485  public function getServerName( $i );
486 
494  public function getServerInfo( $i );
495 
503  public function getServerType( $i );
504 
512  public function getServerAttributes( $i );
513 
520  public function getMasterPos();
521 
537  public function getReplicaResumePos();
538 
547  public function disable( $fname = __METHOD__, $owner = null );
548 
555  public function closeAll( $fname = __METHOD__, $owner = null );
556 
565  public function closeConnection( IDatabase $conn );
566 
573  public function commitAll( $fname = __METHOD__, $owner = null );
574 
584  public function finalizeMasterChanges( $fname = __METHOD__, $owner = null );
585 
597  public function approveMasterChanges( array $options, $fname = __METHOD__, $owner = null );
598 
612  public function beginMasterChanges( $fname = __METHOD__, $owner = null );
613 
620  public function commitMasterChanges( $fname = __METHOD__, $owner = null );
621 
629  public function runMasterTransactionIdleCallbacks( $fname = __METHOD__, $owner = null );
630 
638  public function runMasterTransactionListenerCallbacks( $fname = __METHOD__, $owner = null );
639 
646  public function rollbackMasterChanges( $fname = __METHOD__, $owner = null );
647 
654  public function flushReplicaSnapshots( $fname = __METHOD__, $owner = null );
655 
664  public function flushMasterSnapshots( $fname = __METHOD__, $owner = null );
665 
669  public function hasMasterConnection();
670 
675  public function hasMasterChanges();
676 
681  public function lastMasterChangeTimestamp();
682 
690  public function hasOrMadeRecentMasterChanges( $age = null );
691 
697  public function pendingMasterChangeCallers();
698 
704  public function getLaggedReplicaMode( $domain = false );
705 
714  public function laggedReplicaUsed();
715 
721  public function getReadOnlyReason( $domain = false );
722 
728  public function allowLagged( $mode = null );
729 
733  public function pingAll();
734 
740  public function forEachOpenConnection( $callback, array $params = [] );
741 
747  public function forEachOpenMasterConnection( $callback, array $params = [] );
748 
754  public function forEachOpenReplicaConnection( $callback, array $params = [] );
755 
766  public function getMaxLag( $domain = false );
767 
778  public function getLagTimes( $domain = false );
779 
793  public function waitForMasterPos( IDatabase $conn, $pos = false, $timeout = 10 );
794 
802  public function setTransactionListener( $name, callable $callback = null );
803 
810  public function setLocalDomainPrefix( $prefix );
811 
824  public function setTableAliases( array $aliases );
825 
838  public function setIndexAliases( array $aliases );
839 
848  public function setDomainAliases( array $aliases );
849 }
Wikimedia\Rdbms\ILoadBalancer\getClusterName
getClusterName()
Get the logical name of the database cluster.
Wikimedia\Rdbms\ILoadBalancer\pendingMasterChangeCallers
pendingMasterChangeCallers()
Get the list of callers that have pending primary changes.
Wikimedia\Rdbms\ILoadBalancer\resolveDomainID
resolveDomainID( $domain)
Wikimedia\Rdbms\ILoadBalancer\STAGE_POSTCOMMIT_CALLBACKS
const STAGE_POSTCOMMIT_CALLBACKS
Manager of ILoadBalancer instances is running post-commit callbacks.
Definition: ILoadBalancer.php:113
Wikimedia\Rdbms\ILoadBalancer\pingAll
pingAll()
Wikimedia\Rdbms\ILoadBalancer\GROUP_GENERIC
const GROUP_GENERIC
The generic query group.
Definition: ILoadBalancer.php:101
Wikimedia\Rdbms\ILoadBalancer\setTempTablesOnlyMode
setTempTablesOnlyMode( $value, $domain)
Indicate whether the tables on this domain are only temporary tables for testing.
Wikimedia\Rdbms\ILoadBalancer\waitForAll
waitForAll( $pos, $timeout=null)
Set the primary wait position and wait for ALL replica DBs to catch up to it.
Wikimedia\Rdbms\ILoadBalancer\redefineLocalDomain
redefineLocalDomain( $domain)
Close all connection and redefine the local domain for testing or schema creation.
Wikimedia\Rdbms\ILoadBalancer\forEachOpenMasterConnection
forEachOpenMasterConnection( $callback, array $params=[])
Call a function with each open connection object to a primary.
Wikimedia\Rdbms\ILoadBalancer\setIndexAliases
setIndexAliases(array $aliases)
Convert certain index names to alternative names before querying the DB.
Wikimedia\Rdbms\ILoadBalancer\getServerInfo
getServerInfo( $i)
Return the server configuration map for the server with the specified index.
Wikimedia\Rdbms\ILoadBalancer\getLazyConnectionRef
getLazyConnectionRef( $i, $groups=[], $domain=false, $flags=0)
Get a lazy-connecting database handle reference for a server index.
Wikimedia\Rdbms\ILoadBalancer\DB_PRIMARY
const DB_PRIMARY
Request a primary, write-enabled DB connection.
Definition: ILoadBalancer.php:88
Wikimedia\Rdbms\ILoadBalancer\getConnection
getConnection( $i, $groups=[], $domain=false, $flags=0)
Get a live handle for a specific or virtual (DB_PRIMARY/DB_REPLICA) server index.
Wikimedia\Rdbms\ILoadBalancer\getReadOnlyReason
getReadOnlyReason( $domain=false)
Wikimedia\Rdbms\ILoadBalancer\disable
disable( $fname=__METHOD__, $owner=null)
Close all connections and disable this load balancer.
Wikimedia\Rdbms
Definition: ChronologyProtector.php:24
Wikimedia\Rdbms\ILoadBalancer\DB_MASTER
const DB_MASTER
Request a primary, write-enabled DB connection.
Definition: ILoadBalancer.php:95
Wikimedia\Rdbms\ILoadBalancer\getServerCount
getServerCount()
Get the number of servers defined in configuration.
Wikimedia\Rdbms\ILoadBalancer\setLocalDomainPrefix
setLocalDomainPrefix( $prefix)
Set a new table prefix for the existing local domain ID for testing.
Wikimedia\Rdbms\ILoadBalancer\runMasterTransactionIdleCallbacks
runMasterTransactionIdleCallbacks( $fname=__METHOD__, $owner=null)
Consume and run all pending post-COMMIT/ROLLBACK callbacks and commit dangling transactions.
Wikimedia\Rdbms\ILoadBalancer\getConnectionRef
getConnectionRef( $i, $groups=[], $domain=false, $flags=0)
Get a live database handle reference for a server index.
Wikimedia\Rdbms\ILoadBalancer\runMasterTransactionListenerCallbacks
runMasterTransactionListenerCallbacks( $fname=__METHOD__, $owner=null)
Run all recurring post-COMMIT/ROLLBACK listener callbacks.
Wikimedia\Rdbms\IDatabase
Basic database interface for live and lazy-loaded relation database handles.
Definition: IDatabase.php:38
Wikimedia\Rdbms\ILoadBalancer\setTableAliases
setTableAliases(array $aliases)
Make certain table names use their own database, schema, and table prefix when passed into SQL querie...
Wikimedia\Rdbms\ILoadBalancer\getServerAttributes
getServerAttributes( $i)
Get basic attributes of the server with the specified index without connecting.
Wikimedia\Rdbms\ILoadBalancer\allowLagged
allowLagged( $mode=null)
Disables/enables lag checks.
Wikimedia\Rdbms\ILoadBalancer\hasReplicaServers
hasReplicaServers()
Whether there are any replica servers configured.
Wikimedia\Rdbms\ILoadBalancer\approveMasterChanges
approveMasterChanges(array $options, $fname=__METHOD__, $owner=null)
Perform all pre-commit checks for things like replication safety.
Wikimedia\Rdbms\ILoadBalancer\reuseConnection
reuseConnection(IDatabase $conn)
Mark a live handle as being available for reuse under a different database domain.
Wikimedia\Rdbms\ILoadBalancer\getServerName
getServerName( $i)
Get the readable name of the server with the specified index.
Wikimedia\Rdbms\ILoadBalancer\forEachOpenConnection
forEachOpenConnection( $callback, array $params=[])
Call a function with each open connection object.
Wikimedia\Rdbms\ILoadBalancer\beginMasterChanges
beginMasterChanges( $fname=__METHOD__, $owner=null)
Flush any primary transaction snapshots and set DBO_TRX (if DBO_DEFAULT is set)
Wikimedia\Rdbms\ILoadBalancer\getMaxLag
getMaxLag( $domain=false)
Get the name and lag time of the most-lagged replica server.
Wikimedia\Rdbms\ILoadBalancer\getLocalDomainID
getLocalDomainID()
Get the local (and default) database domain ID of connection handles.
Wikimedia\Rdbms\ILoadBalancer\CONN_SILENCE_ERRORS
const CONN_SILENCE_ERRORS
Return null on connection failure instead of throwing an exception.
Definition: ILoadBalancer.php:106
Wikimedia\Rdbms\ILoadBalancer\getMasterPos
getMasterPos()
Get the current primary replication position.
Wikimedia\Rdbms\ILoadBalancer\hasMasterConnection
hasMasterConnection()
Wikimedia\Rdbms\ILoadBalancer\setTransactionListener
setTransactionListener( $name, callable $callback=null)
Set a callback via IDatabase::setTransactionListener() on all current and future primary connections ...
Wikimedia\Rdbms\ILoadBalancer\getWriterIndex
getWriterIndex()
Get the specific server index of the primary server.
Wikimedia\Rdbms\ILoadBalancer\getMaintenanceConnectionRef
getMaintenanceConnectionRef( $i, $groups=[], $domain=false, $flags=0)
Get a live database handle, suitable for migrations and schema changes, for a server index.
Wikimedia\Rdbms\ILoadBalancer\setDomainAliases
setDomainAliases(array $aliases)
Convert certain database domains to alternative ones.
Wikimedia\Rdbms\ILoadBalancer\waitFor
waitFor( $pos)
Set the primary position to reach before the next generic group DB handle query.
Wikimedia\Rdbms\ILoadBalancer\flushMasterSnapshots
flushMasterSnapshots( $fname=__METHOD__, $owner=null)
Commit all primary DB transactions so as to flush any REPEATABLE-READ or SSI snapshots.
Wikimedia\Rdbms\ILoadBalancer\getLaggedReplicaMode
getLaggedReplicaMode( $domain=false)
Wikimedia\Rdbms\ILoadBalancer\DOMAIN_ANY
const DOMAIN_ANY
Domain specifier when no specific database needs to be selected.
Definition: ILoadBalancer.php:99
Wikimedia\Rdbms\ILoadBalancer\flushReplicaSnapshots
flushReplicaSnapshots( $fname=__METHOD__, $owner=null)
Commit all replica DB transactions so as to flush any REPEATABLE-READ or SSI snapshots.
Wikimedia\Rdbms\ILoadBalancer\hasOrMadeRecentMasterChanges
hasOrMadeRecentMasterChanges( $age=null)
Check if this load balancer object had any recent or still pending writes issued against it by this P...
Wikimedia\Rdbms\ILoadBalancer\waitForMasterPos
waitForMasterPos(IDatabase $conn, $pos=false, $timeout=10)
Wait for a replica DB to reach a specified primary position.
Wikimedia\Rdbms\ILoadBalancer\CONN_INTENT_WRITABLE
const CONN_INTENT_WRITABLE
Caller is requesting the primary DB server for possibly writes.
Definition: ILoadBalancer.php:108
Wikimedia\Rdbms\ILoadBalancer\finalizeMasterChanges
finalizeMasterChanges( $fname=__METHOD__, $owner=null)
Run pre-commit callbacks and defer execution of post-commit callbacks.
Wikimedia\Rdbms\ILoadBalancer\forEachOpenReplicaConnection
forEachOpenReplicaConnection( $callback, array $params=[])
Call a function with each open replica DB connection object.
Wikimedia\Rdbms\ILoadBalancer\laggedReplicaUsed
laggedReplicaUsed()
Checks whether the database for generic connections this request was both:
Wikimedia\Rdbms\ILoadBalancer\getReaderIndex
getReaderIndex( $group=false, $domain=false)
Get the specific server index of the reader connection for a given group.
Wikimedia\Rdbms\ILoadBalancer\CONN_TRX_AUTOCOMMIT
const CONN_TRX_AUTOCOMMIT
DB handle should have DBO_TRX disabled and the caller will leave it as such.
Definition: ILoadBalancer.php:104
Wikimedia\Rdbms\ILoadBalancer\getReplicaResumePos
getReplicaResumePos()
Get the highest DB replication position for chronology control purposes.
Wikimedia\Rdbms\ILoadBalancer\getServerConnection
getServerConnection( $i, $domain, $flags=0)
Get a live handle for a specific server index.
Wikimedia\Rdbms\ILoadBalancer\rollbackMasterChanges
rollbackMasterChanges( $fname=__METHOD__, $owner=null)
Issue ROLLBACK only on primary, only if queries were done on connection.
Wikimedia\Rdbms\ILoadBalancer\CONN_REFRESH_READ_ONLY
const CONN_REFRESH_READ_ONLY
Bypass and update any server-side read-only mode state cache.
Definition: ILoadBalancer.php:110
Wikimedia\Rdbms\ILoadBalancer\__construct
__construct(array $params)
Construct a manager of IDatabase connection objects.
Wikimedia\Rdbms\ILoadBalancer\hasStreamingReplicaServers
hasStreamingReplicaServers()
Whether any replica servers use streaming replication from the primary server.
Wikimedia\Rdbms\ILoadBalancer\getAnyOpenConnection
getAnyOpenConnection( $i, $flags=0)
Get an existing live handle to the given server index (on any domain)
Wikimedia\Rdbms\ILoadBalancer\hasMasterChanges
hasMasterChanges()
Whether there are pending changes or callbacks in a transaction by this thread.
Wikimedia\Rdbms\ILoadBalancer\waitForOne
waitForOne( $pos, $timeout=null)
Set the primary wait position and wait for a generic replica DB to catch up to it.
Wikimedia\Rdbms\ILoadBalancer\closeConnection
closeConnection(IDatabase $conn)
Close a connection.
Wikimedia\Rdbms\ILoadBalancer\getServerType
getServerType( $i)
Get the RDBMS type of the server with the specified index (e.g.
Wikimedia\Rdbms\ILoadBalancer\lastMasterChangeTimestamp
lastMasterChangeTimestamp()
Get the timestamp of the latest write query done by this thread.
Wikimedia\Rdbms\ILoadBalancer\STAGE_POSTROLLBACK_CALLBACKS
const STAGE_POSTROLLBACK_CALLBACKS
Manager of ILoadBalancer instances is running post-rollback callbacks.
Definition: ILoadBalancer.php:115
Wikimedia\Rdbms\ILoadBalancer\DB_REPLICA
const DB_REPLICA
Request a replica DB connection.
Definition: ILoadBalancer.php:83
Wikimedia\Rdbms\ILoadBalancer\closeAll
closeAll( $fname=__METHOD__, $owner=null)
Close all open connections.
Wikimedia\Rdbms\ILoadBalancer
Database cluster connection, tracking, load balancing, and transaction manager interface.
Definition: ILoadBalancer.php:81
Wikimedia\Rdbms\ILoadBalancer\getLagTimes
getLagTimes( $domain=false)
Get an estimate of replication lag (in seconds) for each server.
Wikimedia\Rdbms\ILoadBalancer\commitAll
commitAll( $fname=__METHOD__, $owner=null)
Commit transactions on all open connections.
Wikimedia\Rdbms\ILoadBalancer\commitMasterChanges
commitMasterChanges( $fname=__METHOD__, $owner=null)
Issue COMMIT on all open primary connections to flush changes and view snapshots.