MediaWiki master
Public Member Functions | Protected Member Functions | List of all members
Wikimedia\Rdbms\LoadBalancerDisabled Class Reference
Database

Placeholder LoadBalancer that throws an error upon attempts to access connections. More...

Inherits Wikimedia\Rdbms\LoadBalancer.

Collaboration diagram for Wikimedia\Rdbms\LoadBalancerDisabled:
Collaboration graph
[legend]

Public Member Functions

 __construct (array $params=[])
 
 getConnection ( $i, $groups=[], string|false $domain=false, $flags=0)
 
 getConnectionInternal ( $i, $groups=[], $domain=false, $flags=0)
 
 getMaintenanceConnectionRef ( $i, $groups=[], $domain=false, $flags=0)
 
- Public Member Functions inherited from Wikimedia\Rdbms\LoadBalancer
 approvePrimaryChanges (int $maxWriteDuration, $fname=__METHOD__)
 Perform all pre-commit checks for things like replication safety.Use this only for multi-database commits
Parameters
int$maxWriteDuration: max write query duration time in seconds
string$fnameCaller name
Exceptions
DBTransactionError
Since
1.37

 
 beginPrimaryChanges ( $fname=__METHOD__)
 Flush any primary transaction snapshots and set DBO_TRX (if DBO_DEFAULT is set)The DBO_TRX setting will be reverted to the default in each of these methods:

Parameters
string$fnameCaller name
Exceptions
DBExpectedError
Since
1.37

 
 closeAll ( $fname=__METHOD__)
 Close all open connections.
Parameters
string$fnameCaller name

 
 commitPrimaryChanges ( $fname=__METHOD__)
 Issue COMMIT on all open primary connections to flush changes and view snapshots.
Parameters
string$fnameCaller name
Exceptions
DBExpectedError
Since
1.37

 
 disable ( $fname=__METHOD__)
 Close all connections and disable this load balancer.Any attempt to open a new connection will result in a DBAccessError.
Parameters
string$fnameCaller name

 
 explicitTrxActive ()
 Determine whether an explicit transaction is active on any open primary connection.
Returns
bool
Since
1.39

 
 finalizePrimaryChanges ( $fname=__METHOD__)
 Run pre-commit callbacks and defer execution of post-commit callbacks.Use this only for multi-database commits
Parameters
string$fnameCaller name
Returns
int Number of pre-commit callbacks run (since 1.32)
Since
1.37

 
 flushPrimarySessions ( $fname=__METHOD__)
 Release/destroy session-level named locks, table locks, and temp tables.Only call this function right after calling rollbackPrimaryChanges()
Parameters
string$fnameCaller name
Exceptions
DBExpectedError
Since
1.38

 
 flushPrimarySnapshots ( $fname=__METHOD__)
 Commit all primary DB transactions so as to flush any REPEATABLE-READ or SSI snapshots.An error will be thrown if a connection has pending writes or callbacks
Parameters
string$fnameCaller name
Since
1.37

 
 flushReplicaSnapshots ( $fname=__METHOD__)
 Commit all replica DB transactions so as to flush any REPEATABLE-READ or SSI snapshots.
Parameters
string$fnameCaller name

 
 getAnyOpenConnection ( $i, $flags=0)
 
 getClusterName ()
 Get the name of the overall cluster of database servers managing the dataset.
 
 getLagTimes ()
 Get an estimate of replication lag (in seconds) for each server.Results are cached for a short time in memcached/process cacheValues may be "false" if replication is too broken to estimate
Returns
float[]|int[]|false[] Map of (server index => lag) in order of server index

 
 getLocalDomainID ()
 Get the local (and default) database domain ID of connection handles.
 
 getMaxLag ()
 Get the name and lag time of the most-lagged replica server.This is useful for maintenance scripts that need to throttle their updates. May attempt to open connections to replica DBs on the default DB. If there is no lag, the maximum lag will be reported as -1.
Returns
array{0:string,1:float|int|false,2:int} (host, max lag, index of max lagged host)

 
 getPrimaryPos ()
 Get the current primary replication position.
Returns
DBPrimaryPos|false Returns false if not applicable
Exceptions
DBError
Since
1.37

 
 getReaderIndex ( $group=false)
 Get the specific server index of the reader connection for a given group.This takes into account load ratios and lag times. It should return a consistent index during the life time of the load balancer. This initially checks replica DBs for connectivity to avoid returning an unusable server. This means that connections might be attempted by calling this method (usually one at the most but possibly more). Subsequent calls with the same $group will not need to make new connection attempts since the acquired connection for each group is preserved.
Parameters
string | false | string[]$groupQuery group or false for the generic group
Returns
int|false Specific server index, or false if no DB handle can be obtained

 
 getReadOnlyReason ()
 
Note
This method may trigger a DB connection if not yet done
Returns
string|false Reason the primary is read-only or false if it is not

 
 getServerAttributes ( $i)
 Get basic attributes of the server with the specified index without connecting.
Parameters
int$iSpecific server index
Returns
array (Database::ATTRIBUTE_* constant => value) for all such constants
Since
1.31

 
 getServerConnection ( $i, $domain, $flags=0)
 Get a DB handle for a specific server index.This is an internal utility method for methods like LoadBalancer::getConnectionInternal() and DBConnRef to create the underlying connection to a concrete server.The following is the responsibility of the caller:
  • translate any virtual server indexes (DB_PRIMARY/DB_REPLICA) to a real server index.
  • enforce read-only mode on primary DB handle if there is high replication lag.
See also
ILoadBalancer::getConnection()
Access: internal
Only for use within ILoadBalancer/ILoadMonitor
Parameters
int$iSpecific server index
string$domainResolved DB domain
int$flagsBitfield of class CONN_* constants
Returns
IDatabaseForOwner|false This returns false on failure if CONN_SILENCE_ERRORS is set
Exceptions
DBErrorIf no DB handle could be obtained and CONN_SILENCE_ERRORS is not set

 
 getServerCount ()
 Get the number of servers defined in configuration.
Returns
int

 
 getServerInfo ( $i)
 Return the server configuration map for the server with the specified index.
Parameters
int$iSpecific server index
Returns
array|false Server configuration map; false if the index is invalid
Since
1.31

 
 getServerName ( $i)
 Get the readable name of the server with the specified index.
Parameters
int$iSpecific server index
Returns
string Readable server name, falling back to the hostname or IP address

 
 getServerType ( $i)
 Get the RDBMS type of the server with the specified index (e.g."mysql", "sqlite")
Parameters
int$iSpecific server index
Returns
string One of (mysql,postgres,sqlite,...) or "unknown" for bad indexes
Since
1.30

 
 hasOrMadeRecentPrimaryChanges ( $age=null)
 Check if this load balancer object had any recent or still pending writes issued against it by this PHP thread.
Parameters
float | null$ageHow many seconds ago is "recent" [defaults to mWaitTimeout]
Returns
bool
Since
1.37

 
 hasPrimaryChanges ()
 Whether there are pending changes or callbacks in a transaction by this thread.
Returns
bool
Since
1.37

 
 hasPrimaryConnection ()
 
Returns
bool Whether a primary connection is already open
Since
1.37

 
 hasReplicaServers ()
 Whether there are any replica servers configured.This scans the list of servers defined in configuration, checking for:

  • Servers that are listed after the primary and not flagged with "is static"; such servers are assumed to be typical streaming replicas
  • Servers that are listed after the primary and flagged with "is static"; such servers are assumed to have a clone of the static dataset (matching the primary)
Returns
bool
Since
1.34

 
 hasStreamingReplicaServers ()
 Whether any replica servers use streaming replication from the primary server.This scans the list of servers defined in configuration, checking for:

  • Servers that are listed after the primary and not flagged with "is static"; such servers are assumed to be typical streaming replicas
It is possible for some replicas to be configured with "is static" but not others, though it generally should either be set for all or none of the replicas.If this returns false, this means that there is generally no reason to execute replication wait logic for session consistency and lag reduction.
Returns
bool
Since
1.34

 
 laggedReplicaUsed ()
 Whether a highly "lagged" replica database connection was queried.
Note
This method will never cause a new DB connection
Returns
bool

 
 lastPrimaryChangeTimestamp ()
 Get the last time that a tracked connection was used to commit a write.
Access: internal
Should only be called from the rdbms library.
Returns
float|null UNIX timestamp, or, false (if no writes were committed)
Since
1.37

 
 pendingPrimaryChangeCallers ()
 Get the list of callers that have pending primary changes.
Returns
string[] List of method names
Since
1.37

 
 pingAll ()
 
Returns
bool

 
 reconfigure (array $params)
 Apply updated configuration.
 
 redefineLocalDomain ( $domain)
 Close all connection and redefine the local domain for testing or schema creation.
Parameters
DatabaseDomain | string$domain
Since
1.33

 
 resolveDomainID (DatabaseDomain|string|false $domain)
 
Parameters
DatabaseDomain | string | false$domainDatabase domain
Returns
string Value of $domain if it is foreign or the local domain otherwise
Since
1.32

 
 rollbackPrimaryChanges ( $fname=__METHOD__)
 Issue ROLLBACK only on primary, only if queries were done on connection.
Parameters
string$fnameCaller name
Exceptions
DBExpectedError
Since
1.37

 
 runPrimaryTransactionIdleCallbacks ( $fname=__METHOD__)
 Consume and run all pending post-COMMIT/ROLLBACK callbacks and commit dangling transactions.
Parameters
string$fnameCaller name
Returns
Exception|null The first exception or null if there were none
Since
1.37

 
 runPrimaryTransactionListenerCallbacks ( $fname=__METHOD__)
 Run all recurring post-COMMIT/ROLLBACK listener callbacks.
Parameters
string$fnameCaller name
Returns
Exception|null The first exception or null if there were none
Since
1.37

 
 setDefaultGroupName (string $defaultGroup)
 Set the default group name for all load balancers.
 
 setDomainAliases (array $aliases)
 Convert certain database domains to alternative ones.
 
 setLocalDomainPrefix ( $prefix)
 Set a new table prefix for the existing local domain ID for testing.
Parameters
string$prefix
Since
1.33

 
 setMockTime (&$time)
 
 setTableAliases (array $aliases)
 Make certain table names use their own database, schema, and table prefix when passed into SQL queries pre-escaped and without a qualified database name.
 
 setTempTablesOnlyMode ( $value, $domain)
 Indicate whether the tables on this domain are only temporary tables for testing.In "temporary tables mode", the CONN_TRX_AUTOCOMMIT flag is ignored
Parameters
bool$value
string$domain
Returns
bool Whether "temporary tables mode" was active
Since
1.34

 
 setTransactionListener ( $name, ?callable $callback=null)
 Set a callback via IDatabase::setTransactionListener() on all current and future primary connections of this load balancer.
Parameters
string$nameCallback name
callable | null$callback
Deprecated
Since 1.44

 
 waitForAll (DBPrimaryPos $pos, $timeout=null)
 Set the primary wait position and wait for ALL replica DBs to catch up to it.This method is only intended for use a throttling mechanism for high-volume updates. Unlike waitFor(), failure does not effect laggedReplicaUsed().
Parameters
DBPrimaryPos$posPrimary position
int | null$timeoutMax seconds to wait; default is mWaitTimeout
Returns
bool Success (able to connect and no timeouts reached)

 
 waitForPrimaryPos (IDatabase $conn)
 Wait for a replica DB to reach a specified primary position.If $conn is not a replica server connection, then this will return true. Otherwise, if $pos is not provided, this will connect to the primary server to get an accurate position.
Parameters
IDatabase$connReplica DB
Returns
bool Success
Since
1.37

 

Protected Member Functions

 reallyOpenConnection ( $i, DatabaseDomain $domain, array $lbInfo)
 
- Protected Member Functions inherited from Wikimedia\Rdbms\LoadBalancer
 configure (array $params)
 
 getConnLogContext (IDatabase $conn, array $extras=[])
 Create a log context to pass to PSR-3 logger functions.
 
 getExistingReaderIndex ( $group)
 Get the server index chosen for DB_REPLICA connections for the given query group.
 
 resolveDomainInstance (DatabaseDomain|string|false $domain)
 
 sanitizeConnectionFlags ( $flags, $domain)
 Sanitize connection flags provided by a call to getConnection()
 

Additional Inherited Members

- Public Attributes inherited from Wikimedia\Rdbms\ILoadBalancerForOwner
const STAGE_POSTCOMMIT_CALLBACKS = 'stage-postcommit-callbacks'
 Manager of ILoadBalancer instances is running post-commit callbacks.
 
const STAGE_POSTROLLBACK_CALLBACKS = 'stage-postrollback-callbacks'
 Manager of ILoadBalancer instances is running post-rollback callbacks.
 
- Public Attributes inherited from Wikimedia\Rdbms\ILoadBalancer
const CONN_SILENCE_ERRORS = 4
 Yield null on connection failure instead of throwing an exception.
 
const CONN_TRX_AUTOCOMMIT = 1
 Yield a tracked autocommit-mode handle (reuse existing ones)
 
const CONN_UNTRACKED_GAUGE = 2
 Yield an untracked, low-timeout, autocommit-mode handle (to gauge server health)
 
const DB_PRIMARY = -2
 Request a primary, write-enabled DB connection.
 
const DB_REPLICA = -1
 Request a replica DB connection.
 
const DOMAIN_ANY = ''
 Domain specifier when no specific database needs to be selected.
 
const GROUP_GENERIC = ''
 The generic query group.
 

Detailed Description

Placeholder LoadBalancer that throws an error upon attempts to access connections.

This is useful when running code with no config file present, e.g. during installation.

Since
1.40

Definition at line 18 of file LoadBalancerDisabled.php.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\Rdbms\LoadBalancerDisabled::__construct ( array $params = [])
Parameters
array$paramsParameter map with keys:
  • servers : List of server configuration maps, starting with either the global master or local datacenter multi-master, and optionally followed by local datacenter replicas. Each server configuration map has the same format as the Database::factory() $params argument, with the following additional optional fields:
    • type: the DB type (sqlite, mysql, postgres,...)
    • max lag: per-server override of the "max lag" [optional]
    • is static: whether the dataset is static and this server has a copy [optional]
  • localDomain: A DatabaseDomain or domain ID string
  • loadMonitor : LoadMonitor::__construct() parameters with "class" field [optional]
  • readOnlyReason : Reason the primary server is read-only (false if not) [optional]
  • srvCache : BagOStuff object for server cache [optional]
  • wanCache : WANObjectCache object [optional]
  • databaseFactory: DatabaseFactory object [optional]
  • chronologyProtector: ChronologyProtector object [optional]
  • defaultGroup: Default query group; the generic group if not specified [optional]
  • hostname : The name of the current server [optional]
  • cliMode: Whether the execution context is a CLI script [optional]
  • profiler : Callback that takes a section name argument and returns a ScopedCallback instance that ends the profile section in its destructor [optional]
  • trxProfiler: TransactionProfiler instance [optional]
  • logger: PSR-3 logger instance [optional]
  • errorLogger : Callback that takes an Exception and logs it [optional]
  • deprecationLogger: Callback to log a deprecation warning [optional]
  • roundStage: STAGE_POSTCOMMIT_* class constant; for internal use [optional]
  • clusterName: The name of the overall (single/multi-datacenter) cluster of servers managing the dataset, regardless of 'servers' excluding replicas and multi-masters from remote datacenter [optional]
  • criticalSectionProvider: CriticalSectionProvider instance [optional]
  • statsFactory: StatsFactory instance [optional]

Reimplemented from Wikimedia\Rdbms\LoadBalancer.

Definition at line 20 of file LoadBalancerDisabled.php.

Member Function Documentation

◆ getConnection()

Wikimedia\Rdbms\LoadBalancerDisabled::getConnection ( $i,
$groups = [],
string|false $domain = false,
$flags = 0 )
Parameters
int$iSpecific (overrides $groups) or virtual (DB_PRIMARY/DB_REPLICA) server index
string[] | string$groupsQuery group(s) in preference order; [] for the default group
string | false$domainDB domain ID or false for the local domain
int$flagsBitfield of CONN_* class constants
Returns
never

Reimplemented from Wikimedia\Rdbms\LoadBalancer.

Definition at line 56 of file LoadBalancerDisabled.php.

◆ getConnectionInternal()

Wikimedia\Rdbms\LoadBalancerDisabled::getConnectionInternal ( $i,
$groups = [],
$domain = false,
$flags = 0 )
Access: internal
Only to be used by DBConnRef
Parameters
int$iSpecific (overrides $groups) or virtual (DB_PRIMARY/DB_REPLICA) server index
string[] | string$groupsQuery group(s) in preference order; [] for the default group
string | false$domainDB domain ID or false for the local domain
int$flagsBitfield of CONN_* class constants (e.g. CONN_TRX_AUTOCOMMIT)
Returns
never

Reimplemented from Wikimedia\Rdbms\LoadBalancer.

Definition at line 68 of file LoadBalancerDisabled.php.

◆ getMaintenanceConnectionRef()

Wikimedia\Rdbms\LoadBalancerDisabled::getMaintenanceConnectionRef ( $i,
$groups = [],
$domain = false,
$flags = 0 )
Parameters
int$iSpecific (overrides $groups) or virtual (DB_PRIMARY/DB_REPLICA) server index
string[] | string$groupsQuery group(s) in preference order; [] for the default group
string | false$domainDB domain ID or false for the local domain
int$flagsBitfield of CONN_* class constants
Returns
never

Reimplemented from Wikimedia\Rdbms\LoadBalancer.

Definition at line 80 of file LoadBalancerDisabled.php.

◆ reallyOpenConnection()

Wikimedia\Rdbms\LoadBalancerDisabled::reallyOpenConnection ( $i,
DatabaseDomain $domain,
array $lbInfo )
protected
Parameters
int$i
DatabaseDomain$domain
array$lbInfo
Returns
never

Reimplemented from Wikimedia\Rdbms\LoadBalancer.

Definition at line 44 of file LoadBalancerDisabled.php.

The documentation for this class was generated from the following file: