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 fetchObject( $res ) {
 182                 return $this->__call( __FUNCTION__, func_get_args() );
 183         }
 184
 185         public function fetchRow( $res ) {
 186                 return $this->__call( __FUNCTION__, func_get_args() );
 187         }
 188
 189         public function numRows( $res ) {
 190                 return $this->__call( __FUNCTION__, func_get_args() );
 191         }
 192
 193         public function numFields( $res ) {
 194                 return $this->__call( __FUNCTION__, func_get_args() );
 195         }
 196
 197         public function fieldName( $res, $n ) {
 198                 return $this->__call( __FUNCTION__, func_get_args() );
 199         }
 200
 201         public function insertId() {
 202                 return $this->__call( __FUNCTION__, func_get_args() );
 203         }
 204
 205         public function dataSeek( $res, $row ) {
 206                 return $this->__call( __FUNCTION__, func_get_args() );
 207         }
 208
 209         public function lastErrno() {
 210                 return $this->__call( __FUNCTION__, func_get_args() );
 211         }
 212
 213         public function lastError() {
 214                 return $this->__call( __FUNCTION__, func_get_args() );
 215         }
 216
 217         public function affectedRows() {
 218                 return $this->__call( __FUNCTION__, func_get_args() );
 219         }
 220
 221         public function getSoftwareLink() {
 222                 return $this->__call( __FUNCTION__, func_get_args() );
 223         }
 224
 225         public function getServerVersion() {
 226                 return $this->__call( __FUNCTION__, func_get_args() );
 227         }
 228
 229         public function close() {
 230                 return $this->__call( __FUNCTION__, func_get_args() );
 231         }
 232
 233         public function query( $sql, $fname = __METHOD__, $tempIgnore = false ) {
 234                 return $this->__call( __FUNCTION__, func_get_args() );
 235         }
 236
 237         public function freeResult( $res ) {
 238                 return $this->__call( __FUNCTION__, func_get_args() );
 239         }
 240
 241         public function selectField(
 242                 $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
 243         ) {
 244                 return $this->__call( __FUNCTION__, func_get_args() );
 245         }
 246
 247         public function selectFieldValues(
 248                 $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
 249         ) {
 250                 return $this->__call( __FUNCTION__, func_get_args() );
 251         }
 252
 253         public function select(
 254                 $table, $vars, $conds = '', $fname = __METHOD__,
 255                 $options = [], $join_conds = []
 256         ) {
 257                 return $this->__call( __FUNCTION__, func_get_args() );
 258         }
 259
 260         public function selectSQLText(
 261                 $table, $vars, $conds = '', $fname = __METHOD__,
 262                 $options = [], $join_conds = []
 263         ) {
 264                 return $this->__call( __FUNCTION__, func_get_args() );
 265         }
 266
 267         public function selectRow(
 268                 $table, $vars, $conds, $fname = __METHOD__,
 269                 $options = [], $join_conds = []
 270         ) {
 271                 return $this->__call( __FUNCTION__, func_get_args() );
 272         }
 273
 274         public function estimateRowCount(
 275                 $table, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
 276         ) {
 277                 return $this->__call( __FUNCTION__, func_get_args() );
 278         }
 279
 280         public function selectRowCount(
 281                 $tables, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
 282         ) {
 283                 return $this->__call( __FUNCTION__, func_get_args() );
 284         }
 285
 286         public function lockForUpdate(
 287                 $table, $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
 288         ) {
 289                 return $this->__call( __FUNCTION__, func_get_args() );
 290         }
 291
 292         public function fieldExists( $table, $field, $fname = __METHOD__ ) {
 293                 return $this->__call( __FUNCTION__, func_get_args() );
 294         }
 295
 296         public function indexExists( $table, $index, $fname = __METHOD__ ) {
 297                 return $this->__call( __FUNCTION__, func_get_args() );
 298         }
 299
 300         public function tableExists( $table, $fname = __METHOD__ ) {
 301                 return $this->__call( __FUNCTION__, func_get_args() );
 302         }
 303
 304         public function insert( $table, $a, $fname = __METHOD__, $options = [] ) {
 305                 return $this->__call( __FUNCTION__, func_get_args() );
 306         }
 307
 308         public function update( $table, $values, $conds, $fname = __METHOD__, $options = [] ) {
 309                 return $this->__call( __FUNCTION__, func_get_args() );
 310         }
 311
 312         public function makeList( $a, $mode = self::LIST_COMMA ) {
 313                 return $this->__call( __FUNCTION__, func_get_args() );
 314         }
 315
 316         public function makeWhereFrom2d( $data, $baseKey, $subKey ) {
 317                 return $this->__call( __FUNCTION__, func_get_args() );
 318         }
 319
 320         public function aggregateValue( $valuedata, $valuename = 'value' ) {
 321                 return $this->__call( __FUNCTION__, func_get_args() );
 322         }
 323
 324         public function bitNot( $field ) {
 325                 return $this->__call( __FUNCTION__, func_get_args() );
 326         }
 327
 328         public function bitAnd( $fieldLeft, $fieldRight ) {
 329                 return $this->__call( __FUNCTION__, func_get_args() );
 330         }
 331
 332         public function bitOr( $fieldLeft, $fieldRight ) {
 333                 return $this->__call( __FUNCTION__, func_get_args() );
 334         }
 335
 336         public function buildConcat( $stringList ) {
 337                 return $this->__call( __FUNCTION__, func_get_args() );
 338         }
 339
 340         public function buildGroupConcatField(
 341                 $delim, $table, $field, $conds = '', $join_conds = []
 342         ) {
 343                 return $this->__call( __FUNCTION__, func_get_args() );
 344         }
 345
 346         public function buildSubstring( $input, $startPosition, $length = null ) {
 347                 return $this->__call( __FUNCTION__, func_get_args() );
 348         }
 349
 350         public function buildStringCast( $field ) {
 351                 return $this->__call( __FUNCTION__, func_get_args() );
 352         }
 353
 354         public function buildIntegerCast( $field ) {
 355                 return $this->__call( __FUNCTION__, func_get_args() );
 356         }
 357
 358         public function buildSelectSubquery(
 359                 $table, $vars, $conds = '', $fname = __METHOD__,
 360                 $options = [], $join_conds = []
 361         ) {
 362                 return $this->__call( __FUNCTION__, func_get_args() );
 363         }
 364
 365         public function databasesAreIndependent() {
 366                 return $this->__call( __FUNCTION__, func_get_args() );
 367         }
 368
 369         public function selectDB( $db ) {
 370                 // Disallow things that might confuse the LoadBalancer tracking
 371                 throw new DBUnexpectedError( $this, "Database selection is disallowed to enable reuse." );
 372         }
 373
 374         public function getDBname() {
 375                 return $this->__call( __FUNCTION__, func_get_args() );
 376         }
 377
 378         public function getServer() {
 379                 return $this->__call( __FUNCTION__, func_get_args() );
 380         }
 381
 382         public function addQuotes( $s ) {
 383                 return $this->__call( __FUNCTION__, func_get_args() );
 384         }
 385
 386         public function buildLike() {
 387                 return $this->__call( __FUNCTION__, func_get_args() );
 388         }
 389
 390         public function anyChar() {
 391                 return $this->__call( __FUNCTION__, func_get_args() );
 392         }
 393
 394         public function anyString() {
 395                 return $this->__call( __FUNCTION__, func_get_args() );
 396         }
 397
 398         public function nextSequenceValue( $seqName ) {
 399                 return $this->__call( __FUNCTION__, func_get_args() );
 400         }
 401
 402         public function replace( $table, $uniqueIndexes, $rows, $fname = __METHOD__ ) {
 403                 return $this->__call( __FUNCTION__, func_get_args() );
 404         }
 405
 406         public function upsert(
 407                 $table, array $rows, array $uniqueIndexes, array $set, $fname = __METHOD__
 408         ) {
 409                 return $this->__call( __FUNCTION__, func_get_args() );
 410         }
 411
 412         public function deleteJoin(
 413                 $delTable, $joinTable, $delVar, $joinVar, $conds, $fname = __METHOD__
 414         ) {
 415                 return $this->__call( __FUNCTION__, func_get_args() );
 416         }
 417
 418         public function delete( $table, $conds, $fname = __METHOD__ ) {
 419                 return $this->__call( __FUNCTION__, func_get_args() );
 420         }
 421
 422         public function insertSelect(
 423                 $destTable, $srcTable, $varMap, $conds,
 424                 $fname = __METHOD__, $insertOptions = [], $selectOptions = [], $selectJoinConds = []
 425         ) {
 426                 return $this->__call( __FUNCTION__, func_get_args() );
 427         }
 428
 429         public function unionSupportsOrderAndLimit() {
 430                 return $this->__call( __FUNCTION__, func_get_args() );
 431         }
 432
 433         public function unionQueries( $sqls, $all ) {
 434                 return $this->__call( __FUNCTION__, func_get_args() );
 435         }
 436
 437         public function unionConditionPermutations(
 438                 $table, $vars, array $permute_conds, $extra_conds = '', $fname = __METHOD__,
 439                 $options = [], $join_conds = []
 440         ) {
 441                 return $this->__call( __FUNCTION__, func_get_args() );
 442         }
 443
 444         public function conditional( $cond, $trueVal, $falseVal ) {
 445                 return $this->__call( __FUNCTION__, func_get_args() );
 446         }
 447
 448         public function strreplace( $orig, $old, $new ) {
 449                 return $this->__call( __FUNCTION__, func_get_args() );
 450         }
 451
 452         public function getServerUptime() {
 453                 return $this->__call( __FUNCTION__, func_get_args() );
 454         }
 455
 456         public function wasDeadlock() {
 457                 return $this->__call( __FUNCTION__, func_get_args() );
 458         }
 459
 460         public function wasLockTimeout() {
 461                 return $this->__call( __FUNCTION__, func_get_args() );
 462         }
 463
 464         public function wasConnectionLoss() {
 465                 return $this->__call( __FUNCTION__, func_get_args() );
 466         }
 467
 468         public function wasReadOnlyError() {
 469                 return $this->__call( __FUNCTION__, func_get_args() );
 470         }
 471
 472         public function wasErrorReissuable() {
 473                 return $this->__call( __FUNCTION__, func_get_args() );
 474         }
 475
 476         public function masterPosWait( DBMasterPos $pos, $timeout ) {
 477                 return $this->__call( __FUNCTION__, func_get_args() );
 478         }
 479
 480         public function getReplicaPos() {
 481                 return $this->__call( __FUNCTION__, func_get_args() );
 482         }
 483
 484         public function getMasterPos() {
 485                 return $this->__call( __FUNCTION__, func_get_args() );
 486         }
 487
 488         public function serverIsReadOnly() {
 489                 return $this->__call( __FUNCTION__, func_get_args() );
 490         }
 491
 492         public function onTransactionResolution( callable $callback, $fname = __METHOD__ ) {
 493                 return $this->__call( __FUNCTION__, func_get_args() );
 494         }
 495
 496         public function onTransactionCommitOrIdle( callable $callback, $fname = __METHOD__ ) {
 497                 return $this->__call( __FUNCTION__, func_get_args() );
 498         }
 499
 500         public function onTransactionIdle( callable $callback, $fname = __METHOD__ ) {
 501                 return $this->__call( __FUNCTION__, func_get_args() );
 502         }
 503
 504         public function onTransactionPreCommitOrIdle( callable $callback, $fname = __METHOD__ ) {
 505                 return $this->__call( __FUNCTION__, func_get_args() );
 506         }
 507
 508         public function setTransactionListener( $name, callable $callback = null ) {
 509                 return $this->__call( __FUNCTION__, func_get_args() );
 510         }
 511
 512         public function startAtomic(
 513                 $fname = __METHOD__, $cancelable = IDatabase::ATOMIC_NOT_CANCELABLE
 514         ) {
 515                 return $this->__call( __FUNCTION__, func_get_args() );
 516         }
 517
 518         public function endAtomic( $fname = __METHOD__ ) {
 519                 return $this->__call( __FUNCTION__, func_get_args() );
 520         }
 521
 522         public function cancelAtomic( $fname = __METHOD__, AtomicSectionIdentifier $sectionId = null ) {
 523                 return $this->__call( __FUNCTION__, func_get_args() );
 524         }
 525
 526         public function doAtomicSection(
 527                 $fname, callable $callback, $cancelable = self::ATOMIC_NOT_CANCELABLE
 528         ) {
 529                 return $this->__call( __FUNCTION__, func_get_args() );
 530         }
 531
 532         public function begin( $fname = __METHOD__, $mode = IDatabase::TRANSACTION_EXPLICIT ) {
 533                 return $this->__call( __FUNCTION__, func_get_args() );
 534         }
 535
 536         public function commit( $fname = __METHOD__, $flush = '' ) {
 537                 return $this->__call( __FUNCTION__, func_get_args() );
 538         }
 539
 540         public function rollback( $fname = __METHOD__, $flush = '' ) {
 541                 return $this->__call( __FUNCTION__, func_get_args() );
 542         }
 543
 544         public function flushSnapshot( $fname = __METHOD__ ) {
 545                 return $this->__call( __FUNCTION__, func_get_args() );
 546         }
 547
 548         public function timestamp( $ts = 0 ) {
 549                 return $this->__call( __FUNCTION__, func_get_args() );
 550         }
 551
 552         public function timestampOrNull( $ts = null ) {
 553                 return $this->__call( __FUNCTION__, func_get_args() );
 554         }
 555
 556         public function ping( &$rtt = null ) {
 557                 return func_num_args()
 558                         ? $this->__call( __FUNCTION__, [ &$rtt ] )
 559                         : $this->__call( __FUNCTION__, [] ); // method cares about null vs missing
 560         }
 561
 562         public function getLag() {
 563                 return $this->__call( __FUNCTION__, func_get_args() );
 564         }
 565
 566         public function getSessionLagStatus() {
 567                 return $this->__call( __FUNCTION__, func_get_args() );
 568         }
 569
 570         public function maxListLen() {
 571                 return $this->__call( __FUNCTION__, func_get_args() );
 572         }
 573
 574         public function encodeBlob( $b ) {
 575                 return $this->__call( __FUNCTION__, func_get_args() );
 576         }
 577
 578         public function decodeBlob( $b ) {
 579                 return $this->__call( __FUNCTION__, func_get_args() );
 580         }
 581
 582         public function setSessionOptions( array $options ) {
 583                 return $this->__call( __FUNCTION__, func_get_args() );
 584         }
 585
 586         public function setSchemaVars( $vars ) {
 587                 return $this->__call( __FUNCTION__, func_get_args() );
 588         }
 589
 590         public function lockIsFree( $lockName, $method ) {
 591                 return $this->__call( __FUNCTION__, func_get_args() );
 592         }
 593
 594         public function lock( $lockName, $method, $timeout = 5 ) {
 595                 return $this->__call( __FUNCTION__, func_get_args() );
 596         }
 597
 598         public function unlock( $lockName, $method ) {
 599                 return $this->__call( __FUNCTION__, func_get_args() );
 600         }
 601
 602         public function getScopedLockAndFlush( $lockKey, $fname, $timeout ) {
 603                 return $this->__call( __FUNCTION__, func_get_args() );
 604         }
 605
 606         public function namedLocksEnqueue() {
 607                 return $this->__call( __FUNCTION__, func_get_args() );
 608         }
 609
 610         public function getInfinity() {
 611                 return $this->__call( __FUNCTION__, func_get_args() );
 612         }
 613
 614         public function encodeExpiry( $expiry ) {
 615                 return $this->__call( __FUNCTION__, func_get_args() );
 616         }
 617
 618         public function decodeExpiry( $expiry, $format = TS_MW ) {
 619                 return $this->__call( __FUNCTION__, func_get_args() );
 620         }
 621
 622         public function setBigSelects( $value = true ) {
 623                 return $this->__call( __FUNCTION__, func_get_args() );
 624         }
 625
 626         public function isReadOnly() {
 627                 return $this->__call( __FUNCTION__, func_get_args() );
 628         }
 629
 630         public function setTableAliases( array $aliases ) {
 631                 return $this->__call( __FUNCTION__, func_get_args() );
 632         }
 633
 634         public function setIndexAliases( array $aliases ) {
 635                 return $this->__call( __FUNCTION__, func_get_args() );
 636         }
 637
 638         /**
 639          * Clean up the connection when out of scope
 640          */
 641         function __destruct() {
 642                 if ( $this->conn ) {
 643                         $this->lb->reuseConnection( $this->conn );
 644                 }
 645         }
 646 }
 647
 648 /**
 649  * @since 1.22
 650  * @deprecated since 1.29
 651  */
 652 class_alias( DBConnRef::class, 'DBConnRef' );