includes/libs/rdbms/database/DBConnRef.php

   1 <?php
   2
   3 namespace Wikimedia\Rdbms;
   4
   5 use InvalidArgumentException;
   6
   7 /**
   8  * Helper class used for automatically marking an IDatabase connection as reusable (once it no
   9  * longer matters which DB domain is selected) and for deferring the actual network connection
  10  *
  11  * This uses an RAII-style pattern where calling code is expected to keep the returned reference
  12  * handle as a function variable that falls out of scope when no longer needed. This avoids the
  13  * need for matching reuseConnection() calls for every "return" statement as well as the tedious
  14  * use of try/finally.
  15  *
  16  * @par Example:
  17  * @code
  18  *     function getRowData() {
  19  *         $conn = $this->lb->getConnectedRef( DB_REPLICA );
  20  *         $row = $conn->select( ... );
  21  *         return $row ? (array)$row : false;
  22  *         // $conn falls out of scope and $this->lb->reuseConnection() gets called
  23  *     }
  24  * @endcode
  25  *
  26  * @ingroup Database
  27  * @since 1.22
  28  */
  29 class DBConnRef implements IDatabase {
  30         /** @var ILoadBalancer */
  31         private $lb;
  32         /** @var Database|null Live connection handle */
  33         private $conn;
  34         /** @var array|null N-tuple of (server index, group, DatabaseDomain|string) */
  35         private $params;
  36         /** @var int One of DB_MASTER/DB_REPLICA */
  37         private $role;
  38
  39         const FLD_INDEX = 0;
  40         const FLD_GROUP = 1;
  41         const FLD_DOMAIN = 2;
  42         const FLD_FLAGS = 3;
  43
  44         /**
  45          * @param ILoadBalancer $lb Connection manager for $conn
  46          * @param IDatabase|array $conn Database or (server index, query groups, domain, flags)
  47          * @param int $role The type of connection asked for; one of DB_MASTER/DB_REPLICA
  48          * @internal This method should not be called outside of LoadBalancer
  49          */
  50         public function __construct( ILoadBalancer $lb, $conn, $role ) {
  51                 $this->lb = $lb;
  52                 $this->role = $role;
  53                 if ( $conn instanceof IDatabase && !( $conn instanceof DBConnRef ) ) {
  54                         $this->conn = $conn; // live handle
  55                 } elseif ( is_array( $conn ) && count( $conn ) >= 4 && $conn[self::FLD_DOMAIN] !== false ) {
  56                         $this->params = $conn;
  57                 } else {
  58                         throw new InvalidArgumentException( "Missing lazy connection arguments." );
  59                 }
  60         }
  61
  62         function __call( $name, array $arguments ) {
  63                 if ( $this->conn === null ) {
  64                         list( $index, $groups, $wiki, $flags ) = $this->params;
  65                         $this->conn = $this->lb->getConnection( $index, $groups, $wiki, $flags );
  66                 }
  67
  68                 return $this->conn->$name( ...$arguments );
  69         }
  70
  71         /**
  72          * @return int DB_MASTER when this *requires* the master DB, otherwise DB_REPLICA
  73          * @since 1.33
  74          */
  75         public function getReferenceRole() {
  76                 return $this->role;
  77         }
  78
  79         public function getServerInfo() {
  80                 return $this->__call( __FUNCTION__, func_get_args() );
  81         }
  82
  83         public function bufferResults( $buffer = null ) {
  84                 return $this->__call( __FUNCTION__, func_get_args() );
  85         }
  86
  87         public function trxLevel() {
  88                 return $this->__call( __FUNCTION__, func_get_args() );
  89         }
  90
  91         public function trxTimestamp() {
  92                 return $this->__call( __FUNCTION__, func_get_args() );
  93         }
  94
  95         public function explicitTrxActive() {
  96                 return $this->__call( __FUNCTION__, func_get_args() );
  97         }
  98
  99         public function assertNoOpenTransactions() {
 100                 return $this->__call( __FUNCTION__, func_get_args() );
 101         }
 102
 103         public function tablePrefix( $prefix = null ) {
 104                 if ( $this->conn === null && $prefix === null ) {
 105                         $domain = DatabaseDomain::newFromId( $this->params[self::FLD_DOMAIN] );
 106                         // Avoid triggering a database connection
 107                         return $domain->getTablePrefix();
 108                 } elseif ( $this->conn !== null && $prefix === null ) {
 109                         // This will just return the prefix
 110                         return $this->__call( __FUNCTION__, func_get_args() );
 111                 }
 112                 // Disallow things that might confuse the LoadBalancer tracking
 113                 throw new DBUnexpectedError( $this, "Database selection is disallowed to enable reuse." );
 114         }
 115
 116         public function dbSchema( $schema = null ) {
 117                 if ( $this->conn === null && $schema === null ) {
 118                         $domain = DatabaseDomain::newFromId( $this->params[self::FLD_DOMAIN] );
 119                         // Avoid triggering a database connection
 120                         return $domain->getSchema();
 121                 } elseif ( $this->conn !== null && $schema === null ) {
 122                         // This will just return the schema
 123                         return $this->__call( __FUNCTION__, func_get_args() );
 124                 }
 125                 // Disallow things that might confuse the LoadBalancer tracking
 126                 throw new DBUnexpectedError( $this, "Database selection is disallowed to enable reuse." );
 127         }
 128
 129         public function getLBInfo( $name = null ) {
 130                 return $this->__call( __FUNCTION__, func_get_args() );
 131         }
 132
 133         public function setLBInfo( $nameOrArray, $value = null ) {
 134                 // Disallow things that might confuse the LoadBalancer tracking
 135                 throw new DBUnexpectedError( $this, "Changing LB info is disallowed to enable reuse." );
 136         }
 137
 138         public function setLazyMasterHandle( IDatabase $conn ) {
 139                 // Disallow things that might confuse the LoadBalancer tracking
 140                 throw new DBUnexpectedError( $this, "Database injection is disallowed to enable reuse." );
 141         }
 142
 143         public function implicitGroupby() {
 144                 return $this->__call( __FUNCTION__, func_get_args() );
 145         }
 146
 147         public function implicitOrderby() {
 148                 return $this->__call( __FUNCTION__, func_get_args() );
 149         }
 150
 151         public function lastQuery() {
 152                 return $this->__call( __FUNCTION__, func_get_args() );
 153         }
 154
 155         public function doneWrites() {
 156                 return $this->__call( __FUNCTION__, func_get_args() );
 157         }
 158
 159         public function lastDoneWrites() {
 160                 return $this->__call( __FUNCTION__, func_get_args() );
 161         }
 162
 163         public function writesPending() {
 164                 return $this->__call( __FUNCTION__, func_get_args() );
 165         }
 166
 167         public function preCommitCallbacksPending() {
 168                 return $this->__call( __FUNCTION__, func_get_args() );
 169         }
 170
 171         public function writesOrCallbacksPending() {
 172                 return $this->__call( __FUNCTION__, func_get_args() );
 173         }
 174
 175         public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL ) {
 176                 return $this->__call( __FUNCTION__, func_get_args() );
 177         }
 178
 179         public function pendingWriteCallers() {
 180                 return $this->__call( __FUNCTION__, func_get_args() );
 181         }
 182
 183         public function pendingWriteRowsAffected() {
 184                 return $this->__call( __FUNCTION__, func_get_args() );
 185         }
 186
 187         public function isOpen() {
 188                 return $this->__call( __FUNCTION__, func_get_args() );
 189         }
 190
 191         public function setFlag( $flag, $remember = self::REMEMBER_NOTHING ) {
 192                 return $this->__call( __FUNCTION__, func_get_args() );
 193         }
 194
 195         public function clearFlag( $flag, $remember = self::REMEMBER_NOTHING ) {
 196                 return $this->__call( __FUNCTION__, func_get_args() );
 197         }
 198
 199         public function restoreFlags( $state = self::RESTORE_PRIOR ) {
 200                 return $this->__call( __FUNCTION__, func_get_args() );
 201         }
 202
 203         public function getFlag( $flag ) {
 204                 return $this->__call( __FUNCTION__, func_get_args() );
 205         }
 206
 207         public function getProperty( $name ) {
 208                 return $this->__call( __FUNCTION__, func_get_args() );
 209         }
 210
 211         public function getDomainID() {
 212                 if ( $this->conn === null ) {
 213                         $domain = $this->params[self::FLD_DOMAIN];
 214                         // Avoid triggering a database connection
 215                         return $domain instanceof DatabaseDomain ? $domain->getId() : $domain;
 216                 }
 217
 218                 return $this->__call( __FUNCTION__, func_get_args() );
 219         }
 220
 221         /**
 222          * @codeCoverageIgnore
 223          */
 224         public function getWikiID() {
 225                 return $this->getDomainID();
 226         }
 227
 228         public function getType() {
 229                 if ( $this->conn === null ) {
 230                         // Avoid triggering a database connection
 231                         if ( $this->params[self::FLD_INDEX] === ILoadBalancer::DB_MASTER ) {
 232                                 $index = $this->lb->getWriterIndex();
 233                         } else {
 234                                 $index = $this->params[self::FLD_INDEX];
 235                         }
 236                         if ( $index >= 0 ) {
 237                                 // In theory, if $index is DB_REPLICA, the type could vary
 238                                 return $this->lb->getServerType( $index );
 239                         }
 240                 }
 241
 242                 return $this->__call( __FUNCTION__, func_get_args() );
 243         }
 244
 245         public function fetchObject( $res ) {
 246                 return $this->__call( __FUNCTION__, func_get_args() );
 247         }
 248
 249         public function fetchRow( $res ) {
 250                 return $this->__call( __FUNCTION__, func_get_args() );
 251         }
 252
 253         public function numRows( $res ) {
 254                 return $this->__call( __FUNCTION__, func_get_args() );
 255         }
 256
 257         public function numFields( $res ) {
 258                 return $this->__call( __FUNCTION__, func_get_args() );
 259         }
 260
 261         public function fieldName( $res, $n ) {
 262                 return $this->__call( __FUNCTION__, func_get_args() );
 263         }
 264
 265         public function insertId() {
 266                 return $this->__call( __FUNCTION__, func_get_args() );
 267         }
 268
 269         public function dataSeek( $res, $row ) {
 270                 return $this->__call( __FUNCTION__, func_get_args() );
 271         }
 272
 273         public function lastErrno() {
 274                 return $this->__call( __FUNCTION__, func_get_args() );
 275         }
 276
 277         public function lastError() {
 278                 return $this->__call( __FUNCTION__, func_get_args() );
 279         }
 280
 281         public function affectedRows() {
 282                 return $this->__call( __FUNCTION__, func_get_args() );
 283         }
 284
 285         public function getSoftwareLink() {
 286                 return $this->__call( __FUNCTION__, func_get_args() );
 287         }
 288
 289         public function getServerVersion() {
 290                 return $this->__call( __FUNCTION__, func_get_args() );
 291         }
 292
 293         public function close() {
 294                 throw new DBUnexpectedError( $this->conn, 'Cannot close shared connection.' );
 295         }
 296
 297         public function query( $sql, $fname = __METHOD__, $flags = 0 ) {
 298                 if ( $this->role !== ILoadBalancer::DB_MASTER ) {
 299                         $flags |= IDatabase::QUERY_REPLICA_ROLE;
 300                 }
 301
 302                 return $this->__call( __FUNCTION__, [ $sql, $fname, $flags ] );
 303         }
 304
 305         public function freeResult( $res ) {
 306                 return $this->__call( __FUNCTION__, func_get_args() );
 307         }
 308
 309         public function selectField(
 310                 $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
 311         ) {
 312                 return $this->__call( __FUNCTION__, func_get_args() );
 313         }
 314
 315         public function selectFieldValues(
 316                 $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
 317         ) {
 318                 return $this->__call( __FUNCTION__, func_get_args() );
 319         }
 320
 321         public function select(
 322                 $table, $vars, $conds = '', $fname = __METHOD__,
 323                 $options = [], $join_conds = []
 324         ) {
 325                 return $this->__call( __FUNCTION__, func_get_args() );
 326         }
 327
 328         public function selectSQLText(
 329                 $table, $vars, $conds = '', $fname = __METHOD__,
 330                 $options = [], $join_conds = []
 331         ) {
 332                 return $this->__call( __FUNCTION__, func_get_args() );
 333         }
 334
 335         public function limitResult( $sql, $limit, $offset = false ) {
 336                 return $this->__call( __FUNCTION__, func_get_args() );
 337         }
 338
 339         public function selectRow(
 340                 $table, $vars, $conds, $fname = __METHOD__,
 341                 $options = [], $join_conds = []
 342         ) {
 343                 return $this->__call( __FUNCTION__, func_get_args() );
 344         }
 345
 346         public function estimateRowCount(
 347                 $table, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
 348         ) {
 349                 return $this->__call( __FUNCTION__, func_get_args() );
 350         }
 351
 352         public function selectRowCount(
 353                 $tables, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
 354         ) {
 355                 return $this->__call( __FUNCTION__, func_get_args() );
 356         }
 357
 358         public function lockForUpdate(
 359                 $table, $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
 360         ) {
 361                 $this->assertRoleAllowsWrites();
 362
 363                 return $this->__call( __FUNCTION__, func_get_args() );
 364         }
 365
 366         public function fieldExists( $table, $field, $fname = __METHOD__ ) {
 367                 return $this->__call( __FUNCTION__, func_get_args() );
 368         }
 369
 370         public function indexExists( $table, $index, $fname = __METHOD__ ) {
 371                 return $this->__call( __FUNCTION__, func_get_args() );
 372         }
 373
 374         public function tableExists( $table, $fname = __METHOD__ ) {
 375                 return $this->__call( __FUNCTION__, func_get_args() );
 376         }
 377
 378         public function insert( $table, $a, $fname = __METHOD__, $options = [] ) {
 379                 $this->assertRoleAllowsWrites();
 380
 381                 return $this->__call( __FUNCTION__, func_get_args() );
 382         }
 383
 384         public function update( $table, $values, $conds, $fname = __METHOD__, $options = [] ) {
 385                 $this->assertRoleAllowsWrites();
 386
 387                 return $this->__call( __FUNCTION__, func_get_args() );
 388         }
 389
 390         public function makeList( $a, $mode = self::LIST_COMMA ) {
 391                 return $this->__call( __FUNCTION__, func_get_args() );
 392         }
 393
 394         public function makeWhereFrom2d( $data, $baseKey, $subKey ) {
 395                 return $this->__call( __FUNCTION__, func_get_args() );
 396         }
 397
 398         public function aggregateValue( $valuedata, $valuename = 'value' ) {
 399                 return $this->__call( __FUNCTION__, func_get_args() );
 400         }
 401
 402         public function bitNot( $field ) {
 403                 return $this->__call( __FUNCTION__, func_get_args() );
 404         }
 405
 406         public function bitAnd( $fieldLeft, $fieldRight ) {
 407                 return $this->__call( __FUNCTION__, func_get_args() );
 408         }
 409
 410         public function bitOr( $fieldLeft, $fieldRight ) {
 411                 return $this->__call( __FUNCTION__, func_get_args() );
 412         }
 413
 414         public function buildConcat( $stringList ) {
 415                 return $this->__call( __FUNCTION__, func_get_args() );
 416         }
 417
 418         public function buildGroupConcatField(
 419                 $delim, $table, $field, $conds = '', $join_conds = []
 420         ) {
 421                 return $this->__call( __FUNCTION__, func_get_args() );
 422         }
 423
 424         public function buildSubstring( $input, $startPosition, $length = null ) {
 425                 return $this->__call( __FUNCTION__, func_get_args() );
 426         }
 427
 428         public function buildStringCast( $field ) {
 429                 return $this->__call( __FUNCTION__, func_get_args() );
 430         }
 431
 432         public function buildIntegerCast( $field ) {
 433                 return $this->__call( __FUNCTION__, func_get_args() );
 434         }
 435
 436         public function buildSelectSubquery(
 437                 $table, $vars, $conds = '', $fname = __METHOD__,
 438                 $options = [], $join_conds = []
 439         ) {
 440                 return $this->__call( __FUNCTION__, func_get_args() );
 441         }
 442
 443         public function databasesAreIndependent() {
 444                 return $this->__call( __FUNCTION__, func_get_args() );
 445         }
 446
 447         public function selectDB( $db ) {
 448                 // Disallow things that might confuse the LoadBalancer tracking
 449                 throw new DBUnexpectedError( $this, "Database selection is disallowed to enable reuse." );
 450         }
 451
 452         public function selectDomain( $domain ) {
 453                 // Disallow things that might confuse the LoadBalancer tracking
 454                 throw new DBUnexpectedError( $this, "Database selection is disallowed to enable reuse." );
 455         }
 456
 457         public function getDBname() {
 458                 if ( $this->conn === null ) {
 459                         $domain = DatabaseDomain::newFromId( $this->params[self::FLD_DOMAIN] );
 460                         // Avoid triggering a database connection
 461                         return $domain->getDatabase();
 462                 }
 463
 464                 return $this->__call( __FUNCTION__, func_get_args() );
 465         }
 466
 467         public function getServer() {
 468                 return $this->__call( __FUNCTION__, func_get_args() );
 469         }
 470
 471         public function addQuotes( $s ) {
 472                 return $this->__call( __FUNCTION__, func_get_args() );
 473         }
 474
 475         public function addIdentifierQuotes( $s ) {
 476                 return $this->__call( __FUNCTION__, func_get_args() );
 477         }
 478
 479         public function buildLike( $param ) {
 480                 return $this->__call( __FUNCTION__, func_get_args() );
 481         }
 482
 483         public function anyChar() {
 484                 return $this->__call( __FUNCTION__, func_get_args() );
 485         }
 486
 487         public function anyString() {
 488                 return $this->__call( __FUNCTION__, func_get_args() );
 489         }
 490
 491         public function nextSequenceValue( $seqName ) {
 492                 $this->assertRoleAllowsWrites();
 493
 494                 return $this->__call( __FUNCTION__, func_get_args() );
 495         }
 496
 497         public function replace( $table, $uniqueIndexes, $rows, $fname = __METHOD__ ) {
 498                 $this->assertRoleAllowsWrites();
 499
 500                 return $this->__call( __FUNCTION__, func_get_args() );
 501         }
 502
 503         public function upsert(
 504                 $table, array $rows, $uniqueIndexes, array $set, $fname = __METHOD__
 505         ) {
 506                 $this->assertRoleAllowsWrites();
 507
 508                 return $this->__call( __FUNCTION__, func_get_args() );
 509         }
 510
 511         public function deleteJoin(
 512                 $delTable, $joinTable, $delVar, $joinVar, $conds, $fname = __METHOD__
 513         ) {
 514                 $this->assertRoleAllowsWrites();
 515
 516                 return $this->__call( __FUNCTION__, func_get_args() );
 517         }
 518
 519         public function delete( $table, $conds, $fname = __METHOD__ ) {
 520                 $this->assertRoleAllowsWrites();
 521
 522                 return $this->__call( __FUNCTION__, func_get_args() );
 523         }
 524
 525         public function insertSelect(
 526                 $destTable, $srcTable, $varMap, $conds,
 527                 $fname = __METHOD__, $insertOptions = [], $selectOptions = [], $selectJoinConds = []
 528         ) {
 529                 $this->assertRoleAllowsWrites();
 530
 531                 return $this->__call( __FUNCTION__, func_get_args() );
 532         }
 533
 534         public function unionSupportsOrderAndLimit() {
 535                 return $this->__call( __FUNCTION__, func_get_args() );
 536         }
 537
 538         public function unionQueries( $sqls, $all ) {
 539                 return $this->__call( __FUNCTION__, func_get_args() );
 540         }
 541
 542         public function unionConditionPermutations(
 543                 $table, $vars, array $permute_conds, $extra_conds = '', $fname = __METHOD__,
 544                 $options = [], $join_conds = []
 545         ) {
 546                 return $this->__call( __FUNCTION__, func_get_args() );
 547         }
 548
 549         public function conditional( $cond, $trueVal, $falseVal ) {
 550                 return $this->__call( __FUNCTION__, func_get_args() );
 551         }
 552
 553         public function strreplace( $orig, $old, $new ) {
 554                 return $this->__call( __FUNCTION__, func_get_args() );
 555         }
 556
 557         public function getServerUptime() {
 558                 return $this->__call( __FUNCTION__, func_get_args() );
 559         }
 560
 561         public function wasDeadlock() {
 562                 return $this->__call( __FUNCTION__, func_get_args() );
 563         }
 564
 565         public function wasLockTimeout() {
 566                 return $this->__call( __FUNCTION__, func_get_args() );
 567         }
 568
 569         public function wasConnectionLoss() {
 570                 return $this->__call( __FUNCTION__, func_get_args() );
 571         }
 572
 573         public function wasReadOnlyError() {
 574                 return $this->__call( __FUNCTION__, func_get_args() );
 575         }
 576
 577         public function wasErrorReissuable() {
 578                 return $this->__call( __FUNCTION__, func_get_args() );
 579         }
 580
 581         public function masterPosWait( DBMasterPos $pos, $timeout ) {
 582                 return $this->__call( __FUNCTION__, func_get_args() );
 583         }
 584
 585         public function getReplicaPos() {
 586                 return $this->__call( __FUNCTION__, func_get_args() );
 587         }
 588
 589         public function getMasterPos() {
 590                 return $this->__call( __FUNCTION__, func_get_args() );
 591         }
 592
 593         public function serverIsReadOnly() {
 594                 return $this->__call( __FUNCTION__, func_get_args() );
 595         }
 596
 597         public function onTransactionResolution( callable $callback, $fname = __METHOD__ ) {
 598                 // DB_REPLICA role: caller might want to refresh cache after a REPEATABLE-READ snapshot
 599                 return $this->__call( __FUNCTION__, func_get_args() );
 600         }
 601
 602         public function onTransactionCommitOrIdle( callable $callback, $fname = __METHOD__ ) {
 603                 // DB_REPLICA role: caller might want to refresh cache after a REPEATABLE-READ snapshot
 604                 return $this->__call( __FUNCTION__, func_get_args() );
 605         }
 606
 607         public function onTransactionIdle( callable $callback, $fname = __METHOD__ ) {
 608                 return $this->onTransactionCommitOrIdle( $callback, $fname );
 609         }
 610
 611         public function onTransactionPreCommitOrIdle( callable $callback, $fname = __METHOD__ ) {
 612                 // DB_REPLICA role: caller might want to refresh cache after a cache mutex is released
 613                 return $this->__call( __FUNCTION__, func_get_args() );
 614         }
 615
 616         public function onAtomicSectionCancel( callable $callback, $fname = __METHOD__ ) {
 617                 return $this->__call( __FUNCTION__, func_get_args() );
 618         }
 619
 620         public function setTransactionListener( $name, callable $callback = null ) {
 621                 return $this->__call( __FUNCTION__, func_get_args() );
 622         }
 623
 624         public function startAtomic(
 625                 $fname = __METHOD__, $cancelable = IDatabase::ATOMIC_NOT_CANCELABLE
 626         ) {
 627                 // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot
 628                 return $this->__call( __FUNCTION__, func_get_args() );
 629         }
 630
 631         public function endAtomic( $fname = __METHOD__ ) {
 632                 // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot
 633                 return $this->__call( __FUNCTION__, func_get_args() );
 634         }
 635
 636         public function cancelAtomic( $fname = __METHOD__, AtomicSectionIdentifier $sectionId = null ) {
 637                 // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot
 638                 return $this->__call( __FUNCTION__, func_get_args() );
 639         }
 640
 641         public function doAtomicSection(
 642                 $fname, callable $callback, $cancelable = self::ATOMIC_NOT_CANCELABLE
 643         ) {
 644                 // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot
 645                 return $this->__call( __FUNCTION__, func_get_args() );
 646         }
 647
 648         public function begin( $fname = __METHOD__, $mode = IDatabase::TRANSACTION_EXPLICIT ) {
 649                 return $this->__call( __FUNCTION__, func_get_args() );
 650         }
 651
 652         public function commit( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) {
 653                 return $this->__call( __FUNCTION__, func_get_args() );
 654         }
 655
 656         public function rollback( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) {
 657                 return $this->__call( __FUNCTION__, func_get_args() );
 658         }
 659
 660         public function flushSnapshot( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) {
 661                 return $this->__call( __FUNCTION__, func_get_args() );
 662         }
 663
 664         public function timestamp( $ts = 0 ) {
 665                 return $this->__call( __FUNCTION__, func_get_args() );
 666         }
 667
 668         public function timestampOrNull( $ts = null ) {
 669                 return $this->__call( __FUNCTION__, func_get_args() );
 670         }
 671
 672         public function ping( &$rtt = null ) {
 673                 return func_num_args()
 674                         ? $this->__call( __FUNCTION__, [ &$rtt ] )
 675                         : $this->__call( __FUNCTION__, [] ); // method cares about null vs missing
 676         }
 677
 678         public function getLag() {
 679                 return $this->__call( __FUNCTION__, func_get_args() );
 680         }
 681
 682         public function getSessionLagStatus() {
 683                 return $this->__call( __FUNCTION__, func_get_args() );
 684         }
 685
 686         public function maxListLen() {
 687                 return $this->__call( __FUNCTION__, func_get_args() );
 688         }
 689
 690         public function encodeBlob( $b ) {
 691                 return $this->__call( __FUNCTION__, func_get_args() );
 692         }
 693
 694         public function decodeBlob( $b ) {
 695                 return $this->__call( __FUNCTION__, func_get_args() );
 696         }
 697
 698         public function setSessionOptions( array $options ) {
 699                 return $this->__call( __FUNCTION__, func_get_args() );
 700         }
 701
 702         public function setSchemaVars( $vars ) {
 703                 return $this->__call( __FUNCTION__, func_get_args() );
 704         }
 705
 706         public function lockIsFree( $lockName, $method ) {
 707                 $this->assertRoleAllowsWrites();
 708
 709                 return $this->__call( __FUNCTION__, func_get_args() );
 710         }
 711
 712         public function lock( $lockName, $method, $timeout = 5 ) {
 713                 $this->assertRoleAllowsWrites();
 714
 715                 return $this->__call( __FUNCTION__, func_get_args() );
 716         }
 717
 718         public function unlock( $lockName, $method ) {
 719                 $this->assertRoleAllowsWrites();
 720
 721                 return $this->__call( __FUNCTION__, func_get_args() );
 722         }
 723
 724         public function getScopedLockAndFlush( $lockKey, $fname, $timeout ) {
 725                 $this->assertRoleAllowsWrites();
 726
 727                 return $this->__call( __FUNCTION__, func_get_args() );
 728         }
 729
 730         public function namedLocksEnqueue() {
 731                 return $this->__call( __FUNCTION__, func_get_args() );
 732         }
 733
 734         public function getInfinity() {
 735                 return $this->__call( __FUNCTION__, func_get_args() );
 736         }
 737
 738         public function encodeExpiry( $expiry ) {
 739                 return $this->__call( __FUNCTION__, func_get_args() );
 740         }
 741
 742         public function decodeExpiry( $expiry, $format = TS_MW ) {
 743                 return $this->__call( __FUNCTION__, func_get_args() );
 744         }
 745
 746         public function setBigSelects( $value = true ) {
 747                 return $this->__call( __FUNCTION__, func_get_args() );
 748         }
 749
 750         public function isReadOnly() {
 751                 return $this->__call( __FUNCTION__, func_get_args() );
 752         }
 753
 754         public function setTableAliases( array $aliases ) {
 755                 return $this->__call( __FUNCTION__, func_get_args() );
 756         }
 757
 758         public function setIndexAliases( array $aliases ) {
 759                 return $this->__call( __FUNCTION__, func_get_args() );
 760         }
 761
 762         public function __toString() {
 763                 if ( $this->conn === null ) {
 764                         // spl_object_id is PHP >= 7.2
 765                         $id = function_exists( 'spl_object_id' )
 766                                 ? spl_object_id( $this )
 767                                 : spl_object_hash( $this );
 768
 769                         return $this->getType() . ' object #' . $id;
 770                 }
 771
 772                 return $this->__call( __FUNCTION__, func_get_args() );
 773         }
 774
 775         /**
 776          * Error out if the role is not DB_MASTER
 777          *
 778          * Note that the underlying connection may or may not itself be read-only.
 779          * It could even be to a writable master (both server-side and to the application).
 780          * This error is meant for the case when a DB_REPLICA handle was requested but a
 781          * a write was attempted on that handle regardless.
 782          *
 783          * In configurations where the master DB has some generic read load or is the only server,
 784          * DB_MASTER/DB_REPLICA will sometimes (or always) use the same connection to the master DB.
 785          * This does not effect the role of DBConnRef instances.
 786          * @throws DBReadOnlyRoleError
 787          */
 788         protected function assertRoleAllowsWrites() {
 789                 // DB_MASTER is "prima facie" writable
 790                 if ( $this->role !== ILoadBalancer::DB_MASTER ) {
 791                         throw new DBReadOnlyRoleError( $this->conn, "Cannot write with role DB_REPLICA" );
 792                 }
 793         }
 794
 795         /**
 796          * Clean up the connection when out of scope
 797          */
 798         function __destruct() {
 799                 if ( $this->conn ) {
 800                         $this->lb->reuseConnection( $this->conn );
 801                 }
 802         }
 803 }
 804
 805 /**
 806  * @since 1.22
 807  * @deprecated since 1.29
 808  */
 809 class_alias( DBConnRef::class, 'DBConnRef' );