MediaWiki  master
ILoadBalancer.php
Go to the documentation of this file.
1 <?php
23 namespace Wikimedia\Rdbms;
24 
25 use InvalidArgumentException;
26 
79 interface ILoadBalancer {
81  public const DB_REPLICA = -1;
86  public const DB_PRIMARY = -2;
87 
88  // phpcs:disable MediaWiki.Usage.DeprecatedConstantUsage.DB_MASTER
93  public const DB_MASTER = self::DB_PRIMARY;
94  // phpcs:enable MediaWiki.Usage.DeprecatedConstantUsage.DB_MASTER
95 
97  public const DOMAIN_ANY = '';
99  public const GROUP_GENERIC = '';
100 
102  public const CONN_TRX_AUTOCOMMIT = 1;
104  public const CONN_SILENCE_ERRORS = 2;
106  public const CONN_INTENT_WRITABLE = 4;
108  public const CONN_REFRESH_READ_ONLY = 8;
109 
124  public function getClusterName(): string;
125 
133  public function getLocalDomainID(): string;
134 
140  public function resolveDomainID( $domain ): string;
141 
148  public function redefineLocalDomain( $domain );
149 
160  public function setTempTablesOnlyMode( $value, $domain );
161 
176  public function getReaderIndex( $group = false, $domain = false );
177 
191  public function waitFor( $pos );
192 
203  public function waitForAll( $pos, $timeout = null );
204 
218  public function getAnyOpenConnection( $i, $flags = 0 );
219 
276  public function getConnection( $i, $groups = [], $domain = false, $flags = 0 );
277 
295  public function getServerConnection( $i, $domain, $flags = 0 );
296 
301  public function reuseConnection( IDatabase $conn );
302 
307  public function reuseConnectionInternal( IDatabase $conn );
308 
317  public function getConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): IDatabase;
318 
327  public function getConnectionInternal( $i, $groups = [], $domain = false, $flags = 0 ): IDatabase;
328 
350  public function getLazyConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): IDatabase;
351 
373  public function getMaintenanceConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): DBConnRef;
374 
380  public function getWriterIndex();
381 
387  public function getServerCount();
388 
398  public function hasReplicaServers();
399 
419  public function hasStreamingReplicaServers();
420 
427  public function getServerName( $i ): string;
428 
436  public function getServerInfo( $i );
437 
445  public function getServerType( $i );
446 
454  public function getServerAttributes( $i );
455 
463  public function getPrimaryPos();
464 
480  public function getReplicaResumePos();
481 
490  public function closeConnection( IDatabase $conn );
491 
496  public function hasPrimaryConnection();
497 
503  public function hasPrimaryChanges();
504 
511  public function explicitTrxActive();
512 
518  public function lastPrimaryChangeTimestamp();
519 
528  public function hasOrMadeRecentPrimaryChanges( $age = null );
529 
535  public function getLaggedReplicaMode( $domain = false );
536 
545  public function laggedReplicaUsed();
546 
552  public function getReadOnlyReason( $domain = false );
553 
557  public function pingAll();
558 
569  public function getMaxLag( $domain = false );
570 
581  public function getLagTimes( $domain = false );
582 
596  public function waitForPrimaryPos( IDatabase $conn, $pos = false, $timeout = 10 );
597 
605  public function setTransactionListener( $name, callable $callback = null );
606 
619  public function setTableAliases( array $aliases );
620 
633  public function setIndexAliases( array $aliases );
634 
643  public function setDomainAliases( array $aliases );
644 }
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:39
Database cluster connection, tracking, load balancing, and transaction manager interface.
getClusterName()
Get the logical name of the database cluster.
reuseConnection(IDatabase $conn)
getConnection( $i, $groups=[], $domain=false, $flags=0)
Get a lazy 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.
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 ...
reuseConnectionInternal(IDatabase $conn)
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.
getLaggedReplicaMode( $domain=false)
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
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.
const CONN_SILENCE_ERRORS
Return 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 primary server.
setDomainAliases(array $aliases)
Convert certain database domains to alternative ones.
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)
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 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.
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.
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.
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)