3 namespace Wikimedia\Rdbms
;
5 use InvalidArgumentException
;
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
14 class DBConnRef
implements IDatabase
{
15 /** @var ILoadBalancer */
17 /** @var Database|null Live connection handle */
19 /** @var array|null N-tuple of (server index, group, DatabaseDomain|string) */
21 /** @var int One of DB_MASTER/DB_REPLICA */
30 * @param ILoadBalancer $lb Connection manager for $conn
31 * @param Database|array $conn Database or (server index, query groups, domain, flags)
32 * @param int $role The type of connection asked for; one of DB_MASTER/DB_REPLICA
33 * @internal This method should not be called outside of LoadBalancer
35 public function __construct( ILoadBalancer
$lb, $conn, $role ) {
38 if ( $conn instanceof Database
) {
39 $this->conn
= $conn; // live handle
40 } elseif ( is_array( $conn ) && count( $conn ) >= 4 && $conn[self
::FLD_DOMAIN
] !== false ) {
41 $this->params
= $conn;
43 throw new InvalidArgumentException( "Missing lazy connection arguments." );
47 function __call( $name, array $arguments ) {
48 if ( $this->conn
=== null ) {
49 list( $index, $groups, $wiki, $flags ) = $this->params
;
50 $this->conn
= $this->lb
->getConnection( $index, $groups, $wiki, $flags );
53 return $this->conn
->$name( ...$arguments );
57 * @return int DB_MASTER when this *requires* the master DB, otherwise DB_REPLICA
60 public function getReferenceRole() {
64 public function getServerInfo() {
65 return $this->__call( __FUNCTION__
, func_get_args() );
68 public function bufferResults( $buffer = null ) {
69 return $this->__call( __FUNCTION__
, func_get_args() );
72 public function trxLevel() {
73 return $this->__call( __FUNCTION__
, func_get_args() );
76 public function trxTimestamp() {
77 return $this->__call( __FUNCTION__
, func_get_args() );
80 public function explicitTrxActive() {
81 return $this->__call( __FUNCTION__
, func_get_args() );
84 public function assertNoOpenTransactions() {
85 return $this->__call( __FUNCTION__
, func_get_args() );
88 public function tablePrefix( $prefix = null ) {
89 if ( $this->conn
=== null && $prefix === null ) {
90 $domain = DatabaseDomain
::newFromId( $this->params
[self
::FLD_DOMAIN
] );
91 // Avoid triggering a database connection
92 return $domain->getTablePrefix();
93 } elseif ( $this->conn
!== null && $prefix === null ) {
94 // This will just return the prefix
95 return $this->__call( __FUNCTION__
, func_get_args() );
97 // Disallow things that might confuse the LoadBalancer tracking
98 throw new DBUnexpectedError( $this, "Database selection is disallowed to enable reuse." );
101 public function dbSchema( $schema = null ) {
102 if ( $this->conn
=== null && $schema === null ) {
103 $domain = DatabaseDomain
::newFromId( $this->params
[self
::FLD_DOMAIN
] );
104 // Avoid triggering a database connection
105 return $domain->getSchema();
106 } elseif ( $this->conn
!== null && $schema === null ) {
107 // This will just return the schema
108 return $this->__call( __FUNCTION__
, func_get_args() );
110 // Disallow things that might confuse the LoadBalancer tracking
111 throw new DBUnexpectedError( $this, "Database selection is disallowed to enable reuse." );
114 public function getLBInfo( $name = null ) {
115 return $this->__call( __FUNCTION__
, func_get_args() );
118 public function setLBInfo( $name, $value = null ) {
119 // Disallow things that might confuse the LoadBalancer tracking
120 throw new DBUnexpectedError( $this, "Changing LB info is disallowed to enable reuse." );
123 public function setLazyMasterHandle( IDatabase
$conn ) {
124 // Disallow things that might confuse the LoadBalancer tracking
125 throw new DBUnexpectedError( $this, "Database injection is disallowed to enable reuse." );
128 public function implicitGroupby() {
129 return $this->__call( __FUNCTION__
, func_get_args() );
132 public function implicitOrderby() {
133 return $this->__call( __FUNCTION__
, func_get_args() );
136 public function lastQuery() {
137 return $this->__call( __FUNCTION__
, func_get_args() );
140 public function doneWrites() {
141 return $this->__call( __FUNCTION__
, func_get_args() );
144 public function lastDoneWrites() {
145 return $this->__call( __FUNCTION__
, func_get_args() );
148 public function writesPending() {
149 return $this->__call( __FUNCTION__
, func_get_args() );
152 public function preCommitCallbacksPending() {
153 return $this->__call( __FUNCTION__
, func_get_args() );
156 public function writesOrCallbacksPending() {
157 return $this->__call( __FUNCTION__
, func_get_args() );
160 public function pendingWriteQueryDuration( $type = self
::ESTIMATE_TOTAL
) {
161 return $this->__call( __FUNCTION__
, func_get_args() );
164 public function pendingWriteCallers() {
165 return $this->__call( __FUNCTION__
, func_get_args() );
168 public function pendingWriteRowsAffected() {
169 return $this->__call( __FUNCTION__
, func_get_args() );
172 public function isOpen() {
173 return $this->__call( __FUNCTION__
, func_get_args() );
176 public function setFlag( $flag, $remember = self
::REMEMBER_NOTHING
) {
177 return $this->__call( __FUNCTION__
, func_get_args() );
180 public function clearFlag( $flag, $remember = self
::REMEMBER_NOTHING
) {
181 return $this->__call( __FUNCTION__
, func_get_args() );
184 public function restoreFlags( $state = self
::RESTORE_PRIOR
) {
185 return $this->__call( __FUNCTION__
, func_get_args() );
188 public function getFlag( $flag ) {
189 return $this->__call( __FUNCTION__
, func_get_args() );
192 public function getProperty( $name ) {
193 return $this->__call( __FUNCTION__
, func_get_args() );
196 public function getDomainID() {
197 if ( $this->conn
=== null ) {
198 $domain = $this->params
[self
::FLD_DOMAIN
];
199 // Avoid triggering a database connection
200 return $domain instanceof DatabaseDomain ?
$domain->getId() : $domain;
203 return $this->__call( __FUNCTION__
, func_get_args() );
207 * @codeCoverageIgnore
209 public function getWikiID() {
210 return $this->getDomainID();
213 public function getType() {
214 return $this->__call( __FUNCTION__
, func_get_args() );
217 public function fetchObject( $res ) {
218 return $this->__call( __FUNCTION__
, func_get_args() );
221 public function fetchRow( $res ) {
222 return $this->__call( __FUNCTION__
, func_get_args() );
225 public function numRows( $res ) {
226 return $this->__call( __FUNCTION__
, func_get_args() );
229 public function numFields( $res ) {
230 return $this->__call( __FUNCTION__
, func_get_args() );
233 public function fieldName( $res, $n ) {
234 return $this->__call( __FUNCTION__
, func_get_args() );
237 public function insertId() {
238 return $this->__call( __FUNCTION__
, func_get_args() );
241 public function dataSeek( $res, $row ) {
242 return $this->__call( __FUNCTION__
, func_get_args() );
245 public function lastErrno() {
246 return $this->__call( __FUNCTION__
, func_get_args() );
249 public function lastError() {
250 return $this->__call( __FUNCTION__
, func_get_args() );
253 public function affectedRows() {
254 return $this->__call( __FUNCTION__
, func_get_args() );
257 public function getSoftwareLink() {
258 return $this->__call( __FUNCTION__
, func_get_args() );
261 public function getServerVersion() {
262 return $this->__call( __FUNCTION__
, func_get_args() );
265 public function close() {
266 throw new DBUnexpectedError( $this->conn
, 'Cannot close shared connection.' );
269 public function query( $sql, $fname = __METHOD__
, $flags = 0 ) {
270 if ( $this->role
!== ILoadBalancer
::DB_MASTER
) {
271 $flags |
= IDatabase
::QUERY_REPLICA_ROLE
;
274 return $this->__call( __FUNCTION__
, [ $sql, $fname, $flags ] );
277 public function freeResult( $res ) {
278 return $this->__call( __FUNCTION__
, func_get_args() );
281 public function selectField(
282 $table, $var, $cond = '', $fname = __METHOD__
, $options = [], $join_conds = []
284 return $this->__call( __FUNCTION__
, func_get_args() );
287 public function selectFieldValues(
288 $table, $var, $cond = '', $fname = __METHOD__
, $options = [], $join_conds = []
290 return $this->__call( __FUNCTION__
, func_get_args() );
293 public function select(
294 $table, $vars, $conds = '', $fname = __METHOD__
,
295 $options = [], $join_conds = []
297 return $this->__call( __FUNCTION__
, func_get_args() );
300 public function selectSQLText(
301 $table, $vars, $conds = '', $fname = __METHOD__
,
302 $options = [], $join_conds = []
304 return $this->__call( __FUNCTION__
, func_get_args() );
307 public function limitResult( $sql, $limit, $offset = false ) {
308 return $this->__call( __FUNCTION__
, func_get_args() );
311 public function selectRow(
312 $table, $vars, $conds, $fname = __METHOD__
,
313 $options = [], $join_conds = []
315 return $this->__call( __FUNCTION__
, func_get_args() );
318 public function estimateRowCount(
319 $table, $vars = '*', $conds = '', $fname = __METHOD__
, $options = [], $join_conds = []
321 return $this->__call( __FUNCTION__
, func_get_args() );
324 public function selectRowCount(
325 $tables, $vars = '*', $conds = '', $fname = __METHOD__
, $options = [], $join_conds = []
327 return $this->__call( __FUNCTION__
, func_get_args() );
330 public function lockForUpdate(
331 $table, $conds = '', $fname = __METHOD__
, $options = [], $join_conds = []
333 $this->assertRoleAllowsWrites();
335 return $this->__call( __FUNCTION__
, func_get_args() );
338 public function fieldExists( $table, $field, $fname = __METHOD__
) {
339 return $this->__call( __FUNCTION__
, func_get_args() );
342 public function indexExists( $table, $index, $fname = __METHOD__
) {
343 return $this->__call( __FUNCTION__
, func_get_args() );
346 public function tableExists( $table, $fname = __METHOD__
) {
347 return $this->__call( __FUNCTION__
, func_get_args() );
350 public function insert( $table, $a, $fname = __METHOD__
, $options = [] ) {
351 $this->assertRoleAllowsWrites();
353 return $this->__call( __FUNCTION__
, func_get_args() );
356 public function update( $table, $values, $conds, $fname = __METHOD__
, $options = [] ) {
357 $this->assertRoleAllowsWrites();
359 return $this->__call( __FUNCTION__
, func_get_args() );
362 public function makeList( $a, $mode = self
::LIST_COMMA
) {
363 return $this->__call( __FUNCTION__
, func_get_args() );
366 public function makeWhereFrom2d( $data, $baseKey, $subKey ) {
367 return $this->__call( __FUNCTION__
, func_get_args() );
370 public function aggregateValue( $valuedata, $valuename = 'value' ) {
371 return $this->__call( __FUNCTION__
, func_get_args() );
374 public function bitNot( $field ) {
375 return $this->__call( __FUNCTION__
, func_get_args() );
378 public function bitAnd( $fieldLeft, $fieldRight ) {
379 return $this->__call( __FUNCTION__
, func_get_args() );
382 public function bitOr( $fieldLeft, $fieldRight ) {
383 return $this->__call( __FUNCTION__
, func_get_args() );
386 public function buildConcat( $stringList ) {
387 return $this->__call( __FUNCTION__
, func_get_args() );
390 public function buildGroupConcatField(
391 $delim, $table, $field, $conds = '', $join_conds = []
393 return $this->__call( __FUNCTION__
, func_get_args() );
396 public function buildSubstring( $input, $startPosition, $length = null ) {
397 return $this->__call( __FUNCTION__
, func_get_args() );
400 public function buildStringCast( $field ) {
401 return $this->__call( __FUNCTION__
, func_get_args() );
404 public function buildIntegerCast( $field ) {
405 return $this->__call( __FUNCTION__
, func_get_args() );
408 public function buildSelectSubquery(
409 $table, $vars, $conds = '', $fname = __METHOD__
,
410 $options = [], $join_conds = []
412 return $this->__call( __FUNCTION__
, func_get_args() );
415 public function databasesAreIndependent() {
416 return $this->__call( __FUNCTION__
, func_get_args() );
419 public function selectDB( $db ) {
420 // Disallow things that might confuse the LoadBalancer tracking
421 throw new DBUnexpectedError( $this, "Database selection is disallowed to enable reuse." );
424 public function selectDomain( $domain ) {
425 // Disallow things that might confuse the LoadBalancer tracking
426 throw new DBUnexpectedError( $this, "Database selection is disallowed to enable reuse." );
429 public function getDBname() {
430 if ( $this->conn
=== null ) {
431 $domain = DatabaseDomain
::newFromId( $this->params
[self
::FLD_DOMAIN
] );
432 // Avoid triggering a database connection
433 return $domain->getDatabase();
436 return $this->__call( __FUNCTION__
, func_get_args() );
439 public function getServer() {
440 return $this->__call( __FUNCTION__
, func_get_args() );
443 public function addQuotes( $s ) {
444 return $this->__call( __FUNCTION__
, func_get_args() );
447 public function addIdentifierQuotes( $s ) {
448 return $this->__call( __FUNCTION__
, func_get_args() );
451 public function buildLike() {
452 return $this->__call( __FUNCTION__
, func_get_args() );
455 public function anyChar() {
456 return $this->__call( __FUNCTION__
, func_get_args() );
459 public function anyString() {
460 return $this->__call( __FUNCTION__
, func_get_args() );
463 public function nextSequenceValue( $seqName ) {
464 $this->assertRoleAllowsWrites();
466 return $this->__call( __FUNCTION__
, func_get_args() );
469 public function replace( $table, $uniqueIndexes, $rows, $fname = __METHOD__
) {
470 $this->assertRoleAllowsWrites();
472 return $this->__call( __FUNCTION__
, func_get_args() );
475 public function upsert(
476 $table, array $rows, $uniqueIndexes, array $set, $fname = __METHOD__
478 $this->assertRoleAllowsWrites();
480 return $this->__call( __FUNCTION__
, func_get_args() );
483 public function deleteJoin(
484 $delTable, $joinTable, $delVar, $joinVar, $conds, $fname = __METHOD__
486 $this->assertRoleAllowsWrites();
488 return $this->__call( __FUNCTION__
, func_get_args() );
491 public function delete( $table, $conds, $fname = __METHOD__
) {
492 $this->assertRoleAllowsWrites();
494 return $this->__call( __FUNCTION__
, func_get_args() );
497 public function insertSelect(
498 $destTable, $srcTable, $varMap, $conds,
499 $fname = __METHOD__
, $insertOptions = [], $selectOptions = [], $selectJoinConds = []
501 $this->assertRoleAllowsWrites();
503 return $this->__call( __FUNCTION__
, func_get_args() );
506 public function unionSupportsOrderAndLimit() {
507 return $this->__call( __FUNCTION__
, func_get_args() );
510 public function unionQueries( $sqls, $all ) {
511 return $this->__call( __FUNCTION__
, func_get_args() );
514 public function unionConditionPermutations(
515 $table, $vars, array $permute_conds, $extra_conds = '', $fname = __METHOD__
,
516 $options = [], $join_conds = []
518 return $this->__call( __FUNCTION__
, func_get_args() );
521 public function conditional( $cond, $trueVal, $falseVal ) {
522 return $this->__call( __FUNCTION__
, func_get_args() );
525 public function strreplace( $orig, $old, $new ) {
526 return $this->__call( __FUNCTION__
, func_get_args() );
529 public function getServerUptime() {
530 return $this->__call( __FUNCTION__
, func_get_args() );
533 public function wasDeadlock() {
534 return $this->__call( __FUNCTION__
, func_get_args() );
537 public function wasLockTimeout() {
538 return $this->__call( __FUNCTION__
, func_get_args() );
541 public function wasConnectionLoss() {
542 return $this->__call( __FUNCTION__
, func_get_args() );
545 public function wasReadOnlyError() {
546 return $this->__call( __FUNCTION__
, func_get_args() );
549 public function wasErrorReissuable() {
550 return $this->__call( __FUNCTION__
, func_get_args() );
553 public function masterPosWait( DBMasterPos
$pos, $timeout ) {
554 return $this->__call( __FUNCTION__
, func_get_args() );
557 public function getReplicaPos() {
558 return $this->__call( __FUNCTION__
, func_get_args() );
561 public function getMasterPos() {
562 return $this->__call( __FUNCTION__
, func_get_args() );
565 public function serverIsReadOnly() {
566 return $this->__call( __FUNCTION__
, func_get_args() );
569 public function onTransactionResolution( callable
$callback, $fname = __METHOD__
) {
570 // DB_REPLICA role: caller might want to refresh cache after a REPEATABLE-READ snapshot
571 return $this->__call( __FUNCTION__
, func_get_args() );
574 public function onTransactionCommitOrIdle( callable
$callback, $fname = __METHOD__
) {
575 // DB_REPLICA role: caller might want to refresh cache after a REPEATABLE-READ snapshot
576 return $this->__call( __FUNCTION__
, func_get_args() );
579 public function onTransactionIdle( callable
$callback, $fname = __METHOD__
) {
580 return $this->onTransactionCommitOrIdle( $callback, $fname );
583 public function onTransactionPreCommitOrIdle( callable
$callback, $fname = __METHOD__
) {
584 // DB_REPLICA role: caller might want to refresh cache after a cache mutex is released
585 return $this->__call( __FUNCTION__
, func_get_args() );
588 public function setTransactionListener( $name, callable
$callback = null ) {
589 return $this->__call( __FUNCTION__
, func_get_args() );
592 public function startAtomic(
593 $fname = __METHOD__
, $cancelable = IDatabase
::ATOMIC_NOT_CANCELABLE
595 // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot
596 return $this->__call( __FUNCTION__
, func_get_args() );
599 public function endAtomic( $fname = __METHOD__
) {
600 // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot
601 return $this->__call( __FUNCTION__
, func_get_args() );
604 public function cancelAtomic( $fname = __METHOD__
, AtomicSectionIdentifier
$sectionId = null ) {
605 // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot
606 return $this->__call( __FUNCTION__
, func_get_args() );
609 public function doAtomicSection(
610 $fname, callable
$callback, $cancelable = self
::ATOMIC_NOT_CANCELABLE
612 // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot
613 return $this->__call( __FUNCTION__
, func_get_args() );
616 public function begin( $fname = __METHOD__
, $mode = IDatabase
::TRANSACTION_EXPLICIT
) {
617 return $this->__call( __FUNCTION__
, func_get_args() );
620 public function commit( $fname = __METHOD__
, $flush = '' ) {
621 return $this->__call( __FUNCTION__
, func_get_args() );
624 public function rollback( $fname = __METHOD__
, $flush = '' ) {
625 return $this->__call( __FUNCTION__
, func_get_args() );
628 public function flushSnapshot( $fname = __METHOD__
) {
629 return $this->__call( __FUNCTION__
, func_get_args() );
632 public function timestamp( $ts = 0 ) {
633 return $this->__call( __FUNCTION__
, func_get_args() );
636 public function timestampOrNull( $ts = null ) {
637 return $this->__call( __FUNCTION__
, func_get_args() );
640 public function ping( &$rtt = null ) {
641 return func_num_args()
642 ?
$this->__call( __FUNCTION__
, [ &$rtt ] )
643 : $this->__call( __FUNCTION__
, [] ); // method cares about null vs missing
646 public function getLag() {
647 return $this->__call( __FUNCTION__
, func_get_args() );
650 public function getSessionLagStatus() {
651 return $this->__call( __FUNCTION__
, func_get_args() );
654 public function maxListLen() {
655 return $this->__call( __FUNCTION__
, func_get_args() );
658 public function encodeBlob( $b ) {
659 return $this->__call( __FUNCTION__
, func_get_args() );
662 public function decodeBlob( $b ) {
663 return $this->__call( __FUNCTION__
, func_get_args() );
666 public function setSessionOptions( array $options ) {
667 return $this->__call( __FUNCTION__
, func_get_args() );
670 public function setSchemaVars( $vars ) {
671 return $this->__call( __FUNCTION__
, func_get_args() );
674 public function lockIsFree( $lockName, $method ) {
675 $this->assertRoleAllowsWrites();
677 return $this->__call( __FUNCTION__
, func_get_args() );
680 public function lock( $lockName, $method, $timeout = 5 ) {
681 $this->assertRoleAllowsWrites();
683 return $this->__call( __FUNCTION__
, func_get_args() );
686 public function unlock( $lockName, $method ) {
687 $this->assertRoleAllowsWrites();
689 return $this->__call( __FUNCTION__
, func_get_args() );
692 public function getScopedLockAndFlush( $lockKey, $fname, $timeout ) {
693 $this->assertRoleAllowsWrites();
695 return $this->__call( __FUNCTION__
, func_get_args() );
698 public function namedLocksEnqueue() {
699 return $this->__call( __FUNCTION__
, func_get_args() );
702 public function getInfinity() {
703 return $this->__call( __FUNCTION__
, func_get_args() );
706 public function encodeExpiry( $expiry ) {
707 return $this->__call( __FUNCTION__
, func_get_args() );
710 public function decodeExpiry( $expiry, $format = TS_MW
) {
711 return $this->__call( __FUNCTION__
, func_get_args() );
714 public function setBigSelects( $value = true ) {
715 return $this->__call( __FUNCTION__
, func_get_args() );
718 public function isReadOnly() {
719 return $this->__call( __FUNCTION__
, func_get_args() );
722 public function setTableAliases( array $aliases ) {
723 return $this->__call( __FUNCTION__
, func_get_args() );
726 public function setIndexAliases( array $aliases ) {
727 return $this->__call( __FUNCTION__
, func_get_args() );
731 * Error out if the role is not DB_MASTER
733 * Note that the underlying connection may or may not itself be read-only.
734 * It could even be to a writable master (both server-side and to the application).
735 * This error is meant for the case when a DB_REPLICA handle was requested but a
736 * a write was attempted on that handle regardless.
738 * In configurations where the master DB has some generic read load or is the only server,
739 * DB_MASTER/DB_REPLICA will sometimes (or always) use the same connection to the master DB.
740 * This does not effect the role of DBConnRef instances.
741 * @throws DBReadOnlyRoleError
743 protected function assertRoleAllowsWrites() {
744 // DB_MASTER is "prima facie" writable
745 if ( $this->role
!== ILoadBalancer
::DB_MASTER
) {
746 throw new DBReadOnlyRoleError( $this->conn
, "Cannot write with role DB_REPLICA" );
751 * Clean up the connection when out of scope
753 function __destruct() {
755 $this->lb
->reuseConnection( $this->conn
);
762 * @deprecated since 1.29
764 class_alias( DBConnRef
::class, 'DBConnRef' );