includes/libs/rdbms/database/DBConnRef.php

   1 <?php
   2
   3 namespace Wikimedia\Rdbms;
   4
   5 use InvalidArgumentException;
   6
   7 /**
   8  * Helper class to handle automatically marking connections as reusable (via RAII pattern)
   9  * as well handling deferring the actual network connection until the handle is used
  10  *
  11  * @note: proxy methods are defined explicitly to avoid interface errors
  12  * @ingroup Database
  13  * @since 1.22
  14  */
  15 class DBConnRef implements IDatabase {
  16         /** @var ILoadBalancer */
  17         private $lb;
  18         /** @var Database|null Live connection handle */
  19         private $conn;
  20         /** @var array|null N-tuple of (server index, group, DatabaseDomain|string) */
  21         private $params;
  22
  23         const FLD_INDEX = 0;
  24         const FLD_GROUP = 1;
  25         const FLD_DOMAIN = 2;
  26         const FLD_FLAGS = 3;
  27
  28         /**
  29          * @param ILoadBalancer $lb Connection manager for $conn
  30          * @param Database|array $conn Database handle or (server index, query groups, domain, flags)
  31          */
  32         public function __construct( ILoadBalancer $lb, $conn ) {
  33                 $this->lb = $lb;
  34                 if ( $conn instanceof Database ) {
  35                         $this->conn = $conn; // live handle
  36                 } elseif ( is_array( $conn ) && count( $conn ) >= 4 && $conn[self::FLD_DOMAIN] !== false ) {
  37                         $this->params = $conn;
  38                 } else {
  39                         throw new InvalidArgumentException( "Missing lazy connection arguments." );
  40                 }
  41         }
  42
  43         function __call( $name, array $arguments ) {
  44                 if ( $this->conn === null ) {
  45                         list( $db, $groups, $wiki, $flags ) = $this->params;
  46                         $this->conn = $this->lb->getConnection( $db, $groups, $wiki, $flags );
  47                 }
  48
  49                 return $this->conn->$name( ...$arguments );
  50         }
  51
  52         public function getServerInfo() {
  53                 return $this->__call( __FUNCTION__, func_get_args() );
  54         }
  55
  56         public function bufferResults( $buffer = null ) {
  57                 return $this->__call( __FUNCTION__, func_get_args() );
  58         }
  59
  60         public function trxLevel() {
  61                 return $this->__call( __FUNCTION__, func_get_args() );
  62         }
  63
  64         public function trxTimestamp() {
  65                 return $this->__call( __FUNCTION__, func_get_args() );
  66         }
  67
  68         public function explicitTrxActive() {
  69                 return $this->__call( __FUNCTION__, func_get_args() );
  70         }
  71
  72         public function tablePrefix( $prefix = null ) {
  73                 return $this->__call( __FUNCTION__, func_get_args() );
  74         }
  75
  76         public function dbSchema( $schema = null ) {
  77                 return $this->__call( __FUNCTION__, func_get_args() );
  78         }
  79
  80         public function getLBInfo( $name = null ) {
  81                 return $this->__call( __FUNCTION__, func_get_args() );
  82         }
  83
  84         public function setLBInfo( $name, $value = null ) {
  85                 return $this->__call( __FUNCTION__, func_get_args() );
  86         }
  87
  88         public function setLazyMasterHandle( IDatabase $conn ) {
  89                 return $this->__call( __FUNCTION__, func_get_args() );
  90         }
  91
  92         public function implicitGroupby() {
  93                 return $this->__call( __FUNCTION__, func_get_args() );
  94         }
  95
  96         public function implicitOrderby() {
  97                 return $this->__call( __FUNCTION__, func_get_args() );
  98         }
  99
 100         public function lastQuery() {
 101                 return $this->__call( __FUNCTION__, func_get_args() );
 102         }
 103
 104         public function doneWrites() {
 105                 return $this->__call( __FUNCTION__, func_get_args() );
 106         }
 107
 108         public function lastDoneWrites() {
 109                 return $this->__call( __FUNCTION__, func_get_args() );
 110         }
 111
 112         public function writesPending() {
 113                 return $this->__call( __FUNCTION__, func_get_args() );
 114         }
 115
 116         public function preCommitCallbacksPending() {
 117                 return $this->__call( __FUNCTION__, func_get_args() );
 118         }
 119
 120         public function writesOrCallbacksPending() {
 121                 return $this->__call( __FUNCTION__, func_get_args() );
 122         }
 123
 124         public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL ) {
 125                 return $this->__call( __FUNCTION__, func_get_args() );
 126         }
 127
 128         public function pendingWriteCallers() {
 129                 return $this->__call( __FUNCTION__, func_get_args() );
 130         }
 131
 132         public function pendingWriteRowsAffected() {
 133                 return $this->__call( __FUNCTION__, func_get_args() );
 134         }
 135
 136         public function isOpen() {
 137                 return $this->__call( __FUNCTION__, func_get_args() );
 138         }
 139
 140         public function setFlag( $flag, $remember = self::REMEMBER_NOTHING ) {
 141                 return $this->__call( __FUNCTION__, func_get_args() );
 142         }
 143
 144         public function clearFlag( $flag, $remember = self::REMEMBER_NOTHING ) {
 145                 return $this->__call( __FUNCTION__, func_get_args() );
 146         }
 147
 148         public function restoreFlags( $state = self::RESTORE_PRIOR ) {
 149                 return $this->__call( __FUNCTION__, func_get_args() );
 150         }
 151
 152         public function getFlag( $flag ) {
 153                 return $this->__call( __FUNCTION__, func_get_args() );
 154         }
 155
 156         public function getProperty( $name ) {
 157                 return $this->__call( __FUNCTION__, func_get_args() );
 158         }
 159
 160         public function getDomainID() {
 161                 if ( $this->conn === null ) {
 162                         $domain = $this->params[self::FLD_DOMAIN];
 163                         // Avoid triggering a database connection
 164                         return $domain instanceof DatabaseDomain ? $domain->getId() : $domain;
 165                 }
 166
 167                 return $this->__call( __FUNCTION__, func_get_args() );
 168         }
 169
 170         /**
 171          * @codeCoverageIgnore
 172          */
 173         public function getWikiID() {
 174                 return $this->getDomainID();
 175         }
 176
 177         public function getType() {
 178                 return $this->__call( __FUNCTION__, func_get_args() );
 179         }
 180
 181         public function open( $server, $user, $password, $dbName ) {
 182                 return $this->__call( __FUNCTION__, func_get_args() );
 183         }
 184
 185         public function fetchObject( $res ) {
 186                 return $this->__call( __FUNCTION__, func_get_args() );
 187         }
 188
 189         public function fetchRow( $res ) {
 190                 return $this->__call( __FUNCTION__, func_get_args() );
 191         }
 192
 193         public function numRows( $res ) {
 194                 return $this->__call( __FUNCTION__, func_get_args() );
 195         }
 196
 197         public function numFields( $res ) {
 198                 return $this->__call( __FUNCTION__, func_get_args() );
 199         }
 200
 201         public function fieldName( $res, $n ) {
 202                 return $this->__call( __FUNCTION__, func_get_args() );
 203         }
 204
 205         public function insertId() {
 206                 return $this->__call( __FUNCTION__, func_get_args() );
 207         }
 208
 209         public function dataSeek( $res, $row ) {
 210                 return $this->__call( __FUNCTION__, func_get_args() );
 211         }
 212
 213         public function lastErrno() {
 214                 return $this->__call( __FUNCTION__, func_get_args() );
 215         }
 216
 217         public function lastError() {
 218                 return $this->__call( __FUNCTION__, func_get_args() );
 219         }
 220
 221         public function affectedRows() {
 222                 return $this->__call( __FUNCTION__, func_get_args() );
 223         }
 224
 225         public function getSoftwareLink() {
 226                 return $this->__call( __FUNCTION__, func_get_args() );
 227         }
 228
 229         public function getServerVersion() {
 230                 return $this->__call( __FUNCTION__, func_get_args() );
 231         }
 232
 233         public function close() {
 234                 return $this->__call( __FUNCTION__, func_get_args() );
 235         }
 236
 237         public function query( $sql, $fname = __METHOD__, $tempIgnore = false ) {
 238                 return $this->__call( __FUNCTION__, func_get_args() );
 239         }
 240
 241         public function freeResult( $res ) {
 242                 return $this->__call( __FUNCTION__, func_get_args() );
 243         }
 244
 245         public function selectField(
 246                 $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
 247         ) {
 248                 return $this->__call( __FUNCTION__, func_get_args() );
 249         }
 250
 251         public function selectFieldValues(
 252                 $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
 253         ) {
 254                 return $this->__call( __FUNCTION__, func_get_args() );
 255         }
 256
 257         public function select(
 258                 $table, $vars, $conds = '', $fname = __METHOD__,
 259                 $options = [], $join_conds = []
 260         ) {
 261                 return $this->__call( __FUNCTION__, func_get_args() );
 262         }
 263
 264         public function selectSQLText(
 265                 $table, $vars, $conds = '', $fname = __METHOD__,
 266                 $options = [], $join_conds = []
 267         ) {
 268                 return $this->__call( __FUNCTION__, func_get_args() );
 269         }
 270
 271         public function selectRow(
 272                 $table, $vars, $conds, $fname = __METHOD__,
 273                 $options = [], $join_conds = []
 274         ) {
 275                 return $this->__call( __FUNCTION__, func_get_args() );
 276         }
 277
 278         public function estimateRowCount(
 279                 $table, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
 280         ) {
 281                 return $this->__call( __FUNCTION__, func_get_args() );
 282         }
 283
 284         public function selectRowCount(
 285                 $tables, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
 286         ) {
 287                 return $this->__call( __FUNCTION__, func_get_args() );
 288         }
 289
 290         public function fieldExists( $table, $field, $fname = __METHOD__ ) {
 291                 return $this->__call( __FUNCTION__, func_get_args() );
 292         }
 293
 294         public function indexExists( $table, $index, $fname = __METHOD__ ) {
 295                 return $this->__call( __FUNCTION__, func_get_args() );
 296         }
 297
 298         public function tableExists( $table, $fname = __METHOD__ ) {
 299                 return $this->__call( __FUNCTION__, func_get_args() );
 300         }
 301
 302         public function insert( $table, $a, $fname = __METHOD__, $options = [] ) {
 303                 return $this->__call( __FUNCTION__, func_get_args() );
 304         }
 305
 306         public function update( $table, $values, $conds, $fname = __METHOD__, $options = [] ) {
 307                 return $this->__call( __FUNCTION__, func_get_args() );
 308         }
 309
 310         public function makeList( $a, $mode = self::LIST_COMMA ) {
 311                 return $this->__call( __FUNCTION__, func_get_args() );
 312         }
 313
 314         public function makeWhereFrom2d( $data, $baseKey, $subKey ) {
 315                 return $this->__call( __FUNCTION__, func_get_args() );
 316         }
 317
 318         public function aggregateValue( $valuedata, $valuename = 'value' ) {
 319                 return $this->__call( __FUNCTION__, func_get_args() );
 320         }
 321
 322         public function bitNot( $field ) {
 323                 return $this->__call( __FUNCTION__, func_get_args() );
 324         }
 325
 326         public function bitAnd( $fieldLeft, $fieldRight ) {
 327                 return $this->__call( __FUNCTION__, func_get_args() );
 328         }
 329
 330         public function bitOr( $fieldLeft, $fieldRight ) {
 331                 return $this->__call( __FUNCTION__, func_get_args() );
 332         }
 333
 334         public function buildConcat( $stringList ) {
 335                 return $this->__call( __FUNCTION__, func_get_args() );
 336         }
 337
 338         public function buildGroupConcatField(
 339                 $delim, $table, $field, $conds = '', $join_conds = []
 340         ) {
 341                 return $this->__call( __FUNCTION__, func_get_args() );
 342         }
 343
 344         public function buildSubstring( $input, $startPosition, $length = null ) {
 345                 return $this->__call( __FUNCTION__, func_get_args() );
 346         }
 347
 348         public function buildStringCast( $field ) {
 349                 return $this->__call( __FUNCTION__, func_get_args() );
 350         }
 351
 352         public function buildIntegerCast( $field ) {
 353                 return $this->__call( __FUNCTION__, func_get_args() );
 354         }
 355
 356         public function buildSelectSubquery(
 357                 $table, $vars, $conds = '', $fname = __METHOD__,
 358                 $options = [], $join_conds = []
 359         ) {
 360                 return $this->__call( __FUNCTION__, func_get_args() );
 361         }
 362
 363         public function databasesAreIndependent() {
 364                 return $this->__call( __FUNCTION__, func_get_args() );
 365         }
 366
 367         public function selectDB( $db ) {
 368                 return $this->__call( __FUNCTION__, func_get_args() );
 369         }
 370
 371         public function getDBname() {
 372                 return $this->__call( __FUNCTION__, func_get_args() );
 373         }
 374
 375         public function getServer() {
 376                 return $this->__call( __FUNCTION__, func_get_args() );
 377         }
 378
 379         public function addQuotes( $s ) {
 380                 return $this->__call( __FUNCTION__, func_get_args() );
 381         }
 382
 383         public function buildLike() {
 384                 return $this->__call( __FUNCTION__, func_get_args() );
 385         }
 386
 387         public function anyChar() {
 388                 return $this->__call( __FUNCTION__, func_get_args() );
 389         }
 390
 391         public function anyString() {
 392                 return $this->__call( __FUNCTION__, func_get_args() );
 393         }
 394
 395         public function nextSequenceValue( $seqName ) {
 396                 return $this->__call( __FUNCTION__, func_get_args() );
 397         }
 398
 399         public function replace( $table, $uniqueIndexes, $rows, $fname = __METHOD__ ) {
 400                 return $this->__call( __FUNCTION__, func_get_args() );
 401         }
 402
 403         public function upsert(
 404                 $table, array $rows, array $uniqueIndexes, array $set, $fname = __METHOD__
 405         ) {
 406                 return $this->__call( __FUNCTION__, func_get_args() );
 407         }
 408
 409         public function deleteJoin(
 410                 $delTable, $joinTable, $delVar, $joinVar, $conds, $fname = __METHOD__
 411         ) {
 412                 return $this->__call( __FUNCTION__, func_get_args() );
 413         }
 414
 415         public function delete( $table, $conds, $fname = __METHOD__ ) {
 416                 return $this->__call( __FUNCTION__, func_get_args() );
 417         }
 418
 419         public function insertSelect(
 420                 $destTable, $srcTable, $varMap, $conds,
 421                 $fname = __METHOD__, $insertOptions = [], $selectOptions = [], $selectJoinConds = []
 422         ) {
 423                 return $this->__call( __FUNCTION__, func_get_args() );
 424         }
 425
 426         public function unionSupportsOrderAndLimit() {
 427                 return $this->__call( __FUNCTION__, func_get_args() );
 428         }
 429
 430         public function unionQueries( $sqls, $all ) {
 431                 return $this->__call( __FUNCTION__, func_get_args() );
 432         }
 433
 434         public function unionConditionPermutations(
 435                 $table, $vars, array $permute_conds, $extra_conds = '', $fname = __METHOD__,
 436                 $options = [], $join_conds = []
 437         ) {
 438                 return $this->__call( __FUNCTION__, func_get_args() );
 439         }
 440
 441         public function conditional( $cond, $trueVal, $falseVal ) {
 442                 return $this->__call( __FUNCTION__, func_get_args() );
 443         }
 444
 445         public function strreplace( $orig, $old, $new ) {
 446                 return $this->__call( __FUNCTION__, func_get_args() );
 447         }
 448
 449         public function getServerUptime() {
 450                 return $this->__call( __FUNCTION__, func_get_args() );
 451         }
 452
 453         public function wasDeadlock() {
 454                 return $this->__call( __FUNCTION__, func_get_args() );
 455         }
 456
 457         public function wasLockTimeout() {
 458                 return $this->__call( __FUNCTION__, func_get_args() );
 459         }
 460
 461         public function wasConnectionLoss() {
 462                 return $this->__call( __FUNCTION__, func_get_args() );
 463         }
 464
 465         public function wasReadOnlyError() {
 466                 return $this->__call( __FUNCTION__, func_get_args() );
 467         }
 468
 469         public function wasErrorReissuable() {
 470                 return $this->__call( __FUNCTION__, func_get_args() );
 471         }
 472
 473         public function masterPosWait( DBMasterPos $pos, $timeout ) {
 474                 return $this->__call( __FUNCTION__, func_get_args() );
 475         }
 476
 477         public function getReplicaPos() {
 478                 return $this->__call( __FUNCTION__, func_get_args() );
 479         }
 480
 481         public function getMasterPos() {
 482                 return $this->__call( __FUNCTION__, func_get_args() );
 483         }
 484
 485         public function serverIsReadOnly() {
 486                 return $this->__call( __FUNCTION__, func_get_args() );
 487         }
 488
 489         public function onTransactionResolution( callable $callback, $fname = __METHOD__ ) {
 490                 return $this->__call( __FUNCTION__, func_get_args() );
 491         }
 492
 493         public function onTransactionCommitOrIdle( callable $callback, $fname = __METHOD__ ) {
 494                 return $this->__call( __FUNCTION__, func_get_args() );
 495         }
 496
 497         public function onTransactionIdle( callable $callback, $fname = __METHOD__ ) {
 498                 return $this->__call( __FUNCTION__, func_get_args() );
 499         }
 500
 501         public function onTransactionPreCommitOrIdle( callable $callback, $fname = __METHOD__ ) {
 502                 return $this->__call( __FUNCTION__, func_get_args() );
 503         }
 504
 505         public function setTransactionListener( $name, callable $callback = null ) {
 506                 return $this->__call( __FUNCTION__, func_get_args() );
 507         }
 508
 509         public function startAtomic(
 510                 $fname = __METHOD__, $cancelable = IDatabase::ATOMIC_NOT_CANCELABLE
 511         ) {
 512                 return $this->__call( __FUNCTION__, func_get_args() );
 513         }
 514
 515         public function endAtomic( $fname = __METHOD__ ) {
 516                 return $this->__call( __FUNCTION__, func_get_args() );
 517         }
 518
 519         public function cancelAtomic( $fname = __METHOD__, AtomicSectionIdentifier $sectionId = null ) {
 520                 return $this->__call( __FUNCTION__, func_get_args() );
 521         }
 522
 523         public function doAtomicSection(
 524                 $fname, callable $callback, $cancelable = self::ATOMIC_NOT_CANCELABLE
 525         ) {
 526                 return $this->__call( __FUNCTION__, func_get_args() );
 527         }
 528
 529         public function begin( $fname = __METHOD__, $mode = IDatabase::TRANSACTION_EXPLICIT ) {
 530                 return $this->__call( __FUNCTION__, func_get_args() );
 531         }
 532
 533         public function commit( $fname = __METHOD__, $flush = '' ) {
 534                 return $this->__call( __FUNCTION__, func_get_args() );
 535         }
 536
 537         public function rollback( $fname = __METHOD__, $flush = '' ) {
 538                 return $this->__call( __FUNCTION__, func_get_args() );
 539         }
 540
 541         public function flushSnapshot( $fname = __METHOD__ ) {
 542                 return $this->__call( __FUNCTION__, func_get_args() );
 543         }
 544
 545         public function timestamp( $ts = 0 ) {
 546                 return $this->__call( __FUNCTION__, func_get_args() );
 547         }
 548
 549         public function timestampOrNull( $ts = null ) {
 550                 return $this->__call( __FUNCTION__, func_get_args() );
 551         }
 552
 553         public function ping( &$rtt = null ) {
 554                 return func_num_args()
 555                         ? $this->__call( __FUNCTION__, [ &$rtt ] )
 556                         : $this->__call( __FUNCTION__, [] ); // method cares about null vs missing
 557         }
 558
 559         public function getLag() {
 560                 return $this->__call( __FUNCTION__, func_get_args() );
 561         }
 562
 563         public function getSessionLagStatus() {
 564                 return $this->__call( __FUNCTION__, func_get_args() );
 565         }
 566
 567         public function maxListLen() {
 568                 return $this->__call( __FUNCTION__, func_get_args() );
 569         }
 570
 571         public function encodeBlob( $b ) {
 572                 return $this->__call( __FUNCTION__, func_get_args() );
 573         }
 574
 575         public function decodeBlob( $b ) {
 576                 return $this->__call( __FUNCTION__, func_get_args() );
 577         }
 578
 579         public function setSessionOptions( array $options ) {
 580                 return $this->__call( __FUNCTION__, func_get_args() );
 581         }
 582
 583         public function setSchemaVars( $vars ) {
 584                 return $this->__call( __FUNCTION__, func_get_args() );
 585         }
 586
 587         public function lockIsFree( $lockName, $method ) {
 588                 return $this->__call( __FUNCTION__, func_get_args() );
 589         }
 590
 591         public function lock( $lockName, $method, $timeout = 5 ) {
 592                 return $this->__call( __FUNCTION__, func_get_args() );
 593         }
 594
 595         public function unlock( $lockName, $method ) {
 596                 return $this->__call( __FUNCTION__, func_get_args() );
 597         }
 598
 599         public function getScopedLockAndFlush( $lockKey, $fname, $timeout ) {
 600                 return $this->__call( __FUNCTION__, func_get_args() );
 601         }
 602
 603         public function namedLocksEnqueue() {
 604                 return $this->__call( __FUNCTION__, func_get_args() );
 605         }
 606
 607         public function getInfinity() {
 608                 return $this->__call( __FUNCTION__, func_get_args() );
 609         }
 610
 611         public function encodeExpiry( $expiry ) {
 612                 return $this->__call( __FUNCTION__, func_get_args() );
 613         }
 614
 615         public function decodeExpiry( $expiry, $format = TS_MW ) {
 616                 return $this->__call( __FUNCTION__, func_get_args() );
 617         }
 618
 619         public function setBigSelects( $value = true ) {
 620                 return $this->__call( __FUNCTION__, func_get_args() );
 621         }
 622
 623         public function isReadOnly() {
 624                 return $this->__call( __FUNCTION__, func_get_args() );
 625         }
 626
 627         public function setTableAliases( array $aliases ) {
 628                 return $this->__call( __FUNCTION__, func_get_args() );
 629         }
 630
 631         public function setIndexAliases( array $aliases ) {
 632                 return $this->__call( __FUNCTION__, func_get_args() );
 633         }
 634
 635         /**
 636          * Clean up the connection when out of scope
 637          */
 638         function __destruct() {
 639                 if ( $this->conn ) {
 640                         $this->lb->reuseConnection( $this->conn );
 641                 }
 642         }
 643 }
 644
 645 /**
 646  * @since 1.22
 647  * @deprecated since 1.29
 648  */
 649 class_alias( DBConnRef::class, 'DBConnRef' );