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(): string;
164 
172  public function getLocalDomainID(): string;
173 
179  public function resolveDomainID( $domain ): string;
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 
353  public function getServerConnection( $i, $domain, $flags = 0 );
354 
368  public function reuseConnection( IDatabase $conn );
369 
386  public function getConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): IDatabase;
387 
409  public function getLazyConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): DBConnRef;
410 
432  public function getMaintenanceConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): MaintainableDBConnRef;
433 
439  public function getWriterIndex();
440 
446  public function getServerCount();
447 
457  public function hasReplicaServers();
458 
478  public function hasStreamingReplicaServers();
479 
486  public function getServerName( $i ): string;
487 
495  public function getServerInfo( $i );
496 
504  public function getServerType( $i );
505 
513  public function getServerAttributes( $i );
514 
522  public function getPrimaryPos();
523 
529  public function getMasterPos();
530 
546  public function getReplicaResumePos();
547 
556  public function disable( $fname = __METHOD__, $owner = null );
557 
564  public function closeAll( $fname = __METHOD__, $owner = null );
565 
574  public function closeConnection( IDatabase $conn );
575 
582  public function commitAll( $fname = __METHOD__, $owner = null );
583 
594  public function finalizePrimaryChanges( $fname = __METHOD__, $owner = null );
595 
602  public function finalizeMasterChanges( $fname = __METHOD__, $owner = null );
603 
616  public function approvePrimaryChanges( array $options, $fname = __METHOD__, $owner = null );
617 
626  public function approveMasterChanges( array $options, $fname = __METHOD__, $owner = null );
627 
642  public function beginPrimaryChanges( $fname = __METHOD__, $owner = null );
643 
650  public function beginMasterChanges( $fname = __METHOD__, $owner = null );
651 
659  public function commitPrimaryChanges( $fname = __METHOD__, $owner = null );
660 
667  public function commitMasterChanges( $fname = __METHOD__, $owner = null );
668 
677  public function runPrimaryTransactionIdleCallbacks( $fname = __METHOD__, $owner = null );
678 
685  public function runMasterTransactionIdleCallbacks( $fname = __METHOD__, $owner = null );
686 
695  public function runPrimaryTransactionListenerCallbacks( $fname = __METHOD__, $owner = null );
696 
703  public function runMasterTransactionListenerCallbacks( $fname = __METHOD__, $owner = null );
704 
712  public function rollbackPrimaryChanges( $fname = __METHOD__, $owner = null );
713 
720  public function rollbackMasterChanges( $fname = __METHOD__, $owner = null );
721 
728  public function flushReplicaSnapshots( $fname = __METHOD__, $owner = null );
729 
739  public function flushPrimarySnapshots( $fname = __METHOD__, $owner = null );
740 
746  public function flushMasterSnapshots( $fname = __METHOD__, $owner = null );
747 
752  public function hasPrimaryConnection();
753 
758  public function hasMasterConnection();
759 
765  public function hasPrimaryChanges();
766 
771  public function hasMasterChanges();
772 
778  public function lastPrimaryChangeTimestamp();
779 
784  public function lastMasterChangeTimestamp();
785 
794  public function hasOrMadeRecentPrimaryChanges( $age = null );
795 
801  public function hasOrMadeRecentMasterChanges( $age = null );
802 
809  public function pendingPrimaryChangeCallers();
810 
815  public function pendingMasterChangeCallers();
816 
822  public function getLaggedReplicaMode( $domain = false );
823 
832  public function laggedReplicaUsed();
833 
839  public function getReadOnlyReason( $domain = false );
840 
846  public function allowLagged( $mode = null );
847 
851  public function pingAll();
852 
858  public function forEachOpenConnection( $callback, array $params = [] );
859 
866  public function forEachOpenPrimaryConnection( $callback, array $params = [] );
867 
873  public function forEachOpenMasterConnection( $callback, array $params = [] );
874 
880  public function forEachOpenReplicaConnection( $callback, array $params = [] );
881 
892  public function getMaxLag( $domain = false );
893 
904  public function getLagTimes( $domain = false );
905 
919  public function waitForPrimaryPos( IDatabase $conn, $pos = false, $timeout = 10 );
920 
929  public function waitForMasterPos( IDatabase $conn, $pos = false, $timeout = 10 );
930 
938  public function setTransactionListener( $name, callable $callback = null );
939 
946  public function setLocalDomainPrefix( $prefix );
947 
960  public function setTableAliases( array $aliases );
961 
974  public function setIndexAliases( array $aliases );
975 
984  public function setDomainAliases( array $aliases );
985 }
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:29
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)