includes/libs/rdbms/connectionmanager/ConnectionManager.php

   1 <?php
   2
   3 namespace Wikimedia\Rdbms;
   4
   5 use Database;
   6 use DBConnRef;
   7 use IDatabase;
   8 use InvalidArgumentException;
   9 use LoadBalancer;
  10
  11 /**
  12  * Database connection manager.
  13  *
  14  * This manages access to master and replica databases.
  15  *
  16  * @since 1.29
  17  *
  18  * @license GPL-2.0+
  19  * @author Addshore
  20  */
  21 class ConnectionManager {
  22
  23         /**
  24          * @var LoadBalancer
  25          */
  26         private $loadBalancer;
  27
  28         /**
  29          * The symbolic name of the target database, or false for the local wiki's database.
  30          *
  31          * @var string|false
  32          */
  33         private $domain;
  34
  35         /**
  36          * @var string[]
  37          */
  38         private $groups = [];
  39
  40         /**
  41          * @param LoadBalancer $loadBalancer
  42          * @param string|bool $domain Optional logical DB name, defaults to current wiki.
  43          *        This follows the convention for database names used by $loadBalancer.
  44          * @param string[] $groups see LoadBalancer::getConnection
  45          *
  46          * @throws InvalidArgumentException
  47          */
  48         public function __construct( LoadBalancer $loadBalancer, $domain = false, array $groups = [] ) {
  49                 if ( !is_string( $domain ) && $domain !== false ) {
  50                         throw new InvalidArgumentException( '$dbName must be a string, or false.' );
  51                 }
  52
  53                 $this->loadBalancer = $loadBalancer;
  54                 $this->domain = $domain;
  55                 $this->groups = $groups;
  56         }
  57
  58         /**
  59          * @param int $i
  60          * @param string[]|null $groups
  61          *
  62          * @return Database
  63          */
  64         private function getConnection( $i, array $groups = null ) {
  65                 $groups = $groups === null ? $this->groups : $groups;
  66                 return $this->loadBalancer->getConnection( $i, $groups, $this->domain );
  67         }
  68
  69         /**
  70          * @param int $i
  71          * @param string[]|null $groups
  72          *
  73          * @return DBConnRef
  74          */
  75         private function getConnectionRef( $i, array $groups = null ) {
  76                 $groups = $groups === null ? $this->groups : $groups;
  77                 return $this->loadBalancer->getConnectionRef( $i, $groups, $this->domain );
  78         }
  79
  80         /**
  81          * Returns a connection to the master DB, for updating. The connection should later be released
  82          * by calling releaseConnection().
  83          *
  84          * @since 1.29
  85          *
  86          * @return Database
  87          */
  88         public function getWriteConnection() {
  89                 return $this->getConnection( DB_MASTER );
  90         }
  91
  92         /**
  93          * Returns a database connection for reading. The connection should later be released by
  94          * calling releaseConnection().
  95          *
  96          * @since 1.29
  97          *
  98          * @param string[]|null $groups
  99          *
 100          * @return Database
 101          */
 102         public function getReadConnection( array $groups = null ) {
 103                 $groups = $groups === null ? $this->groups : $groups;
 104                 return $this->getConnection( DB_REPLICA, $groups );
 105         }
 106
 107         /**
 108          * @since 1.29
 109          *
 110          * @param IDatabase $db
 111          */
 112         public function releaseConnection( IDatabase $db ) {
 113                 $this->loadBalancer->reuseConnection( $db );
 114         }
 115
 116         /**
 117          * Returns a connection ref to the master DB, for updating.
 118          *
 119          * @since 1.29
 120          *
 121          * @return DBConnRef
 122          */
 123         public function getWriteConnectionRef() {
 124                 return $this->getConnectionRef( DB_MASTER );
 125         }
 126
 127         /**
 128          * Returns a database connection ref for reading.
 129          *
 130          * @since 1.29
 131          *
 132          * @param string[]|null $groups
 133          *
 134          * @return DBConnRef
 135          */
 136         public function getReadConnectionRef( array $groups = null ) {
 137                 $groups = $groups === null ? $this->groups : $groups;
 138                 return $this->getConnectionRef( DB_REPLICA, $groups );
 139         }
 140
 141         /**
 142          * Begins an atomic section and returns a database connection to the master DB, for updating.
 143          *
 144          * @since 1.29
 145          *
 146          * @param string $fname
 147          *
 148          * @return Database
 149          */
 150         public function beginAtomicSection( $fname ) {
 151                 $db = $this->getWriteConnection();
 152                 $db->startAtomic( $fname );
 153
 154                 return $db;
 155         }
 156
 157         /**
 158          * @since 1.29
 159          *
 160          * @param IDatabase $db
 161          * @param string $fname
 162          */
 163         public function commitAtomicSection( IDatabase $db, $fname ) {
 164                 $db->endAtomic( $fname );
 165                 $this->releaseConnection( $db );
 166         }
 167
 168         /**
 169          * @since 1.29
 170          *
 171          * @param IDatabase $db
 172          * @param string $fname
 173          */
 174         public function rollbackAtomicSection( IDatabase $db, $fname ) {
 175                 // FIXME: there does not seem to be a clean way to roll back an atomic section?!
 176                 $db->rollback( $fname, 'flush' );
 177                 $this->releaseConnection( $db );
 178         }
 179
 180 }