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 
148  public function __construct( array $params );
149 
164  public function getClusterName(): string;
165 
173  public function getLocalDomainID(): string;
174 
180  public function resolveDomainID( $domain ): string;
181 
188  public function redefineLocalDomain( $domain );
189 
200  public function setTempTablesOnlyMode( $value, $domain );
201 
216  public function getReaderIndex( $group = false, $domain = false );
217 
231  public function waitFor( $pos );
232 
245  public function waitForOne( $pos, $timeout = null );
246 
257  public function waitForAll( $pos, $timeout = null );
258 
272  public function getAnyOpenConnection( $i, $flags = 0 );
273 
336  public function getConnection( $i, $groups = [], $domain = false, $flags = 0 );
337 
355  public function getServerConnection( $i, $domain, $flags = 0 );
356 
370  public function reuseConnection( IDatabase $conn );
371 
388  public function getConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): IDatabase;
389 
411  public function getLazyConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): DBConnRef;
412 
434  public function getMaintenanceConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): MaintainableDBConnRef;
435 
441  public function getWriterIndex();
442 
448  public function getServerCount();
449 
459  public function hasReplicaServers();
460 
480  public function hasStreamingReplicaServers();
481 
488  public function getServerName( $i ): string;
489 
497  public function getServerInfo( $i );
498 
506  public function getServerType( $i );
507 
515  public function getServerAttributes( $i );
516 
524  public function getPrimaryPos();
525 
531  public function getMasterPos();
532 
548  public function getReplicaResumePos();
549 
558  public function disable( $fname = __METHOD__, $owner = null );
559 
566  public function closeAll( $fname = __METHOD__, $owner = null );
567 
576  public function closeConnection( IDatabase $conn );
577 
584  public function commitAll( $fname = __METHOD__, $owner = null );
585 
596  public function finalizePrimaryChanges( $fname = __METHOD__, $owner = null );
597 
604  public function finalizeMasterChanges( $fname = __METHOD__, $owner = null );
605 
618  public function approvePrimaryChanges( array $options, $fname = __METHOD__, $owner = null );
619 
628  public function approveMasterChanges( array $options, $fname = __METHOD__, $owner = null );
629 
644  public function beginPrimaryChanges( $fname = __METHOD__, $owner = null );
645 
652  public function beginMasterChanges( $fname = __METHOD__, $owner = null );
653 
661  public function commitPrimaryChanges( $fname = __METHOD__, $owner = null );
662 
669  public function commitMasterChanges( $fname = __METHOD__, $owner = null );
670 
679  public function runPrimaryTransactionIdleCallbacks( $fname = __METHOD__, $owner = null );
680 
687  public function runMasterTransactionIdleCallbacks( $fname = __METHOD__, $owner = null );
688 
697  public function runPrimaryTransactionListenerCallbacks( $fname = __METHOD__, $owner = null );
698 
705  public function runMasterTransactionListenerCallbacks( $fname = __METHOD__, $owner = null );
706 
714  public function rollbackPrimaryChanges( $fname = __METHOD__, $owner = null );
715 
722  public function rollbackMasterChanges( $fname = __METHOD__, $owner = null );
723 
730  public function flushReplicaSnapshots( $fname = __METHOD__, $owner = null );
731 
741  public function flushPrimarySnapshots( $fname = __METHOD__, $owner = null );
742 
748  public function flushMasterSnapshots( $fname = __METHOD__, $owner = null );
749 
754  public function hasPrimaryConnection();
755 
760  public function hasMasterConnection();
761 
767  public function hasPrimaryChanges();
768 
773  public function hasMasterChanges();
774 
780  public function lastPrimaryChangeTimestamp();
781 
786  public function lastMasterChangeTimestamp();
787 
796  public function hasOrMadeRecentPrimaryChanges( $age = null );
797 
803  public function hasOrMadeRecentMasterChanges( $age = null );
804 
811  public function pendingPrimaryChangeCallers();
812 
817  public function pendingMasterChangeCallers();
818 
824  public function getLaggedReplicaMode( $domain = false );
825 
834  public function laggedReplicaUsed();
835 
841  public function getReadOnlyReason( $domain = false );
842 
848  public function allowLagged( $mode = null );
849 
853  public function pingAll();
854 
860  public function forEachOpenConnection( $callback, array $params = [] );
861 
868  public function forEachOpenPrimaryConnection( $callback, array $params = [] );
869 
875  public function forEachOpenMasterConnection( $callback, array $params = [] );
876 
882  public function forEachOpenReplicaConnection( $callback, array $params = [] );
883 
894  public function getMaxLag( $domain = false );
895 
906  public function getLagTimes( $domain = false );
907 
921  public function waitForPrimaryPos( IDatabase $conn, $pos = false, $timeout = 10 );
922 
931  public function waitForMasterPos( IDatabase $conn, $pos = false, $timeout = 10 );
932 
940  public function setTransactionListener( $name, callable $callback = null );
941 
948  public function setLocalDomainPrefix( $prefix );
949 
962  public function setTableAliases( array $aliases );
963 
976  public function setIndexAliases( array $aliases );
977 
986  public function setDomainAliases( array $aliases );
987 }
Wikimedia\Rdbms\ILoadBalancer\commitPrimaryChanges
commitPrimaryChanges( $fname=__METHOD__, $owner=null)
Issue COMMIT on all open primary connections to flush changes and view snapshots.
Wikimedia\Rdbms\ILoadBalancer\getClusterName
getClusterName()
Get the logical name of the database cluster.
Wikimedia\Rdbms\ILoadBalancer\pendingMasterChangeCallers
pendingMasterChangeCallers()
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=[])
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\lastPrimaryChangeTimestamp
lastPrimaryChangeTimestamp()
Get the timestamp of the latest write query done by this thread.
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\pendingPrimaryChangeCallers
pendingPrimaryChangeCallers()
Get the list of callers that have pending primary changes.
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\hasPrimaryChanges
hasPrimaryChanges()
Whether there are pending changes or callbacks in a transaction by this thread.
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\rollbackPrimaryChanges
rollbackPrimaryChanges( $fname=__METHOD__, $owner=null)
Issue ROLLBACK only on primary, only if queries were done on connection.
Wikimedia\Rdbms\ILoadBalancer\approvePrimaryChanges
approvePrimaryChanges(array $options, $fname=__METHOD__, $owner=null)
Perform all pre-commit checks for things like replication safety.
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\getPrimaryPos
getPrimaryPos()
Get the current primary replication position.
Wikimedia\Rdbms\ILoadBalancer\runMasterTransactionIdleCallbacks
runMasterTransactionIdleCallbacks( $fname=__METHOD__, $owner=null)
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)
Wikimedia\Rdbms\ILoadBalancer\forEachOpenPrimaryConnection
forEachOpenPrimaryConnection( $callback, array $params=[])
Call a function with each open connection object to a primary.
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\MaintainableDBConnRef
Helper class to handle automatically marking connections as reusable (via RAII pattern) as well handl...
Definition: MaintainableDBConnRef.php:13
Wikimedia\Rdbms\ILoadBalancer\hasReplicaServers
hasReplicaServers()
Whether there are any replica servers configured.
Wikimedia\Rdbms\ILoadBalancer\approveMasterChanges
approveMasterChanges(array $options, $fname=__METHOD__, $owner=null)
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\runPrimaryTransactionListenerCallbacks
runPrimaryTransactionListenerCallbacks( $fname=__METHOD__, $owner=null)
Run all recurring post-COMMIT/ROLLBACK listener callbacks.
Wikimedia\Rdbms\ILoadBalancer\beginMasterChanges
beginMasterChanges( $fname=__METHOD__, $owner=null)
Wikimedia\Rdbms\ILoadBalancer\getMaxLag
getMaxLag( $domain=false)
Get the name and lag time of the most-lagged replica server.
Wikimedia\Rdbms\ILoadBalancer\waitForPrimaryPos
waitForPrimaryPos(IDatabase $conn, $pos=false, $timeout=10)
Wait for a replica DB to reach a specified primary position.
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()
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)
Wikimedia\Rdbms\ILoadBalancer\hasOrMadeRecentPrimaryChanges
hasOrMadeRecentPrimaryChanges( $age=null)
Check if this load balancer object had any recent or still pending writes issued against it by this P...
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)
Wikimedia\Rdbms\ILoadBalancer\waitForMasterPos
waitForMasterPos(IDatabase $conn, $pos=false, $timeout=10)
Wikimedia\Rdbms\ILoadBalancer\flushPrimarySnapshots
flushPrimarySnapshots( $fname=__METHOD__, $owner=null)
Commit all primary DB transactions so as to flush any REPEATABLE-READ or SSI snapshots.
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)
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\DBConnRef
Helper class used for automatically marking an IDatabase connection as reusable (once it no longer ma...
Definition: DBConnRef.php:30
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)
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\finalizePrimaryChanges
finalizePrimaryChanges( $fname=__METHOD__, $owner=null)
Run pre-commit callbacks and defer execution of post-commit callbacks.
Wikimedia\Rdbms\ILoadBalancer\runPrimaryTransactionIdleCallbacks
runPrimaryTransactionIdleCallbacks( $fname=__METHOD__, $owner=null)
Consume and run all pending post-COMMIT/ROLLBACK callbacks and commit dangling transactions.
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()
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\beginPrimaryChanges
beginPrimaryChanges( $fname=__METHOD__, $owner=null)
Flush any primary transaction snapshots and set DBO_TRX (if DBO_DEFAULT is set)
Wikimedia\Rdbms\ILoadBalancer\getServerType
getServerType( $i)
Get the RDBMS type of the server with the specified index (e.g.
Wikimedia\Rdbms\ILoadBalancer\lastMasterChangeTimestamp
lastMasterChangeTimestamp()
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\hasPrimaryConnection
hasPrimaryConnection()
Wikimedia\Rdbms\ILoadBalancer\commitMasterChanges
commitMasterChanges( $fname=__METHOD__, $owner=null)