includes/libs/rdbms/lbfactory/ILBFactory.php

   1 <?php
   2 /**
   3  * Generator and manager of database load balancing objects
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup Database
  22  */
  23
  24 namespace Wikimedia\Rdbms;
  25
  26 use InvalidArgumentException;
  27
  28 /**
  29  * An interface for generating database load balancers
  30  * @ingroup Database
  31  * @since 1.28
  32  */
  33 interface ILBFactory {
  34         /** @var int Don't save DB positions at all */
  35         const SHUTDOWN_NO_CHRONPROT = 0; // don't save DB positions at all
  36         /** @var int Save DB positions, but don't wait on remote DCs */
  37         const SHUTDOWN_CHRONPROT_ASYNC = 1;
  38         /** @var int Save DB positions, waiting on all DCs */
  39         const SHUTDOWN_CHRONPROT_SYNC = 2;
  40
  41         /** @var string Default main LB cluster name (do not change this) */
  42         const CLUSTER_MAIN_DEFAULT = 'DEFAULT';
  43
  44         /**
  45          * Construct a manager of ILoadBalancer objects
  46          *
  47          * Sub-classes will extend the required keys in $conf with additional parameters
  48          *
  49          * @param array $conf Array with keys:
  50          *  - localDomain: A DatabaseDomain or domain ID string.
  51          *  - readOnlyReason: Reason the master DB is read-only if so [optional]
  52          *  - srvCache: BagOStuff object for server cache [optional]
  53          *  - memStash: BagOStuff object for cross-datacenter memory storage [optional]
  54          *  - wanCache: WANObjectCache object [optional]
  55          *  - hostname: The name of the current server [optional]
  56          *  - cliMode: Whether the execution context is a CLI script. [optional]
  57          *  - maxLag: Try to avoid DB replicas with lag above this many seconds [optional]
  58          *  - profiler: Class name or instance with profileIn()/profileOut() methods. [optional]
  59          *  - trxProfiler: TransactionProfiler instance. [optional]
  60          *  - replLogger: PSR-3 logger instance. [optional]
  61          *  - connLogger: PSR-3 logger instance. [optional]
  62          *  - queryLogger: PSR-3 logger instance. [optional]
  63          *  - perfLogger: PSR-3 logger instance. [optional]
  64          *  - errorLogger: Callback that takes an Exception and logs it. [optional]
  65          *  - deprecationLogger: Callback to log a deprecation warning. [optional]
  66          *  - secret: Secret string to use for HMAC hashing [optional]
  67          * @throws InvalidArgumentException
  68          */
  69         public function __construct( array $conf );
  70
  71         /**
  72          * Disables all load balancers. All connections are closed, and any attempt to
  73          * open a new connection will result in a DBAccessError.
  74          * @see ILoadBalancer::disable()
  75          */
  76         public function destroy();
  77
  78         /**
  79          * Get the local (and default) database domain ID of connection handles
  80          *
  81          * @see DatabaseDomain
  82          * @return string Database domain ID; this specifies DB name, schema, and table prefix
  83          * @since 1.32
  84          */
  85         public function getLocalDomainID();
  86
  87         /**
  88          * @param DatabaseDomain|string|bool $domain Database domain
  89          * @return string Value of $domain if provided or the local domain otherwise
  90          * @since 1.32
  91          */
  92         public function resolveDomainID( $domain );
  93
  94         /**
  95          * Close all connection and redefine the local domain for testing or schema creation
  96          *
  97          * @param DatabaseDomain|string $domain
  98          * @since 1.33
  99          */
 100         public function redefineLocalDomain( $domain );
 101
 102         /**
 103          * Create a new load balancer object. The resulting object will be untracked,
 104          * not chronology-protected, and the caller is responsible for cleaning it up.
 105          *
 106          * This method is for only advanced usage and callers should almost always use
 107          * getMainLB() instead. This method can be useful when a table is used as a key/value
 108          * store. In that cases, one might want to query it in autocommit mode (DBO_TRX off)
 109          * but still use DBO_TRX transaction rounds on other tables.
 110          *
 111          * @param bool|string $domain Domain ID, or false for the current domain
 112          * @param int|null $owner Owner ID of the new instance (e.g. this LBFactory ID)
 113          * @return ILoadBalancer
 114          */
 115         public function newMainLB( $domain = false, $owner = null );
 116
 117         /**
 118          * Get a cached (tracked) load balancer object.
 119          *
 120          * @param bool|string $domain Domain ID, or false for the current domain
 121          * @return ILoadBalancer
 122          */
 123         public function getMainLB( $domain = false );
 124
 125         /**
 126          * Create a new load balancer for external storage. The resulting object will be
 127          * untracked, not chronology-protected, and the caller is responsible for cleaning it up.
 128          *
 129          * This method is for only advanced usage and callers should almost always use
 130          * getExternalLB() instead. This method can be useful when a table is used as a
 131          * key/value store. In that cases, one might want to query it in autocommit mode
 132          * (DBO_TRX off) but still use DBO_TRX transaction rounds on other tables.
 133          *
 134          * @param string $cluster External storage cluster name
 135          * @param int|null $owner Owner ID of the new instance (e.g. this LBFactory ID)
 136          * @return ILoadBalancer
 137          */
 138         public function newExternalLB( $cluster, $owner = null );
 139
 140         /**
 141          * Get a cached (tracked) load balancer for external storage
 142          *
 143          * @param string $cluster External storage cluster name
 144          * @return ILoadBalancer
 145          */
 146         public function getExternalLB( $cluster );
 147
 148         /**
 149          * Get cached (tracked) load balancers for all main database clusters
 150          *
 151          * The default cluster name is ILoadBalancer::CLUSTER_MAIN_DEFAULT
 152          *
 153          * @return ILoadBalancer[] Map of (cluster name => ILoadBalancer)
 154          * @since 1.29
 155          */
 156         public function getAllMainLBs();
 157
 158         /**
 159          * Get cached (tracked) load balancers for all external database clusters
 160          *
 161          * @return ILoadBalancer[] Map of (cluster name => ILoadBalancer)
 162          * @since 1.29
 163          */
 164         public function getAllExternalLBs();
 165
 166         /**
 167          * Execute a function for each currently tracked (instantiated) load balancer
 168          *
 169          * The callback is called with the load balancer as the first parameter,
 170          * and $params passed as the subsequent parameters.
 171          *
 172          * @param callable $callback
 173          * @param array $params
 174          */
 175         public function forEachLB( $callback, array $params = [] );
 176
 177         /**
 178          * Prepare all currently tracked (instantiated) load balancers for shutdown
 179          *
 180          * @param int $mode One of the class SHUTDOWN_* constants
 181          * @param callable|null $workCallback Work to mask ChronologyProtector writes
 182          * @param int|null &$cpIndex Position key write counter for ChronologyProtector
 183          * @param string|null &$cpClientId Client ID hash for ChronologyProtector
 184          */
 185         public function shutdown(
 186                 $mode = self::SHUTDOWN_CHRONPROT_SYNC,
 187                 callable $workCallback = null,
 188                 &$cpIndex = null,
 189                 &$cpClientId = null
 190         );
 191
 192         /**
 193          * Commit all replica DB transactions so as to flush any REPEATABLE-READ or SSI snapshot
 194          *
 195          * This is useful for getting rid of stale data from an implicit transaction round
 196          *
 197          * @param string $fname Caller name
 198          */
 199         public function flushReplicaSnapshots( $fname = __METHOD__ );
 200
 201         /**
 202          * Commit open transactions on all connections. This is useful for two main cases:
 203          *   - a) To commit changes to the masters.
 204          *   - b) To release the snapshot on all connections, master and replica DBs.
 205          * @param string $fname Caller name
 206          * @param array $options Options map:
 207          *   - maxWriteDuration: abort if more than this much time was spent in write queries
 208          */
 209         public function commitAll( $fname = __METHOD__, array $options = [] );
 210
 211         /**
 212          * Flush any master transaction snapshots and set DBO_TRX (if DBO_DEFAULT is set)
 213          *
 214          * The DBO_TRX setting will be reverted to the default in each of these methods:
 215          *   - commitMasterChanges()
 216          *   - rollbackMasterChanges()
 217          *   - commitAll()
 218          *
 219          * This allows for custom transaction rounds from any outer transaction scope.
 220          *
 221          * @param string $fname
 222          * @throws DBTransactionError
 223          */
 224         public function beginMasterChanges( $fname = __METHOD__ );
 225
 226         /**
 227          * Commit changes and clear view snapshots on all master connections
 228          * @param string $fname Caller name
 229          * @param array $options Options map:
 230          *   - maxWriteDuration: abort if more than this much time was spent in write queries
 231          * @throws DBTransactionError
 232          */
 233         public function commitMasterChanges( $fname = __METHOD__, array $options = [] );
 234
 235         /**
 236          * Rollback changes on all master connections
 237          * @param string $fname Caller name
 238          */
 239         public function rollbackMasterChanges( $fname = __METHOD__ );
 240
 241         /**
 242          * Check if an explicit transaction round is active
 243          * @return bool
 244          * @since 1.29
 245          */
 246         public function hasTransactionRound();
 247
 248         /**
 249          * Check if transaction rounds can be started, committed, or rolled back right now
 250          *
 251          * This can be used as a recusion guard to avoid exceptions in transaction callbacks
 252          *
 253          * @return bool
 254          * @since 1.32
 255          */
 256         public function isReadyForRoundOperations();
 257
 258         /**
 259          * Determine if any master connection has pending changes
 260          * @return bool
 261          */
 262         public function hasMasterChanges();
 263
 264         /**
 265          * Detemine if any lagged replica DB connection was used
 266          * @return bool
 267          */
 268         public function laggedReplicaUsed();
 269
 270         /**
 271          * Determine if any master connection has pending/written changes from this request
 272          * @param float|null $age How many seconds ago is "recent" [defaults to LB lag wait timeout]
 273          * @return bool
 274          */
 275         public function hasOrMadeRecentMasterChanges( $age = null );
 276
 277         /**
 278          * Waits for the replica DBs to catch up to the current master position
 279          *
 280          * Use this when updating very large numbers of rows, as in maintenance scripts,
 281          * to avoid causing too much lag. Of course, this is a no-op if there are no replica DBs.
 282          *
 283          * By default this waits on all DB clusters actually used in this request.
 284          * This makes sense when lag being waiting on is caused by the code that does this check.
 285          * In that case, setting "ifWritesSince" can avoid the overhead of waiting for clusters
 286          * that were not changed since the last wait check. To forcefully wait on a specific cluster
 287          * for a given domain, use the 'domain' parameter. To forcefully wait on an "external" cluster,
 288          * use the "cluster" parameter.
 289          *
 290          * Never call this function after a large DB write that is *still* in a transaction.
 291          * It only makes sense to call this after the possible lag inducing changes were committed.
 292          *
 293          * @param array $opts Optional fields that include:
 294          *   - domain : wait on the load balancer DBs that handles the given domain ID
 295          *   - cluster : wait on the given external load balancer DBs
 296          *   - timeout : Max wait time. Default: 60 seconds for CLI, 1 second for web.
 297          *   - ifWritesSince: Only wait if writes were done since this UNIX timestamp
 298          * @return bool True on success, false if a timeout or error occurred while waiting
 299          */
 300         public function waitForReplication( array $opts = [] );
 301
 302         /**
 303          * Add a callback to be run in every call to waitForReplication() before waiting
 304          *
 305          * Callbacks must clear any transactions that they start
 306          *
 307          * @param string $name Callback name
 308          * @param callable|null $callback Use null to unset a callback
 309          */
 310         public function setWaitForReplicationListener( $name, callable $callback = null );
 311
 312         /**
 313          * Get a token asserting that no transaction writes are active
 314          *
 315          * @param string $fname Caller name (e.g. __METHOD__)
 316          * @return mixed A value to pass to commitAndWaitForReplication()
 317          */
 318         public function getEmptyTransactionTicket( $fname );
 319
 320         /**
 321          * Convenience method for safely running commitMasterChanges()/waitForReplication()
 322          *
 323          * This will commit and wait unless $ticket indicates it is unsafe to do so
 324          *
 325          * @param string $fname Caller name (e.g. __METHOD__)
 326          * @param mixed $ticket Result of getEmptyTransactionTicket()
 327          * @param array $opts Options to waitForReplication()
 328          * @return bool True if the wait was successful, false on timeout
 329          */
 330         public function commitAndWaitForReplication( $fname, $ticket, array $opts = [] );
 331
 332         /**
 333          * @param string $dbName DB master name (e.g. "db1052")
 334          * @return float|bool UNIX timestamp when client last touched the DB or false if not recent
 335          */
 336         public function getChronologyProtectorTouched( $dbName );
 337
 338         /**
 339          * Disable the ChronologyProtector for all load balancers
 340          *
 341          * This can be called at the start of special API entry points
 342          */
 343         public function disableChronologyProtection();
 344
 345         /**
 346          * Set a new table prefix for the existing local domain ID for testing
 347          *
 348          * @param string $prefix
 349          * @since 1.33
 350          */
 351         public function setLocalDomainPrefix( $prefix );
 352
 353         /**
 354          * Close all open database connections on all open load balancers.
 355          */
 356         public function closeAll();
 357
 358         /**
 359          * @param string $agent Agent name for query profiling
 360          */
 361         public function setAgentName( $agent );
 362
 363         /**
 364          * Append ?cpPosIndex parameter to a URL for ChronologyProtector purposes if needed
 365          *
 366          * Note that unlike cookies, this works across domains
 367          *
 368          * @param string $url
 369          * @param int $index Write counter index
 370          * @return string
 371          */
 372         public function appendShutdownCPIndexAsQuery( $url, $index );
 373
 374         /**
 375          * Get the client ID of the ChronologyProtector instance
 376          *
 377          * @return string Client ID
 378          * @since 1.34
 379          */
 380         public function getChronologyProtectorClientId();
 381
 382         /**
 383          * @param array $info Map of fields, including:
 384          *   - IPAddress : IP address
 385          *   - UserAgent : User-Agent HTTP header
 386          *   - ChronologyProtection : cookie/header value specifying ChronologyProtector usage
 387          *   - ChronologyPositionIndex: timestamp used to get up-to-date DB positions for the agent
 388          */
 389         public function setRequestInfo( array $info );
 390
 391         /**
 392          * Make certain table names use their own database, schema, and table prefix
 393          * when passed into SQL queries pre-escaped and without a qualified database name
 394          *
 395          * For example, "user" can be converted to "myschema.mydbname.user" for convenience.
 396          * Appearances like `user`, somedb.user, somedb.someschema.user will used literally.
 397          *
 398          * Calling this twice will completely clear any old table aliases. Also, note that
 399          * callers are responsible for making sure the schemas and databases actually exist.
 400          *
 401          * @param array[] $aliases Map of (table => (dbname, schema, prefix) map)
 402          * @since 1.31
 403          */
 404         public function setTableAliases( array $aliases );
 405
 406         /**
 407          * Convert certain index names to alternative names before querying the DB
 408          *
 409          * Note that this applies to indexes regardless of the table they belong to.
 410          *
 411          * This can be employed when an index was renamed X => Y in code, but the new Y-named
 412          * indexes were not yet built on all DBs. After all the Y-named ones are added by the DBA,
 413          * the aliases can be removed, and then the old X-named indexes dropped.
 414          *
 415          * @param string[] $aliases
 416          * @since 1.31
 417          */
 418         public function setIndexAliases( array $aliases );
 419 }