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