MediaWiki  master
ILoadBalancer.php
Go to the documentation of this file.
1 <?php
20 namespace Wikimedia\Rdbms;
21 
113 interface ILoadBalancer {
115  public const DB_REPLICA = -1;
120  public const DB_PRIMARY = -2;
121 
122  // phpcs:disable MediaWiki.Usage.DeprecatedConstantUsage.DB_MASTER
127  public const DB_MASTER = self::DB_PRIMARY;
128  // phpcs:enable MediaWiki.Usage.DeprecatedConstantUsage.DB_MASTER
129 
131  public const DOMAIN_ANY = '';
133  public const GROUP_GENERIC = '';
134 
136  public const CONN_UNTRACKED_GAUGE = 1;
138  public const CONN_TRX_AUTOCOMMIT = 2;
140  public const CONN_SILENCE_ERRORS = 4;
142  public const CONN_INTENT_WRITABLE = 8;
144  public const CONN_REFRESH_READ_ONLY = 16;
145 
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 
215  public function getReaderIndex( $group = false );
216 
230  public function waitFor( $pos );
231 
242  public function waitForAll( $pos, $timeout = null );
243 
258  public function getAnyOpenConnection( $i, $flags = 0 );
259 
305  public function getConnection( $i, $groups = [], $domain = false, $flags = 0 );
306 
327  public function getServerConnection( $i, $domain, $flags = 0 );
328 
333  public function reuseConnection( IDatabase $conn );
334 
343  public function getConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): IDatabase;
344 
353  public function getConnectionInternal( $i, $groups = [], $domain = false, $flags = 0 ): IDatabase;
354 
373  public function getMaintenanceConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): DBConnRef;
374 
386  public function getWriterIndex();
387 
393  public function getServerCount();
394 
407  public function hasReplicaServers();
408 
425  public function hasStreamingReplicaServers();
426 
433  public function getServerName( $i ): string;
434 
442  public function getServerInfo( $i );
443 
451  public function getServerType( $i );
452 
460  public function getServerAttributes( $i );
461 
469  public function getPrimaryPos();
470 
486  public function getReplicaResumePos();
487 
496  public function closeConnection( IDatabase $conn );
497 
502  public function hasPrimaryConnection();
503 
509  public function hasPrimaryChanges();
510 
517  public function explicitTrxActive();
518 
524  public function lastPrimaryChangeTimestamp();
525 
534  public function hasOrMadeRecentPrimaryChanges( $age = null );
535 
542  public function laggedReplicaUsed();
543 
549  public function getReadOnlyReason( $domain = false );
550 
554  public function pingAll();
555 
565  public function getMaxLag();
566 
576  public function getLagTimes();
577 
589  public function waitForPrimaryPos( IDatabase $conn );
590 
598  public function setTransactionListener( $name, callable $callback = null );
599 
612  public function setTableAliases( array $aliases );
613 
626  public function setIndexAliases( array $aliases );
627 
636  public function setDomainAliases( array $aliases );
637 }
Helper class used for automatically marking an IDatabase connection as reusable (once it no longer ma...
Definition: DBConnRef.php:29
Basic database interface for live and lazy-loaded relation database handles.
Definition: IDatabase.php:40
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.
waitFor( $pos)
Set the primary position to reach before the next generic group DB query.
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.
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.
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.
const CONN_REFRESH_READ_ONLY
Bypass and update any server-side read-only mode state cache.
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.
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 DB handle to the given server index (on any domain)