MediaWiki REL1_37
ILoadBalancer.php
Go to the documentation of this file.
1<?php
23namespace Wikimedia\Rdbms;
24
25use Exception;
26use InvalidArgumentException;
27use LogicException;
28
81interface ILoadBalancer {
83 public const DB_REPLICA = -1;
88 public const DB_PRIMARY = -2;
89
90 // phpcs:disable MediaWiki.Usage.DeprecatedConstantUsage.DB_MASTER
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
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 );
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 );
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
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}
Helper class used for automatically marking an IDatabase connection as reusable (once it no longer ma...
Definition DBConnRef.php:29
Helper class to handle automatically marking connections as reusable (via RAII pattern) as well handl...
Basic database interface for live and lazy-loaded relation database handles.
Definition IDatabase.php:38
Database cluster connection, tracking, load balancing, and transaction manager interface.
runMasterTransactionIdleCallbacks( $fname=__METHOD__, $owner=null)
getClusterName()
Get the logical name of the database cluster.
flushMasterSnapshots( $fname=__METHOD__, $owner=null)
reuseConnection(IDatabase $conn)
Mark a live handle as being available for reuse under a different database domain.
forEachOpenConnection( $callback, array $params=[])
Call a function with each open connection object.
waitForMasterPos(IDatabase $conn, $pos=false, $timeout=10)
getConnection( $i, $groups=[], $domain=false, $flags=0)
Get a live handle for a specific or virtual (DB_PRIMARY/DB_REPLICA) server index.
const CONN_INTENT_WRITABLE
Caller is requesting the primary DB server for possibly writes.
hasOrMadeRecentPrimaryChanges( $age=null)
Check if this load balancer object had any recent or still pending writes issued against it by this P...
getServerType( $i)
Get the RDBMS type of the server with the specified index (e.g.
const GROUP_GENERIC
The generic query group.
getMaxLag( $domain=false)
Get the name and lag time of the most-lagged replica server.
waitFor( $pos)
Set the primary position to reach before the next generic group DB handle query.
rollbackMasterChanges( $fname=__METHOD__, $owner=null)
beginMasterChanges( $fname=__METHOD__, $owner=null)
getServerConnection( $i, $domain, $flags=0)
Get a live handle for a specific server index.
getReadOnlyReason( $domain=false)
getReplicaResumePos()
Get the highest DB replication position for chronology control purposes.
setTransactionListener( $name, callable $callback=null)
Set a callback via IDatabase::setTransactionListener() on all current and future primary connections ...
commitMasterChanges( $fname=__METHOD__, $owner=null)
disable( $fname=__METHOD__, $owner=null)
Close all connections and disable this load balancer.
getReaderIndex( $group=false, $domain=false)
Get the specific server index of the reader connection for a given group.
waitForPrimaryPos(IDatabase $conn, $pos=false, $timeout=10)
Wait for a replica DB to reach a specified primary position.
const STAGE_POSTROLLBACK_CALLBACKS
Manager of ILoadBalancer instances is running post-rollback callbacks.
hasOrMadeRecentMasterChanges( $age=null)
forEachOpenMasterConnection( $callback, array $params=[])
forEachOpenPrimaryConnection( $callback, array $params=[])
Call a function with each open connection object to a primary.
getLaggedReplicaMode( $domain=false)
const DOMAIN_ANY
Domain specifier when no specific database needs to be selected.
closeAll( $fname=__METHOD__, $owner=null)
Close all open connections.
const DB_REPLICA
Request a replica DB connection.
const CONN_TRX_AUTOCOMMIT
DB handle should have DBO_TRX disabled and the caller will leave it as such.
setTableAliases(array $aliases)
Make certain table names use their own database, schema, and table prefix when passed into SQL querie...
redefineLocalDomain( $domain)
Close all connection and redefine the local domain for testing or schema creation.
__construct(array $params)
Construct a manager of IDatabase connection objects.
const CONN_SILENCE_ERRORS
Return null on connection failure instead of throwing an exception.
commitAll( $fname=__METHOD__, $owner=null)
Commit transactions on all open connections.
forEachOpenReplicaConnection( $callback, array $params=[])
Call a function with each open replica DB connection object.
setTempTablesOnlyMode( $value, $domain)
Indicate whether the tables on this domain are only temporary tables for testing.
commitPrimaryChanges( $fname=__METHOD__, $owner=null)
Issue COMMIT on all open primary connections to flush changes and view snapshots.
getWriterIndex()
Get the specific server index of the primary server.
approveMasterChanges(array $options, $fname=__METHOD__, $owner=null)
setDomainAliases(array $aliases)
Convert certain database domains to alternative ones.
runMasterTransactionListenerCallbacks( $fname=__METHOD__, $owner=null)
laggedReplicaUsed()
Checks whether the database for generic connections this request was both:
getServerCount()
Get the number of servers defined in configuration.
getLocalDomainID()
Get the local (and default) database domain ID of connection handles.
getServerInfo( $i)
Return the server configuration map for the server with the specified index.
const CONN_REFRESH_READ_ONLY
Bypass and update any server-side read-only mode state cache.
getConnectionRef( $i, $groups=[], $domain=false, $flags=0)
Get a live database handle reference for a server index.
hasPrimaryChanges()
Whether there are pending changes or callbacks in a transaction by this thread.
approvePrimaryChanges(array $options, $fname=__METHOD__, $owner=null)
Perform all pre-commit checks for things like replication safety.
getPrimaryPos()
Get the current primary replication position.
getMaintenanceConnectionRef( $i, $groups=[], $domain=false, $flags=0)
Get a live database handle, suitable for migrations and schema changes, for a server index.
setIndexAliases(array $aliases)
Convert certain index names to alternative names before querying the DB.
getLazyConnectionRef( $i, $groups=[], $domain=false, $flags=0)
Get a lazy-connecting database handle reference for a server index.
finalizePrimaryChanges( $fname=__METHOD__, $owner=null)
Run pre-commit callbacks and defer execution of post-commit callbacks.
lastPrimaryChangeTimestamp()
Get the timestamp of the latest write query done by this thread.
const DB_MASTER
Request a primary, write-enabled DB connection.
runPrimaryTransactionListenerCallbacks( $fname=__METHOD__, $owner=null)
Run all recurring post-COMMIT/ROLLBACK listener callbacks.
const DB_PRIMARY
Request a primary, write-enabled DB connection.
setLocalDomainPrefix( $prefix)
Set a new table prefix for the existing local domain ID for testing.
pendingPrimaryChangeCallers()
Get the list of callers that have pending primary changes.
closeConnection(IDatabase $conn)
Close a connection.
finalizeMasterChanges( $fname=__METHOD__, $owner=null)
flushPrimarySnapshots( $fname=__METHOD__, $owner=null)
Commit all primary DB transactions so as to flush any REPEATABLE-READ or SSI snapshots.
beginPrimaryChanges( $fname=__METHOD__, $owner=null)
Flush any primary transaction snapshots and set DBO_TRX (if DBO_DEFAULT is set)
allowLagged( $mode=null)
Disables/enables lag checks.
runPrimaryTransactionIdleCallbacks( $fname=__METHOD__, $owner=null)
Consume and run all pending post-COMMIT/ROLLBACK callbacks and commit dangling transactions.
const STAGE_POSTCOMMIT_CALLBACKS
Manager of ILoadBalancer instances is running post-commit callbacks.
rollbackPrimaryChanges( $fname=__METHOD__, $owner=null)
Issue ROLLBACK only on primary, only if queries were done on connection.
hasReplicaServers()
Whether there are any replica servers configured.
getLagTimes( $domain=false)
Get an estimate of replication lag (in seconds) for each server.
hasStreamingReplicaServers()
Whether any replica servers use streaming replication from the primary server.
waitForOne( $pos, $timeout=null)
Set the primary wait position and wait for a generic replica DB to catch up to it.
getServerName( $i)
Get the readable name of the server with the specified index.
getServerAttributes( $i)
Get basic attributes of the server with the specified index without connecting.
waitForAll( $pos, $timeout=null)
Set the primary wait position and wait for ALL replica DBs to catch up to it.
getAnyOpenConnection( $i, $flags=0)
Get an existing live handle to the given server index (on any domain)
flushReplicaSnapshots( $fname=__METHOD__, $owner=null)
Commit all replica DB transactions so as to flush any REPEATABLE-READ or SSI snapshots.