MediaWiki  master
ILoadBalancer.php
Go to the documentation of this file.
1 <?php
20 namespace Wikimedia\Rdbms;
21 
113 interface ILoadBalancer {
117  public const DB_REPLICA = -1;
123  public const DB_PRIMARY = -2;
124 
125  // phpcs:disable MediaWiki.Usage.DeprecatedConstantUsage.DB_MASTER
130  public const DB_MASTER = self::DB_PRIMARY;
131  // phpcs:enable MediaWiki.Usage.DeprecatedConstantUsage.DB_MASTER
132 
134  public const DOMAIN_ANY = '';
136  public const GROUP_GENERIC = '';
137 
139  public const CONN_UNTRACKED_GAUGE = 1;
141  public const CONN_TRX_AUTOCOMMIT = 2;
143  public const CONN_SILENCE_ERRORS = 4;
145  public const CONN_INTENT_WRITABLE = 8;
146 
165  public function getClusterName(): string;
166 
174  public function getLocalDomainID(): string;
175 
181  public function resolveDomainID( $domain ): string;
182 
189  public function redefineLocalDomain( $domain );
190 
201  public function setTempTablesOnlyMode( $value, $domain );
202 
216  public function getReaderIndex( $group = false );
217 
231  public function waitFor( DBPrimaryPos $pos );
232 
243  public function waitForAll( DBPrimaryPos $pos, $timeout = null );
244 
259  public function getAnyOpenConnection( $i, $flags = 0 );
260 
306  public function getConnection( $i, $groups = [], $domain = false, $flags = 0 );
307 
328  public function getServerConnection( $i, $domain, $flags = 0 );
329 
334  public function reuseConnection( IDatabase $conn );
335 
344  public function getConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): IDatabase;
345 
354  public function getConnectionInternal( $i, $groups = [], $domain = false, $flags = 0 ): IDatabase;
355 
374  public function getMaintenanceConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): DBConnRef;
375 
387  public function getWriterIndex();
388 
394  public function getServerCount();
395 
408  public function hasReplicaServers();
409 
426  public function hasStreamingReplicaServers();
427 
434  public function getServerName( $i ): string;
435 
443  public function getServerInfo( $i );
444 
452  public function getServerType( $i );
453 
461  public function getServerAttributes( $i );
462 
470  public function getPrimaryPos();
471 
488  public function getReplicaResumePos();
489 
498  public function closeConnection( IDatabase $conn );
499 
504  public function hasPrimaryConnection();
505 
511  public function hasPrimaryChanges();
512 
519  public function explicitTrxActive();
520 
526  public function lastPrimaryChangeTimestamp();
527 
536  public function hasOrMadeRecentPrimaryChanges( $age = null );
537 
544  public function laggedReplicaUsed();
545 
551  public function getReadOnlyReason( $domain = false );
552 
556  public function pingAll();
557 
567  public function getMaxLag();
568 
578  public function getLagTimes();
579 
591  public function waitForPrimaryPos( IDatabase $conn );
592 
600  public function setTransactionListener( $name, callable $callback = null );
601 
614  public function setTableAliases( array $aliases );
615 
628  public function setIndexAliases( array $aliases );
629 
638  public function setDomainAliases( array $aliases );
639 }
Helper class used for automatically marking an IDatabase connection as reusable (once it no longer ma...
Definition: DBConnRef.php:29
An object representing a primary or replica DB position in a replicated setup.
Basic database interface for live and lazy-loaded relation database handles.
Definition: IDatabase.php:36
This class is a delegate to ILBFactory for a given database cluster.
getClusterName()
Get the name of the overall cluster of database servers managing the dataset.
reuseConnection(IDatabase $conn)
getMaxLag()
Get the name and lag time of the most-lagged replica server.
const CONN_UNTRACKED_GAUGE
Yield an untracked, low-timeout, autocommit-mode handle (to gauge server health)
getConnection( $i, $groups=[], $domain=false, $flags=0)
Get a lazy-connecting database 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...
getLagTimes()
Get an estimate of replication lag (in seconds) for each server.
getServerType( $i)
Get the RDBMS type of the server with the specified index (e.g.
const GROUP_GENERIC
The generic query group.
getServerConnection( $i, $domain, $flags=0)
Get a DB 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 ...
getReaderIndex( $group=false)
Get the specific server index of the reader connection for a given group.
waitForAll(DBPrimaryPos $pos, $timeout=null)
Set the primary wait position and wait for ALL replica DBs to catch up to it.
const DOMAIN_ANY
Domain specifier when no specific database needs to be selected.
const DB_REPLICA
Request a replica DB connection.
const CONN_TRX_AUTOCOMMIT
Yield a tracked autocommit-mode handle (reuse existing ones)
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.
const CONN_SILENCE_ERRORS
Yield null on connection failure instead of throwing an exception.
setTempTablesOnlyMode( $value, $domain)
Indicate whether the tables on this domain are only temporary tables for testing.
getWriterIndex()
Get the specific server index of the "writer server".
setDomainAliases(array $aliases)
Convert certain database domains to alternative ones.
waitFor(DBPrimaryPos $pos)
Set the primary position to reach before the next generic group DB query.
laggedReplicaUsed()
Whether a highly "lagged" replica database connection was queried.
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.
waitForPrimaryPos(IDatabase $conn)
Wait for a replica DB to reach a specified primary position.
getConnectionRef( $i, $groups=[], $domain=false, $flags=0)
hasPrimaryChanges()
Whether there are pending changes or callbacks in a transaction by this thread.
getPrimaryPos()
Get the current primary replication position.
getMaintenanceConnectionRef( $i, $groups=[], $domain=false, $flags=0)
Get a DB 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.
explicitTrxActive()
Determine whether an explicit transaction is active on any open primary connection.
lastPrimaryChangeTimestamp()
Get the timestamp of the latest write query done by this thread.
const DB_MASTER
Request a primary, write-enabled DB connection.
const DB_PRIMARY
Request a primary, write-enabled DB connection.
closeConnection(IDatabase $conn)
Close a connection.
getConnectionInternal( $i, $groups=[], $domain=false, $flags=0)
hasReplicaServers()
Whether there are any replica servers configured.
hasStreamingReplicaServers()
Whether any replica servers use streaming replication from the primary server.
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.
getAnyOpenConnection( $i, $flags=0)
Get an existing DB handle to the given server index (on any domain)