includes/libs/rdbms/loadbalancer/ILoadBalancerForOwner.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  */
  20 namespace Wikimedia\Rdbms;
  21
  22 use Exception;
  23
  24 /**
  25  * Internal interface for load balancer instances exposed to their owner
  26  *
  27  * Instances are either owned by an LBFactory object or owned by the caller that created
  28  * the instance using a constructor/factory function such as LBFactory::newMain().
  29  *
  30  * @internal Only for use within LBFactory/LoadMonitor/ChronologyProtector
  31  * @since 1.39
  32  * @ingroup Database
  33  */
  34 interface ILoadBalancerForOwner extends ILoadBalancer {
  35         /** Manager of ILoadBalancer instances is running post-commit callbacks */
  36         public const STAGE_POSTCOMMIT_CALLBACKS = 'stage-postcommit-callbacks';
  37         /** Manager of ILoadBalancer instances is running post-rollback callbacks */
  38         public const STAGE_POSTROLLBACK_CALLBACKS = 'stage-postrollback-callbacks';
  39
  40         /**
  41          * @param array $params Parameter map with keys:
  42          *  - servers : List of server configuration maps, starting with either the global master
  43          *     or local datacenter multi-master, and optionally followed by local datacenter replicas.
  44          *     Each server configuration map has the same format as the Database::factory() $params
  45          *     argument, with the following additional optional fields:
  46          *      - type: the DB type (sqlite, mysql, postgres,...)
  47          *      - groupLoads: map of (group => weight for this server) [optional]
  48          *      - max lag: per-server override of the "max lag" [optional]
  49          *      - is static: whether the dataset is static *and* this server has a copy [optional]
  50          *  - localDomain: A DatabaseDomain or domain ID string
  51          *  - loadMonitor : LoadMonitor::__construct() parameters with "class" field [optional]
  52          *  - readOnlyReason : Reason the primary server is read-only (false if not) [optional]
  53          *  - srvCache : BagOStuff object for server cache [optional]
  54          *  - wanCache : WANObjectCache object [optional]
  55          *  - databaseFactory: DatabaseFactory object [optional]
  56          *  - chronologyProtector: ChronologyProtector object [optional]
  57          *  - defaultGroup: Default query group; the generic group if not specified [optional]
  58          *  - hostname : The name of the current server [optional]
  59          *  - cliMode: Whether the execution context is a CLI script [optional]
  60          *  - profiler : Callback that takes a section name argument and returns
  61          *      a ScopedCallback instance that ends the profile section in its destructor [optional]
  62          *  - trxProfiler: TransactionProfiler instance [optional]
  63          *  - logger: 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          *  - roundStage: STAGE_POSTCOMMIT_* class constant; for internal use [optional]
  67          *  - clusterName: The name of the overall (single/multi-datacenter) cluster of servers
  68          *     managing the dataset, regardless of 'servers' excluding replicas and
  69          *     multi-masters from remote datacenter [optional]
  70          *  - criticalSectionProvider: CriticalSectionProvider instance [optional]
  71          */
  72         public function __construct( array $params );
  73
  74         /**
  75          * Close all connections and disable this load balancer
  76          *
  77          * Any attempt to open a new connection will result in a DBAccessError.
  78          *
  79          * @param string $fname Caller name @phan-mandatory-param
  80          */
  81         public function disable( $fname = __METHOD__ );
  82
  83         /**
  84          * Close all open connections
  85          *
  86          * @param string $fname Caller name @phan-mandatory-param
  87          *
  88          */
  89         public function closeAll( $fname = __METHOD__ );
  90
  91         /**
  92          * Run pre-commit callbacks and defer execution of post-commit callbacks
  93          *
  94          * Use this only for multi-database commits
  95          *
  96          * @param string $fname Caller name @phan-mandatory-param
  97          * @return int Number of pre-commit callbacks run (since 1.32)
  98          * @since 1.37
  99          */
 100         public function finalizePrimaryChanges( $fname = __METHOD__ );
 101
 102         /**
 103          * Perform all pre-commit checks for things like replication safety
 104          *
 105          * Use this only for multi-database commits
 106          *
 107          * @param int $maxWriteDuration : max write query duration time in seconds
 108          * @param string $fname Caller name @phan-mandatory-param
 109          * @throws DBTransactionError
 110          * @since 1.37
 111          */
 112         public function approvePrimaryChanges( int $maxWriteDuration, $fname = __METHOD__ );
 113
 114         /**
 115          * Flush any primary transaction snapshots and set DBO_TRX (if DBO_DEFAULT is set)
 116          *
 117          * The DBO_TRX setting will be reverted to the default in each of these methods:
 118          *   - commitPrimaryChanges()
 119          *   - rollbackPrimaryChanges()
 120          * This allows for custom transaction rounds from any outer transaction scope.
 121          *
 122          * @param string $fname Caller name @phan-mandatory-param
 123          * @throws DBExpectedError
 124          * @since 1.37
 125          */
 126         public function beginPrimaryChanges( $fname = __METHOD__ );
 127
 128         /**
 129          * Issue COMMIT on all open primary connections to flush changes and view snapshots
 130          * @param string $fname Caller name @phan-mandatory-param
 131          * @throws DBExpectedError
 132          * @since 1.37
 133          */
 134         public function commitPrimaryChanges( $fname = __METHOD__ );
 135
 136         /**
 137          * Consume and run all pending post-COMMIT/ROLLBACK callbacks and commit dangling transactions
 138          *
 139          * @param string $fname Caller name @phan-mandatory-param
 140          * @return Exception|null The first exception or null if there were none
 141          * @since 1.37
 142          */
 143         public function runPrimaryTransactionIdleCallbacks( $fname = __METHOD__ );
 144
 145         /**
 146          * Run all recurring post-COMMIT/ROLLBACK listener callbacks
 147          *
 148          * @param string $fname Caller name @phan-mandatory-param
 149          * @return Exception|null The first exception or null if there were none
 150          * @since 1.37
 151          */
 152         public function runPrimaryTransactionListenerCallbacks( $fname = __METHOD__ );
 153
 154         /**
 155          * Issue ROLLBACK only on primary, only if queries were done on connection
 156          *
 157          * @param string $fname Caller name @phan-mandatory-param
 158          * @throws DBExpectedError
 159          * @since 1.37
 160          */
 161         public function rollbackPrimaryChanges( $fname = __METHOD__ );
 162
 163         /**
 164          * Release/destroy session-level named locks, table locks, and temp tables
 165          *
 166          * Only call this function right after calling rollbackPrimaryChanges()
 167          *
 168          * @param string $fname Caller name @phan-mandatory-param
 169          * @throws DBExpectedError
 170          * @since 1.38
 171          */
 172         public function flushPrimarySessions( $fname = __METHOD__ );
 173
 174         /**
 175          * Commit all replica DB transactions so as to flush any REPEATABLE-READ or SSI snapshots
 176          *
 177          * @param string $fname Caller name @phan-mandatory-param
 178          */
 179         public function flushReplicaSnapshots( $fname = __METHOD__ );
 180
 181         /**
 182          * Commit all primary DB transactions so as to flush any REPEATABLE-READ or SSI snapshots
 183          *
 184          * An error will be thrown if a connection has pending writes or callbacks
 185          *
 186          * @param string $fname Caller name @phan-mandatory-param
 187          * @since 1.37
 188          */
 189         public function flushPrimarySnapshots( $fname = __METHOD__ );
 190
 191         /**
 192          * Get the list of callers that have pending primary changes
 193          *
 194          * @return string[] List of method names
 195          * @since 1.37
 196          */
 197         public function pendingPrimaryChangeCallers();
 198
 199         /**
 200          * Set a new table prefix for the existing local domain ID for testing
 201          *
 202          * @param string $prefix
 203          * @since 1.33
 204          */
 205         public function setLocalDomainPrefix( $prefix );
 206
 207         /**
 208          * Reconfigure using the given config array.
 209          * If the config changed, this invalidates all existing connections.
 210          *
 211          * @warning This must only be called in top level code, typically via
 212          * LBFactory::reconfigure.
 213          *
 214          * @since 1.39
 215          *
 216          * @param array $params A configuration array, using the same structure as
 217          *        the one passed to the LoadBalancer's constructor.
 218          */
 219         public function reconfigure( array $params );
 220
 221         /**
 222          * Close all connection and redefine the local domain for testing or schema creation
 223          *
 224          * @param DatabaseDomain|string $domain
 225          * @since 1.33
 226          */
 227         public function redefineLocalDomain( $domain );
 228
 229         /**
 230          * @return bool Whether a primary connection is already open
 231          * @since 1.37
 232          */
 233         public function hasPrimaryConnection();
 234
 235         /**
 236          * Convert certain index names to alternative names before querying the DB
 237          *
 238          * Note that this applies to indexes regardless of the table they belong to.
 239          *
 240          * This can be employed when an index was renamed X => Y in code, but the new Y-named
 241          * indexes were not yet built on all DBs. After all the Y-named ones are added by the DBA,
 242          * the aliases can be removed, and then the old X-named indexes dropped.
 243          *
 244          * @param string[] $aliases
 245          * @since 1.31
 246          */
 247         public function setIndexAliases( array $aliases );
 248
 249         /**
 250          * Get the last time that a tracked connection was used to commit a write
 251          *
 252          * @internal Should only be called from the rdbms library.
 253          *
 254          * @return float|null UNIX timestamp, or, false (if no writes were committed)
 255          * @since 1.37
 256          */
 257         public function lastPrimaryChangeTimestamp();
 258
 259         /**
 260          * Set the primary wait position and wait for ALL replica DBs to catch up to it
 261          *
 262          * This method is only intended for use a throttling mechanism for high-volume updates.
 263          * Unlike waitFor(), failure does not effect laggedReplicaUsed().
 264          *
 265          * @param DBPrimaryPos $pos Primary position
 266          * @param int|null $timeout Max seconds to wait; default is mWaitTimeout
 267          * @return bool Success (able to connect and no timeouts reached)
 268          */
 269         public function waitForAll( DBPrimaryPos $pos, $timeout = null );
 270
 271         /**
 272          * Whether a highly "lagged" replica database connection was queried.
 273          *
 274          * @note This method will never cause a new DB connection
 275          * @return bool
 276          */
 277         public function laggedReplicaUsed();
 278 }