MediaWiki  master
Database.php
Go to the documentation of this file.
1 <?php
26 namespace Wikimedia\Rdbms;
27 
34 use BagOStuff;
35 use HashBagOStuff;
36 use LogicException;
39 use Exception;
41 use Throwable;
42 
49 abstract class Database implements IDatabase, IMaintainableDatabase, LoggerAwareInterface {
51  protected $srvCache;
53  protected $connLogger;
55  protected $queryLogger;
57  protected $errorLogger;
59  protected $deprecationLogger;
61  protected $profiler;
63  protected $trxProfiler;
64 
66  protected $currentDomain;
67 
69  protected $conn;
70 
73 
75  protected $server;
77  protected $user;
79  protected $password;
81  protected $cliMode;
83  protected $agent;
85  protected $topologyRole;
89  protected $connectionParams;
94 
96  protected $flags;
98  protected $lbInfo = [];
100  protected $delimiter = ';';
102  protected $tableAliases = [];
104  protected $indexAliases = [];
106  protected $schemaVars;
107 
109  private $htmlErrors;
111  private $priorFlags = [];
112 
114  protected $sessionNamedLocks = [];
116  protected $sessionTempTables = [];
117 
119  private $trxShortId = '';
121  private $trxStatus = self::STATUS_TRX_NONE;
127  private $trxTimestamp = null;
129  private $trxReplicaLag = null;
131  private $trxFname = null;
133  private $trxDoneWrites = false;
135  private $trxAutomatic = false;
137  private $trxAtomicCounter = 0;
139  private $trxAtomicLevels = [];
141  private $trxAutomaticAtomic = false;
143  private $trxWriteCallers = [];
145  private $trxWriteDuration = 0.0;
147  private $trxWriteQueryCount = 0;
151  private $trxWriteAdjDuration = 0.0;
155  private $trxIdleCallbacks = [];
162  private $trxEndCallbacks = [];
168  private $trxEndCallbacksSuppressed = false;
169 
171  protected $affectedRowCount;
172 
174  private $lastPing = 0.0;
176  private $lastQuery = '';
178  private $lastWriteTime = false;
180  private $lastPhpError = false;
182  private $lastRoundTripEstimate = 0.0;
183 
185  private $ownerId;
186 
188  const ATTR_DB_IS_FILE = 'db-is-file';
190  const ATTR_DB_LEVEL_LOCKING = 'db-level-locking';
192  const ATTR_SCHEMAS_AS_TABLE_GROUPS = 'supports-schemas';
193 
195  const NEW_UNCONNECTED = 0;
197  const NEW_CONNECTED = 1;
198 
200  const STATUS_TRX_ERROR = 1;
202  const STATUS_TRX_OK = 2;
204  const STATUS_TRX_NONE = 3;
205 
207  private static $NOT_APPLICABLE = 'n/a';
209  private static $SAVEPOINT_PREFIX = 'wikimedia_rdbms_atomic';
210 
212  private static $TEMP_NORMAL = 1;
214  private static $TEMP_PSEUDO_PERMANENT = 2;
215 
217  private static $DEADLOCK_TRIES = 4;
219  private static $DEADLOCK_DELAY_MIN = 500000;
221  private static $DEADLOCK_DELAY_MAX = 1500000;
222 
224  private static $PING_TTL = 1.0;
226  private static $PING_QUERY = 'SELECT 1 AS ping';
227 
229  private static $TINY_WRITE_SEC = 0.010;
231  private static $SLOW_WRITE_SEC = 0.500;
233  private static $SMALL_WRITE_ROWS = 100;
234 
236  protected static $MUTABLE_FLAGS = [
237  'DBO_DEBUG',
238  'DBO_NOBUFFER',
239  'DBO_TRX',
240  'DBO_DDLMODE',
241  ];
243  protected static $DBO_MUTABLE = (
245  );
246 
251  public function __construct( array $params ) {
252  $this->connectionParams = [
253  'host' => strlen( $params['host'] ) ? $params['host'] : null,
254  'user' => strlen( $params['user'] ) ? $params['user'] : null,
255  'dbname' => strlen( $params['dbname'] ) ? $params['dbname'] : null,
256  'schema' => strlen( $params['schema'] ) ? $params['schema'] : null,
257  'password' => is_string( $params['password'] ) ? $params['password'] : null,
258  'tablePrefix' => (string)$params['tablePrefix']
259  ];
260 
261  $this->lbInfo = $params['lbInfo'] ?? [];
262  $this->lazyMasterHandle = $params['lazyMasterHandle'] ?? null;
263  $this->connectionVariables = $params['variables'] ?? [];
264 
265  $this->flags = (int)$params['flags'];
266  $this->cliMode = (bool)$params['cliMode'];
267  $this->agent = (string)$params['agent'];
268  $this->topologyRole = (string)$params['topologyRole'];
269  $this->topologyRootMaster = (string)$params['topologicalMaster'];
270  $this->nonNativeInsertSelectBatchSize = $params['nonNativeInsertSelectBatchSize'] ?? 10000;
271 
272  $this->srvCache = $params['srvCache'];
273  $this->profiler = is_callable( $params['profiler'] ) ? $params['profiler'] : null;
274  $this->trxProfiler = $params['trxProfiler'];
275  $this->connLogger = $params['connLogger'];
276  $this->queryLogger = $params['queryLogger'];
277  $this->errorLogger = $params['errorLogger'];
278  $this->deprecationLogger = $params['deprecationLogger'];
279 
280  // Set initial dummy domain until open() sets the final DB/prefix
281  $this->currentDomain = new DatabaseDomain(
282  $params['dbname'] != '' ? $params['dbname'] : null,
283  $params['schema'] != '' ? $params['schema'] : null,
284  $params['tablePrefix']
285  );
286 
287  $this->ownerId = $params['ownerId'] ?? null;
288  }
289 
298  final public function initConnection() {
299  if ( $this->isOpen() ) {
300  throw new LogicException( __METHOD__ . ': already connected' );
301  }
302  // Establish the connection
303  $this->doInitConnection();
304  }
305 
312  protected function doInitConnection() {
313  $this->open(
314  $this->connectionParams['host'],
315  $this->connectionParams['user'],
316  $this->connectionParams['password'],
317  $this->connectionParams['dbname'],
318  $this->connectionParams['schema'],
319  $this->connectionParams['tablePrefix']
320  );
321  }
322 
334  abstract protected function open( $server, $user, $password, $dbName, $schema, $tablePrefix );
335 
389  final public static function factory( $type, $params = [], $connect = self::NEW_CONNECTED ) {
390  $class = self::getClass( $type, $params['driver'] ?? null );
391 
392  if ( class_exists( $class ) && is_subclass_of( $class, IDatabase::class ) ) {
393  $params += [
394  // Default configuration
395  'host' => null,
396  'user' => null,
397  'password' => null,
398  'dbname' => null,
399  'schema' => null,
400  'tablePrefix' => '',
401  'flags' => 0,
402  'variables' => [],
403  'lbInfo' => [],
404  'cliMode' => ( PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg' ),
405  'agent' => basename( $_SERVER['SCRIPT_NAME'] ) . '@' . gethostname(),
406  'ownerId' => null,
407  'topologyRole' => null,
408  'topologicalMaster' => null,
409  // Objects and callbacks
410  'lazyMasterHandle' => $params['lazyMasterHandle'] ?? null,
411  'srvCache' => $params['srvCache'] ?? new HashBagOStuff(),
412  'profiler' => $params['profiler'] ?? null,
413  'trxProfiler' => $params['trxProfiler'] ?? new TransactionProfiler(),
414  'connLogger' => $params['connLogger'] ?? new NullLogger(),
415  'queryLogger' => $params['queryLogger'] ?? new NullLogger(),
416  'errorLogger' => $params['errorLogger'] ?? function ( Exception $e ) {
417  trigger_error( get_class( $e ) . ': ' . $e->getMessage(), E_USER_WARNING );
418  },
419  'deprecationLogger' => $params['deprecationLogger'] ?? function ( $msg ) {
420  trigger_error( $msg, E_USER_DEPRECATED );
421  }
422  ];
423 
425  $conn = new $class( $params );
426  if ( $connect === self::NEW_CONNECTED ) {
427  $conn->initConnection();
428  }
429  } else {
430  $conn = null;
431  }
432 
433  return $conn;
434  }
435 
443  final public static function attributesFromType( $dbType, $driver = null ) {
444  static $defaults = [
445  self::ATTR_DB_IS_FILE => false,
446  self::ATTR_DB_LEVEL_LOCKING => false,
447  self::ATTR_SCHEMAS_AS_TABLE_GROUPS => false
448  ];
449 
450  $class = self::getClass( $dbType, $driver );
451 
452  return call_user_func( [ $class, 'getAttributes' ] ) + $defaults;
453  }
454 
461  private static function getClass( $dbType, $driver = null ) {
462  // For database types with built-in support, the below maps type to IDatabase
463  // implementations. For types with multiple driver implementations (PHP extensions),
464  // an array can be used, keyed by extension name. In case of an array, the
465  // optional 'driver' parameter can be used to force a specific driver. Otherwise,
466  // we auto-detect the first available driver. For types without built-in support,
467  // an class named "Database<Type>" us used, eg. DatabaseFoo for type 'foo'.
468  static $builtinTypes = [
469  'mysql' => [ 'mysqli' => DatabaseMysqli::class ],
470  'sqlite' => DatabaseSqlite::class,
471  'postgres' => DatabasePostgres::class,
472  ];
473 
474  $dbType = strtolower( $dbType );
475  $class = false;
476 
477  if ( isset( $builtinTypes[$dbType] ) ) {
478  $possibleDrivers = $builtinTypes[$dbType];
479  if ( is_string( $possibleDrivers ) ) {
480  $class = $possibleDrivers;
481  } elseif ( (string)$driver !== '' ) {
482  if ( !isset( $possibleDrivers[$driver] ) ) {
483  throw new InvalidArgumentException( __METHOD__ .
484  " type '$dbType' does not support driver '{$driver}'" );
485  }
486 
487  $class = $possibleDrivers[$driver];
488  } else {
489  foreach ( $possibleDrivers as $posDriver => $possibleClass ) {
490  if ( extension_loaded( $posDriver ) ) {
491  $class = $possibleClass;
492  break;
493  }
494  }
495  }
496  } else {
497  $class = 'Database' . ucfirst( $dbType );
498  }
499 
500  if ( $class === false ) {
501  throw new InvalidArgumentException( __METHOD__ .
502  " no viable database extension found for type '$dbType'" );
503  }
504 
505  return $class;
506  }
507 
512  protected static function getAttributes() {
513  return [];
514  }
515 
523  public function setLogger( LoggerInterface $logger ) {
524  $this->queryLogger = $logger;
525  }
526 
527  public function getServerInfo() {
528  return $this->getServerVersion();
529  }
530 
531  public function getTopologyRole() {
532  return $this->topologyRole;
533  }
534 
535  public function getTopologyRootMaster() {
537  }
538 
546  public function bufferResults( $buffer = null ) {
547  return true;
548  }
549 
550  final public function trxLevel() {
551  return ( $this->trxShortId != '' ) ? 1 : 0;
552  }
553 
554  public function trxTimestamp() {
555  return $this->trxLevel() ? $this->trxTimestamp : null;
556  }
557 
562  public function trxStatus() {
563  return $this->trxStatus;
564  }
565 
566  public function tablePrefix( $prefix = null ) {
567  $old = $this->currentDomain->getTablePrefix();
568  if ( $prefix !== null ) {
569  $this->currentDomain = new DatabaseDomain(
570  $this->currentDomain->getDatabase(),
571  $this->currentDomain->getSchema(),
572  $prefix
573  );
574  }
575 
576  return $old;
577  }
578 
579  public function dbSchema( $schema = null ) {
580  if ( strlen( $schema ) && $this->getDBname() === null ) {
581  throw new DBUnexpectedError( $this, "Cannot set schema to '$schema'; no database set" );
582  }
583 
584  $old = $this->currentDomain->getSchema();
585  if ( $schema !== null ) {
586  $this->currentDomain = new DatabaseDomain(
587  $this->currentDomain->getDatabase(),
588  // DatabaseDomain uses null for unspecified schemas
589  strlen( $schema ) ? $schema : null,
590  $this->currentDomain->getTablePrefix()
591  );
592  }
593 
594  return (string)$old;
595  }
596 
600  protected function relationSchemaQualifier() {
601  return $this->dbSchema();
602  }
603 
604  public function getLBInfo( $name = null ) {
605  if ( is_null( $name ) ) {
606  return $this->lbInfo;
607  }
608 
609  if ( array_key_exists( $name, $this->lbInfo ) ) {
610  return $this->lbInfo[$name];
611  }
612 
613  return null;
614  }
615 
616  public function setLBInfo( $nameOrArray, $value = null ) {
617  if ( is_array( $nameOrArray ) ) {
618  $this->lbInfo = $nameOrArray;
619  } elseif ( is_string( $nameOrArray ) ) {
620  if ( $value !== null ) {
621  $this->lbInfo[$nameOrArray] = $value;
622  } else {
623  unset( $this->lbInfo[$nameOrArray] );
624  }
625  } else {
626  throw new InvalidArgumentException( "Got non-string key" );
627  }
628  }
629 
636  protected function getLazyMasterHandle() {
638  }
639 
640  public function implicitOrderby() {
641  return true;
642  }
643 
644  public function lastQuery() {
645  return $this->lastQuery;
646  }
647 
648  public function lastDoneWrites() {
649  return $this->lastWriteTime ?: false;
650  }
651 
652  public function writesPending() {
653  return $this->trxLevel() && $this->trxDoneWrites;
654  }
655 
656  public function writesOrCallbacksPending() {
657  return $this->trxLevel() && (
658  $this->trxDoneWrites ||
659  $this->trxIdleCallbacks ||
660  $this->trxPreCommitCallbacks ||
661  $this->trxEndCallbacks ||
663  );
664  }
665 
666  public function preCommitCallbacksPending() {
667  return $this->trxLevel() && $this->trxPreCommitCallbacks;
668  }
669 
673  final protected function getTransactionRoundId() {
674  // If transaction round participation is enabled, see if one is active
675  if ( $this->getFlag( self::DBO_TRX ) ) {
676  $id = $this->getLBInfo( self::LB_TRX_ROUND_ID );
677 
678  return is_string( $id ) ? $id : null;
679  }
680 
681  return null;
682  }
683 
684  public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL ) {
685  if ( !$this->trxLevel() ) {
686  return false;
687  } elseif ( !$this->trxDoneWrites ) {
688  return 0.0;
689  }
690 
691  switch ( $type ) {
692  case self::ESTIMATE_DB_APPLY:
693  return $this->pingAndCalculateLastTrxApplyTime();
694  default: // everything
696  }
697  }
698 
702  private function pingAndCalculateLastTrxApplyTime() {
703  $this->ping( $rtt );
704 
705  $rttAdjTotal = $this->trxWriteAdjQueryCount * $rtt;
706  $applyTime = max( $this->trxWriteAdjDuration - $rttAdjTotal, 0 );
707  // For omitted queries, make them count as something at least
708  $omitted = $this->trxWriteQueryCount - $this->trxWriteAdjQueryCount;
709  $applyTime += self::$TINY_WRITE_SEC * $omitted;
710 
711  return $applyTime;
712  }
713 
714  public function pendingWriteCallers() {
715  return $this->trxLevel() ? $this->trxWriteCallers : [];
716  }
717 
718  public function pendingWriteRowsAffected() {
720  }
721 
730  public function pendingWriteAndCallbackCallers() {
731  $fnames = $this->pendingWriteCallers();
732  foreach ( [
733  $this->trxIdleCallbacks,
734  $this->trxPreCommitCallbacks,
735  $this->trxEndCallbacks,
736  $this->trxSectionCancelCallbacks
737  ] as $callbacks ) {
738  foreach ( $callbacks as $callback ) {
739  $fnames[] = $callback[1];
740  }
741  }
742 
743  return $fnames;
744  }
745 
749  private function flatAtomicSectionList() {
750  return array_reduce( $this->trxAtomicLevels, function ( $accum, $v ) {
751  return $accum === null ? $v[0] : "$accum, " . $v[0];
752  } );
753  }
754 
755  public function isOpen() {
756  return (bool)$this->conn;
757  }
758 
759  public function setFlag( $flag, $remember = self::REMEMBER_NOTHING ) {
760  if ( $flag & ~static::$DBO_MUTABLE ) {
761  throw new DBUnexpectedError(
762  $this,
763  "Got $flag (allowed: " . implode( ', ', static::$MUTABLE_FLAGS ) . ')'
764  );
765  }
766 
767  if ( $remember === self::REMEMBER_PRIOR ) {
768  array_push( $this->priorFlags, $this->flags );
769  }
770 
771  $this->flags |= $flag;
772  }
773 
774  public function clearFlag( $flag, $remember = self::REMEMBER_NOTHING ) {
775  if ( $flag & ~static::$DBO_MUTABLE ) {
776  throw new DBUnexpectedError(
777  $this,
778  "Got $flag (allowed: " . implode( ', ', static::$MUTABLE_FLAGS ) . ')'
779  );
780  }
781 
782  if ( $remember === self::REMEMBER_PRIOR ) {
783  array_push( $this->priorFlags, $this->flags );
784  }
785 
786  $this->flags &= ~$flag;
787  }
788 
789  public function restoreFlags( $state = self::RESTORE_PRIOR ) {
790  if ( !$this->priorFlags ) {
791  return;
792  }
793 
794  if ( $state === self::RESTORE_INITIAL ) {
795  $this->flags = reset( $this->priorFlags );
796  $this->priorFlags = [];
797  } else {
798  $this->flags = array_pop( $this->priorFlags );
799  }
800  }
801 
802  public function getFlag( $flag ) {
803  return ( ( $this->flags & $flag ) === $flag );
804  }
805 
806  public function getDomainID() {
807  return $this->currentDomain->getId();
808  }
809 
817  abstract function indexInfo( $table, $index, $fname = __METHOD__ );
818 
825  abstract function strencode( $s );
826 
830  protected function installErrorHandler() {
831  $this->lastPhpError = false;
832  $this->htmlErrors = ini_set( 'html_errors', '0' );
833  set_error_handler( [ $this, 'connectionErrorLogger' ] );
834  }
835 
841  protected function restoreErrorHandler() {
842  restore_error_handler();
843  if ( $this->htmlErrors !== false ) {
844  ini_set( 'html_errors', $this->htmlErrors );
845  }
846 
847  return $this->getLastPHPError();
848  }
849 
853  protected function getLastPHPError() {
854  if ( $this->lastPhpError ) {
855  $error = preg_replace( '!\[<a.*</a>\]!', '', $this->lastPhpError );
856  $error = preg_replace( '!^.*?:\s?(.*)$!', '$1', $error );
857 
858  return $error;
859  }
860 
861  return false;
862  }
863 
871  public function connectionErrorLogger( $errno, $errstr ) {
872  $this->lastPhpError = $errstr;
873  }
874 
881  protected function getLogContext( array $extras = [] ) {
882  return array_merge(
883  [
884  'db_server' => $this->server,
885  'db_name' => $this->getDBname(),
886  'db_user' => $this->user,
887  ],
888  $extras
889  );
890  }
891 
892  final public function close( $fname = __METHOD__, $owner = null ) {
893  $error = null; // error to throw after disconnecting
894 
895  $wasOpen = (bool)$this->conn;
896  // This should mostly do nothing if the connection is already closed
897  if ( $this->conn ) {
898  // Roll back any dangling transaction first
899  if ( $this->trxLevel() ) {
900  if ( $this->trxAtomicLevels ) {
901  // Cannot let incomplete atomic sections be committed
902  $levels = $this->flatAtomicSectionList();
903  $error = "$fname: atomic sections $levels are still open";
904  } elseif ( $this->trxAutomatic ) {
905  // Only the connection manager can commit non-empty DBO_TRX transactions
906  // (empty ones we can silently roll back)
907  if ( $this->writesOrCallbacksPending() ) {
908  $error = "$fname: " .
909  "expected mass rollback of all peer transactions (DBO_TRX set)";
910  }
911  } else {
912  // Manual transactions should have been committed or rolled
913  // back, even if empty.
914  $error = "$fname: transaction is still open (from {$this->trxFname})";
915  }
916 
917  if ( $this->trxEndCallbacksSuppressed && $error === null ) {
918  $error = "$fname: callbacks are suppressed; cannot properly commit";
919  }
920 
921  // Rollback the changes and run any callbacks as needed
922  $this->rollback( __METHOD__, self::FLUSHING_INTERNAL );
923  }
924 
925  // Close the actual connection in the binding handle
926  $closed = $this->closeConnection();
927  } else {
928  $closed = true; // already closed; nothing to do
929  }
930 
931  $this->conn = null;
932 
933  // Log or throw any unexpected errors after having disconnected
934  if ( $error !== null ) {
935  // T217819, T231443: if this is probably just LoadBalancer trying to recover from
936  // errors and shutdown, then log any problems and move on since the request has to
937  // end one way or another. Throwing errors is not very useful at some point.
938  if ( $this->ownerId !== null && $owner === $this->ownerId ) {
939  $this->queryLogger->error( $error );
940  } else {
941  throw new DBUnexpectedError( $this, $error );
942  }
943  }
944 
945  // Note that various subclasses call close() at the start of open(), which itself is
946  // called by replaceLostConnection(). In that case, just because onTransactionResolution()
947  // callbacks are pending does not mean that an exception should be thrown. Rather, they
948  // will be executed after the reconnection step.
949  if ( $wasOpen ) {
950  // Sanity check that no callbacks are dangling
951  $fnames = $this->pendingWriteAndCallbackCallers();
952  if ( $fnames ) {
953  throw new RuntimeException(
954  "Transaction callbacks are still pending: " . implode( ', ', $fnames )
955  );
956  }
957  }
958 
959  return $closed;
960  }
961 
970  final protected function assertHasConnectionHandle() {
971  if ( !$this->isOpen() ) {
972  throw new DBUnexpectedError( $this, "DB connection was already closed" );
973  }
974  }
975 
981  protected function assertIsWritableMaster() {
982  $info = $this->getReadOnlyReason();
983  if ( $info ) {
984  list( $reason, $source ) = $info;
985  if ( $source === 'role' ) {
986  throw new DBReadOnlyRoleError( $this, "Database is read-only: $reason" );
987  } else {
988  throw new DBReadOnlyError( $this, "Database is read-only: $reason" );
989  }
990  }
991  }
992 
998  abstract protected function closeConnection();
999 
1029  abstract protected function doQuery( $sql );
1030 
1047  protected function isWriteQuery( $sql ) {
1048  // BEGIN and COMMIT queries are considered read queries here.
1049  // Database backends and drivers (MySQL, MariaDB, php-mysqli) generally
1050  // treat these as write queries, in that their results have "affected rows"
1051  // as meta data as from writes, instead of "num rows" as from reads.
1052  // But, we treat them as read queries because when reading data (from
1053  // either replica or master) we use transactions to enable repeatable-read
1054  // snapshots, which ensures we get consistent results from the same snapshot
1055  // for all queries within a request. Use cases:
1056  // - Treating these as writes would trigger ChronologyProtector (see method doc).
1057  // - We use this method to reject writes to replicas, but we need to allow
1058  // use of transactions on replicas for read snapshots. This is fine given
1059  // that transactions by themselves don't make changes, only actual writes
1060  // within the transaction matter, which we still detect.
1061  return !preg_match(
1062  '/^(?:SELECT|BEGIN|ROLLBACK|COMMIT|SAVEPOINT|RELEASE|SET|SHOW|EXPLAIN|USE|\(SELECT)\b/i',
1063  $sql
1064  );
1065  }
1066 
1071  protected function getQueryVerb( $sql ) {
1072  return preg_match( '/^\s*([a-z]+)/i', $sql, $m ) ? strtoupper( $m[1] ) : null;
1073  }
1074 
1088  protected function isTransactableQuery( $sql ) {
1089  return !in_array(
1090  $this->getQueryVerb( $sql ),
1091  [ 'BEGIN', 'ROLLBACK', 'COMMIT', 'SET', 'SHOW', 'CREATE', 'ALTER', 'USE', 'SHOW' ],
1092  true
1093  );
1094  }
1095 
1104  protected function getTempWrites( $sql, $pseudoPermanent ) {
1105  static $qt = '[`"\']?(\w+)[`"\']?'; // quoted table
1106 
1107  if ( preg_match(
1108  '/^CREATE\s+TEMPORARY\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?' . $qt . '/i',
1109  $sql,
1110  $matches
1111  ) ) {
1112  $type = $pseudoPermanent ? self::$TEMP_PSEUDO_PERMANENT : self::$TEMP_NORMAL;
1113 
1114  return [ $type, $matches[1], null ];
1115  } elseif ( preg_match(
1116  '/^DROP\s+(?:TEMPORARY\s+)?TABLE\s+(?:IF\s+EXISTS\s+)?' . $qt . '/i',
1117  $sql,
1118  $matches
1119  ) ) {
1120  return [ $this->sessionTempTables[$matches[1]] ?? null, null, $matches[1] ];
1121  } elseif ( preg_match(
1122  '/^TRUNCATE\s+(?:TEMPORARY\s+)?TABLE\s+(?:IF\s+EXISTS\s+)?' . $qt . '/i',
1123  $sql,
1124  $matches
1125  ) ) {
1126  return [ $this->sessionTempTables[$matches[1]] ?? null, null, null ];
1127  } elseif ( preg_match(
1128  '/^(?:(?:INSERT|REPLACE)\s+(?:\w+\s+)?INTO|UPDATE|DELETE\s+FROM)\s+' . $qt . '/i',
1129  $sql,
1130  $matches
1131  ) ) {
1132  return [ $this->sessionTempTables[$matches[1]] ?? null, null, null ];
1133  }
1134 
1135  return [ null, null, null ];
1136  }
1137 
1144  protected function registerTempWrites( $ret, $tmpType, $tmpNew, $tmpDel ) {
1145  if ( $ret !== false ) {
1146  if ( $tmpNew !== null ) {
1147  $this->sessionTempTables[$tmpNew] = $tmpType;
1148  }
1149  if ( $tmpDel !== null ) {
1150  unset( $this->sessionTempTables[$tmpDel] );
1151  }
1152  }
1153  }
1154 
1155  public function query( $sql, $fname = __METHOD__, $flags = 0 ) {
1156  $flags = (int)$flags; // b/c; this field used to be a bool
1157  // Sanity check that the SQL query is appropriate in the current context and is
1158  // allowed for an outside caller (e.g. does not break transaction/session tracking).
1159  $this->assertQueryIsCurrentlyAllowed( $sql, $fname );
1160 
1161  // Send the query to the server and fetch any corresponding errors
1162  list( $ret, $err, $errno, $unignorable ) = $this->executeQuery( $sql, $fname, $flags );
1163  if ( $ret === false ) {
1164  $ignoreErrors = $this->fieldHasBit( $flags, self::QUERY_SILENCE_ERRORS );
1165  // Throw an error unless both the ignore flag was set and a rollback is not needed
1166  $this->reportQueryError( $err, $errno, $sql, $fname, $ignoreErrors && !$unignorable );
1167  }
1168 
1169  return $this->resultObject( $ret );
1170  }
1171 
1192  final protected function executeQuery( $sql, $fname, $flags ) {
1193  $this->assertHasConnectionHandle();
1194 
1195  $priorTransaction = $this->trxLevel();
1196 
1197  if ( $this->isWriteQuery( $sql ) ) {
1198  // In theory, non-persistent writes are allowed in read-only mode, but due to things
1199  // like https://bugs.mysql.com/bug.php?id=33669 that might not work anyway...
1200  $this->assertIsWritableMaster();
1201  // Do not treat temporary table writes as "meaningful writes" since they are only
1202  // visible to one session and are not permanent. Profile them as reads. Integration
1203  // tests can override this behavior via $flags.
1204  $pseudoPermanent = $this->fieldHasBit( $flags, self::QUERY_PSEUDO_PERMANENT );
1205  list( $tmpType, $tmpNew, $tmpDel ) = $this->getTempWrites( $sql, $pseudoPermanent );
1206  $isPermWrite = ( $tmpType !== self::$TEMP_NORMAL );
1207  // DBConnRef uses QUERY_REPLICA_ROLE to enforce the replica role for raw SQL queries
1208  if ( $isPermWrite && $this->fieldHasBit( $flags, self::QUERY_REPLICA_ROLE ) ) {
1209  throw new DBReadOnlyRoleError( $this, "Cannot write; target role is DB_REPLICA" );
1210  }
1211  } else {
1212  // No permanent writes in this query
1213  $isPermWrite = false;
1214  // No temporary tables written to either
1215  list( $tmpType, $tmpNew, $tmpDel ) = [ null, null, null ];
1216  }
1217 
1218  // Add trace comment to the begin of the sql string, right after the operator.
1219  // Or, for one-word queries (like "BEGIN" or COMMIT") add it to the end (T44598).
1220  $encAgent = str_replace( '/', '-', $this->agent );
1221  $commentedSql = preg_replace( '/\s|$/', " /* $fname $encAgent */ ", $sql, 1 );
1222 
1223  // Send the query to the server and fetch any corresponding errors.
1224  // This also doubles as a "ping" to see if the connection was dropped.
1225  list( $ret, $err, $errno, $recoverableSR, $recoverableCL, $reconnected ) =
1226  $this->executeQueryAttempt( $sql, $commentedSql, $isPermWrite, $fname, $flags );
1227 
1228  // Check if the query failed due to a recoverable connection loss
1229  $allowRetry = !$this->fieldHasBit( $flags, self::QUERY_NO_RETRY );
1230  if ( $ret === false && $recoverableCL && $reconnected && $allowRetry ) {
1231  // Silently resend the query to the server since it is safe and possible
1232  list( $ret, $err, $errno, $recoverableSR, $recoverableCL ) =
1233  $this->executeQueryAttempt( $sql, $commentedSql, $isPermWrite, $fname, $flags );
1234  }
1235 
1236  // Register creation and dropping of temporary tables
1237  $this->registerTempWrites( $ret, $tmpType, $tmpNew, $tmpDel );
1238 
1239  $corruptedTrx = false;
1240 
1241  if ( $ret === false ) {
1242  if ( $priorTransaction ) {
1243  if ( $recoverableSR ) {
1244  # We're ignoring an error that caused just the current query to be aborted.
1245  # But log the cause so we can log a deprecation notice if a caller actually
1246  # does ignore it.
1247  $this->trxStatusIgnoredCause = [ $err, $errno, $fname ];
1248  } elseif ( !$recoverableCL ) {
1249  # Either the query was aborted or all queries after BEGIN where aborted.
1250  # In the first case, the only options going forward are (a) ROLLBACK, or
1251  # (b) ROLLBACK TO SAVEPOINT (if one was set). If the later case, the only
1252  # option is ROLLBACK, since the snapshots would have been released.
1253  $corruptedTrx = true; // cannot recover
1254  $this->trxStatus = self::STATUS_TRX_ERROR;
1255  $this->trxStatusCause = $this->getQueryException( $err, $errno, $sql, $fname );
1256  $this->trxStatusIgnoredCause = null;
1257  }
1258  }
1259  }
1260 
1261  return [ $ret, $err, $errno, $corruptedTrx ];
1262  }
1263 
1282  private function executeQueryAttempt( $sql, $commentedSql, $isPermWrite, $fname, $flags ) {
1283  $priorWritesPending = $this->writesOrCallbacksPending();
1284 
1285  if ( ( $flags & self::QUERY_IGNORE_DBO_TRX ) == 0 ) {
1286  $this->beginIfImplied( $sql, $fname );
1287  }
1288 
1289  // Keep track of whether the transaction has write queries pending
1290  if ( $isPermWrite ) {
1291  $this->lastWriteTime = microtime( true );
1292  if ( $this->trxLevel() && !$this->trxDoneWrites ) {
1293  $this->trxDoneWrites = true;
1294  $this->trxProfiler->transactionWritingIn(
1295  $this->server, $this->getDomainID(), $this->trxShortId );
1296  }
1297  }
1298 
1299  $prefix = $this->topologyRole ? 'query-m: ' : 'query: ';
1300  $generalizedSql = new GeneralizedSql( $sql, $this->trxShortId, $prefix );
1301 
1302  $startTime = microtime( true );
1303  $ps = $this->profiler
1304  ? ( $this->profiler )( $generalizedSql->stringify() )
1305  : null;
1306  $this->affectedRowCount = null;
1307  $this->lastQuery = $sql;
1308  $ret = $this->doQuery( $commentedSql );
1309  $lastError = $this->lastError();
1310  $lastErrno = $this->lastErrno();
1311 
1312  $this->affectedRowCount = $this->affectedRows();
1313  unset( $ps ); // profile out (if set)
1314  $queryRuntime = max( microtime( true ) - $startTime, 0.0 );
1315 
1316  $recoverableSR = false; // recoverable statement rollback?
1317  $recoverableCL = false; // recoverable connection loss?
1318  $reconnected = false; // reconnection both attempted and succeeded?
1319 
1320  if ( $ret !== false ) {
1321  $this->lastPing = $startTime;
1322  if ( $isPermWrite && $this->trxLevel() ) {
1323  $this->updateTrxWriteQueryTime( $sql, $queryRuntime, $this->affectedRows() );
1324  $this->trxWriteCallers[] = $fname;
1325  }
1326  } elseif ( $this->wasConnectionError( $lastErrno ) ) {
1327  # Check if no meaningful session state was lost
1328  $recoverableCL = $this->canRecoverFromDisconnect( $sql, $priorWritesPending );
1329  # Update session state tracking and try to restore the connection
1330  $reconnected = $this->replaceLostConnection( __METHOD__ );
1331  } else {
1332  # Check if only the last query was rolled back
1333  $recoverableSR = $this->wasKnownStatementRollbackError();
1334  }
1335 
1336  if ( $sql === self::$PING_QUERY ) {
1337  $this->lastRoundTripEstimate = $queryRuntime;
1338  }
1339 
1340  $this->trxProfiler->recordQueryCompletion(
1341  $generalizedSql,
1342  $startTime,
1343  $isPermWrite,
1344  $isPermWrite ? $this->affectedRows() : $this->numRows( $ret )
1345  );
1346 
1347  // Avoid the overhead of logging calls unless debug mode is enabled
1348  if ( $this->getFlag( self::DBO_DEBUG ) ) {
1349  $this->queryLogger->debug(
1350  "{method} [{runtime}s] {db_host}: {sql}",
1351  [
1352  'method' => $fname,
1353  'db_host' => $this->getServer(),
1354  'sql' => $sql,
1355  'domain' => $this->getDomainID(),
1356  'runtime' => round( $queryRuntime, 3 )
1357  ]
1358  );
1359  }
1360 
1361  return [ $ret, $lastError, $lastErrno, $recoverableSR, $recoverableCL, $reconnected ];
1362  }
1363 
1370  private function beginIfImplied( $sql, $fname ) {
1371  if (
1372  !$this->trxLevel() &&
1373  $this->getFlag( self::DBO_TRX ) &&
1374  $this->isTransactableQuery( $sql )
1375  ) {
1376  $this->begin( __METHOD__ . " ($fname)", self::TRANSACTION_INTERNAL );
1377  $this->trxAutomatic = true;
1378  }
1379  }
1380 
1393  private function updateTrxWriteQueryTime( $sql, $runtime, $affected ) {
1394  // Whether this is indicative of replica DB runtime (except for RBR or ws_repl)
1395  $indicativeOfReplicaRuntime = true;
1396  if ( $runtime > self::$SLOW_WRITE_SEC ) {
1397  $verb = $this->getQueryVerb( $sql );
1398  // insert(), upsert(), replace() are fast unless bulky in size or blocked on locks
1399  if ( $verb === 'INSERT' ) {
1400  $indicativeOfReplicaRuntime = $this->affectedRows() > self::$SMALL_WRITE_ROWS;
1401  } elseif ( $verb === 'REPLACE' ) {
1402  $indicativeOfReplicaRuntime = $this->affectedRows() > self::$SMALL_WRITE_ROWS / 2;
1403  }
1404  }
1405 
1406  $this->trxWriteDuration += $runtime;
1407  $this->trxWriteQueryCount += 1;
1408  $this->trxWriteAffectedRows += $affected;
1409  if ( $indicativeOfReplicaRuntime ) {
1410  $this->trxWriteAdjDuration += $runtime;
1411  $this->trxWriteAdjQueryCount += 1;
1412  }
1413  }
1414 
1422  private function assertQueryIsCurrentlyAllowed( $sql, $fname ) {
1423  $verb = $this->getQueryVerb( $sql );
1424  if ( $verb === 'USE' ) {
1425  throw new DBUnexpectedError( $this, "Got USE query; use selectDomain() instead" );
1426  }
1427 
1428  if ( $verb === 'ROLLBACK' ) { // transaction/savepoint
1429  return;
1430  }
1431 
1432  if ( $this->trxStatus < self::STATUS_TRX_OK ) {
1433  throw new DBTransactionStateError(
1434  $this,
1435  "Cannot execute query from $fname while transaction status is ERROR",
1436  [],
1437  $this->trxStatusCause
1438  );
1439  } elseif ( $this->trxStatus === self::STATUS_TRX_OK && $this->trxStatusIgnoredCause ) {
1440  list( $iLastError, $iLastErrno, $iFname ) = $this->trxStatusIgnoredCause;
1441  call_user_func( $this->deprecationLogger,
1442  "Caller from $fname ignored an error originally raised from $iFname: " .
1443  "[$iLastErrno] $iLastError"
1444  );
1445  $this->trxStatusIgnoredCause = null;
1446  }
1447  }
1448 
1449  public function assertNoOpenTransactions() {
1450  if ( $this->explicitTrxActive() ) {
1451  throw new DBTransactionError(
1452  $this,
1453  "Explicit transaction still active. A caller may have caught an error. "
1454  . "Open transactions: " . $this->flatAtomicSectionList()
1455  );
1456  }
1457  }
1458 
1468  private function canRecoverFromDisconnect( $sql, $priorWritesPending ) {
1469  # Transaction dropped; this can mean lost writes, or REPEATABLE-READ snapshots.
1470  # Dropped connections also mean that named locks are automatically released.
1471  # Only allow error suppression in autocommit mode or when the lost transaction
1472  # didn't matter anyway (aside from DBO_TRX snapshot loss).
1473  if ( $this->sessionNamedLocks ) {
1474  return false; // possible critical section violation
1475  } elseif ( $this->sessionTempTables ) {
1476  return false; // tables might be queried latter
1477  } elseif ( $sql === 'COMMIT' ) {
1478  return !$priorWritesPending; // nothing written anyway? (T127428)
1479  } elseif ( $sql === 'ROLLBACK' ) {
1480  return true; // transaction lost...which is also what was requested :)
1481  } elseif ( $this->explicitTrxActive() ) {
1482  return false; // don't drop atomicity and explicit snapshots
1483  } elseif ( $priorWritesPending ) {
1484  return false; // prior writes lost from implicit transaction
1485  }
1486 
1487  return true;
1488  }
1489 
1493  private function handleSessionLossPreconnect() {
1494  // Clean up tracking of session-level things...
1495  // https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html
1496  // https://www.postgresql.org/docs/9.2/static/sql-createtable.html (ignoring ON COMMIT)
1497  $this->sessionTempTables = [];
1498  // https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_get-lock
1499  // https://www.postgresql.org/docs/9.4/static/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS
1500  $this->sessionNamedLocks = [];
1501  // Session loss implies transaction loss
1502  $oldTrxShortId = $this->consumeTrxShortId();
1503  $this->trxAtomicCounter = 0;
1504  $this->trxIdleCallbacks = []; // T67263; transaction already lost
1505  $this->trxPreCommitCallbacks = []; // T67263; transaction already lost
1506  // Clear additional subclass fields
1508  // @note: leave trxRecurringCallbacks in place
1509  if ( $this->trxDoneWrites ) {
1510  $this->trxProfiler->transactionWritingOut(
1511  $this->server,
1512  $this->getDomainID(),
1513  $oldTrxShortId,
1514  $this->pendingWriteQueryDuration( self::ESTIMATE_TOTAL ),
1515  $this->trxWriteAffectedRows
1516  );
1517  }
1518  }
1519 
1523  protected function doHandleSessionLossPreconnect() {
1524  // no-op
1525  }
1526 
1530  private function handleSessionLossPostconnect() {
1531  try {
1532  // Handle callbacks in trxEndCallbacks, e.g. onTransactionResolution().
1533  // If callback suppression is set then the array will remain unhandled.
1534  $this->runOnTransactionIdleCallbacks( self::TRIGGER_ROLLBACK );
1535  } catch ( Exception $ex ) {
1536  // Already logged; move on...
1537  }
1538  try {
1539  // Handle callbacks in trxRecurringCallbacks, e.g. setTransactionListener()
1540  $this->runTransactionListenerCallbacks( self::TRIGGER_ROLLBACK );
1541  } catch ( Exception $ex ) {
1542  // Already logged; move on...
1543  }
1544  }
1545 
1551  private function consumeTrxShortId() {
1552  $old = $this->trxShortId;
1553  $this->trxShortId = '';
1554 
1555  return $old;
1556  }
1557 
1568  protected function wasQueryTimeout( $error, $errno ) {
1569  return false;
1570  }
1571 
1583  public function reportQueryError( $error, $errno, $sql, $fname, $ignore = false ) {
1584  if ( $ignore ) {
1585  $this->queryLogger->debug( "SQL ERROR (ignored): $error" );
1586  } else {
1587  throw $this->getQueryExceptionAndLog( $error, $errno, $sql, $fname );
1588  }
1589  }
1590 
1598  private function getQueryExceptionAndLog( $error, $errno, $sql, $fname ) {
1599  $this->queryLogger->error(
1600  "{fname}\t{db_server}\t{errno}\t{error}\t{sql1line}",
1601  $this->getLogContext( [
1602  'method' => __METHOD__,
1603  'errno' => $errno,
1604  'error' => $error,
1605  'sql1line' => mb_substr( str_replace( "\n", "\\n", $sql ), 0, 5 * 1024 ),
1606  'fname' => $fname,
1607  'trace' => ( new RuntimeException() )->getTraceAsString()
1608  ] )
1609  );
1610  return $this->getQueryException( $error, $errno, $sql, $fname );
1611  }
1612 
1620  private function getQueryException( $error, $errno, $sql, $fname ) {
1621  if ( $this->wasQueryTimeout( $error, $errno ) ) {
1622  return new DBQueryTimeoutError( $this, $error, $errno, $sql, $fname );
1623  } elseif ( $this->wasConnectionError( $errno ) ) {
1624  return new DBQueryDisconnectedError( $this, $error, $errno, $sql, $fname );
1625  } else {
1626  return new DBQueryError( $this, $error, $errno, $sql, $fname );
1627  }
1628  }
1629 
1634  final protected function newExceptionAfterConnectError( $error ) {
1635  // Connection was not fully initialized and is not safe for use
1636  $this->conn = null;
1637 
1638  $this->connLogger->error(
1639  "Error connecting to {db_server} as user {db_user}: {error}",
1640  $this->getLogContext( [
1641  'error' => $error,
1642  'trace' => ( new RuntimeException() )->getTraceAsString()
1643  ] )
1644  );
1645 
1646  return new DBConnectionError( $this, $error );
1647  }
1648 
1649  public function freeResult( $res ) {
1650  }
1651 
1652  public function selectField(
1653  $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
1654  ) {
1655  if ( $var === '*' ) { // sanity
1656  throw new DBUnexpectedError( $this, "Cannot use a * field: got '$var'" );
1657  }
1658 
1659  if ( !is_array( $options ) ) {
1660  $options = [ $options ];
1661  }
1662 
1663  $options['LIMIT'] = 1;
1664 
1665  $res = $this->select( $table, $var, $cond, $fname, $options, $join_conds );
1666  if ( $res === false ) {
1667  throw new DBUnexpectedError( $this, "Got false from select()" );
1668  }
1669 
1670  $row = $this->fetchRow( $res );
1671  if ( $row === false ) {
1672  return false;
1673  }
1674 
1675  return reset( $row );
1676  }
1677 
1678  public function selectFieldValues(
1679  $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
1680  ) {
1681  if ( $var === '*' ) { // sanity
1682  throw new DBUnexpectedError( $this, "Cannot use a * field" );
1683  } elseif ( !is_string( $var ) ) { // sanity
1684  throw new DBUnexpectedError( $this, "Cannot use an array of fields" );
1685  }
1686 
1687  if ( !is_array( $options ) ) {
1688  $options = [ $options ];
1689  }
1690 
1691  $res = $this->select( $table, [ 'value' => $var ], $cond, $fname, $options, $join_conds );
1692  if ( $res === false ) {
1693  throw new DBUnexpectedError( $this, "Got false from select()" );
1694  }
1695 
1696  $values = [];
1697  foreach ( $res as $row ) {
1698  $values[] = $row->value;
1699  }
1700 
1701  return $values;
1702  }
1703 
1714  protected function makeSelectOptions( array $options ) {
1715  $preLimitTail = $postLimitTail = '';
1716  $startOpts = '';
1717 
1718  $noKeyOptions = [];
1719 
1720  foreach ( $options as $key => $option ) {
1721  if ( is_numeric( $key ) ) {
1722  $noKeyOptions[$option] = true;
1723  }
1724  }
1725 
1726  $preLimitTail .= $this->makeGroupByWithHaving( $options );
1727 
1728  $preLimitTail .= $this->makeOrderBy( $options );
1729 
1730  if ( isset( $noKeyOptions['FOR UPDATE'] ) ) {
1731  $postLimitTail .= ' FOR UPDATE';
1732  }
1733 
1734  if ( isset( $noKeyOptions['LOCK IN SHARE MODE'] ) ) {
1735  $postLimitTail .= ' LOCK IN SHARE MODE';
1736  }
1737 
1738  if ( isset( $noKeyOptions['DISTINCT'] ) || isset( $noKeyOptions['DISTINCTROW'] ) ) {
1739  $startOpts .= 'DISTINCT';
1740  }
1741 
1742  # Various MySQL extensions
1743  if ( isset( $noKeyOptions['STRAIGHT_JOIN'] ) ) {
1744  $startOpts .= ' /*! STRAIGHT_JOIN */';
1745  }
1746 
1747  if ( isset( $noKeyOptions['SQL_BIG_RESULT'] ) ) {
1748  $startOpts .= ' SQL_BIG_RESULT';
1749  }
1750 
1751  if ( isset( $noKeyOptions['SQL_BUFFER_RESULT'] ) ) {
1752  $startOpts .= ' SQL_BUFFER_RESULT';
1753  }
1754 
1755  if ( isset( $noKeyOptions['SQL_SMALL_RESULT'] ) ) {
1756  $startOpts .= ' SQL_SMALL_RESULT';
1757  }
1758 
1759  if ( isset( $noKeyOptions['SQL_CALC_FOUND_ROWS'] ) ) {
1760  $startOpts .= ' SQL_CALC_FOUND_ROWS';
1761  }
1762 
1763  if ( isset( $options['USE INDEX'] ) && is_string( $options['USE INDEX'] ) ) {
1764  $useIndex = $this->useIndexClause( $options['USE INDEX'] );
1765  } else {
1766  $useIndex = '';
1767  }
1768  if ( isset( $options['IGNORE INDEX'] ) && is_string( $options['IGNORE INDEX'] ) ) {
1769  $ignoreIndex = $this->ignoreIndexClause( $options['IGNORE INDEX'] );
1770  } else {
1771  $ignoreIndex = '';
1772  }
1773 
1774  return [ $startOpts, $useIndex, $preLimitTail, $postLimitTail, $ignoreIndex ];
1775  }
1776 
1785  protected function makeGroupByWithHaving( $options ) {
1786  $sql = '';
1787  if ( isset( $options['GROUP BY'] ) ) {
1788  $gb = is_array( $options['GROUP BY'] )
1789  ? implode( ',', $options['GROUP BY'] )
1790  : $options['GROUP BY'];
1791  $sql .= ' GROUP BY ' . $gb;
1792  }
1793  if ( isset( $options['HAVING'] ) ) {
1794  $having = is_array( $options['HAVING'] )
1795  ? $this->makeList( $options['HAVING'], self::LIST_AND )
1796  : $options['HAVING'];
1797  $sql .= ' HAVING ' . $having;
1798  }
1799 
1800  return $sql;
1801  }
1802 
1811  protected function makeOrderBy( $options ) {
1812  if ( isset( $options['ORDER BY'] ) ) {
1813  $ob = is_array( $options['ORDER BY'] )
1814  ? implode( ',', $options['ORDER BY'] )
1815  : $options['ORDER BY'];
1816 
1817  return ' ORDER BY ' . $ob;
1818  }
1819 
1820  return '';
1821  }
1822 
1823  public function select(
1824  $table, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
1825  ) {
1826  $sql = $this->selectSQLText( $table, $vars, $conds, $fname, $options, $join_conds );
1827 
1828  return $this->query( $sql, $fname );
1829  }
1830 
1831  public function selectSQLText( $table, $vars, $conds = '', $fname = __METHOD__,
1832  $options = [], $join_conds = []
1833  ) {
1834  if ( is_array( $vars ) ) {
1835  $fields = implode( ',', $this->fieldNamesWithAlias( $vars ) );
1836  } else {
1837  $fields = $vars;
1838  }
1839 
1840  $options = (array)$options;
1841  $useIndexes = ( isset( $options['USE INDEX'] ) && is_array( $options['USE INDEX'] ) )
1842  ? $options['USE INDEX']
1843  : [];
1844  $ignoreIndexes = (
1845  isset( $options['IGNORE INDEX'] ) &&
1846  is_array( $options['IGNORE INDEX'] )
1847  )
1848  ? $options['IGNORE INDEX']
1849  : [];
1850 
1851  if (
1852  $this->selectOptionsIncludeLocking( $options ) &&
1853  $this->selectFieldsOrOptionsAggregate( $vars, $options )
1854  ) {
1855  // Some DB types (e.g. postgres) disallow FOR UPDATE with aggregate
1856  // functions. Discourage use of such queries to encourage compatibility.
1857  call_user_func(
1858  $this->deprecationLogger,
1859  __METHOD__ . ": aggregation used with a locking SELECT ($fname)"
1860  );
1861  }
1862 
1863  if ( is_array( $table ) ) {
1864  $from = ' FROM ' .
1866  $table, $useIndexes, $ignoreIndexes, $join_conds );
1867  } elseif ( $table != '' ) {
1868  $from = ' FROM ' .
1870  [ $table ], $useIndexes, $ignoreIndexes, [] );
1871  } else {
1872  $from = '';
1873  }
1874 
1875  list( $startOpts, $useIndex, $preLimitTail, $postLimitTail, $ignoreIndex ) =
1876  $this->makeSelectOptions( $options );
1877 
1878  if ( is_array( $conds ) ) {
1879  $conds = $this->makeList( $conds, self::LIST_AND );
1880  }
1881 
1882  if ( $conds === null || $conds === false ) {
1883  $this->queryLogger->warning(
1884  __METHOD__
1885  . ' called from '
1886  . $fname
1887  . ' with incorrect parameters: $conds must be a string or an array'
1888  );
1889  $conds = '';
1890  }
1891 
1892  if ( $conds === '' || $conds === '*' ) {
1893  $sql = "SELECT $startOpts $fields $from $useIndex $ignoreIndex $preLimitTail";
1894  } elseif ( is_string( $conds ) ) {
1895  $sql = "SELECT $startOpts $fields $from $useIndex $ignoreIndex " .
1896  "WHERE $conds $preLimitTail";
1897  } else {
1898  throw new DBUnexpectedError( $this, __METHOD__ . ' called with incorrect parameters' );
1899  }
1900 
1901  if ( isset( $options['LIMIT'] ) ) {
1902  $sql = $this->limitResult( $sql, $options['LIMIT'],
1903  $options['OFFSET'] ?? false );
1904  }
1905  $sql = "$sql $postLimitTail";
1906 
1907  if ( isset( $options['EXPLAIN'] ) ) {
1908  $sql = 'EXPLAIN ' . $sql;
1909  }
1910 
1911  return $sql;
1912  }
1913 
1914  public function selectRow( $table, $vars, $conds, $fname = __METHOD__,
1915  $options = [], $join_conds = []
1916  ) {
1917  $options = (array)$options;
1918  $options['LIMIT'] = 1;
1919 
1920  $res = $this->select( $table, $vars, $conds, $fname, $options, $join_conds );
1921  if ( $res === false ) {
1922  throw new DBUnexpectedError( $this, "Got false from select()" );
1923  }
1924 
1925  if ( !$this->numRows( $res ) ) {
1926  return false;
1927  }
1928 
1929  return $this->fetchObject( $res );
1930  }
1931 
1932  public function estimateRowCount(
1933  $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
1934  ) {
1935  $conds = $this->normalizeConditions( $conds, $fname );
1936  $column = $this->extractSingleFieldFromList( $var );
1937  if ( is_string( $column ) && !in_array( $column, [ '*', '1' ] ) ) {
1938  $conds[] = "$column IS NOT NULL";
1939  }
1940 
1941  $res = $this->select(
1942  $tables, [ 'rowcount' => 'COUNT(*)' ], $conds, $fname, $options, $join_conds
1943  );
1944  $row = $res ? $this->fetchRow( $res ) : [];
1945 
1946  return isset( $row['rowcount'] ) ? (int)$row['rowcount'] : 0;
1947  }
1948 
1949  public function selectRowCount(
1950  $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
1951  ) {
1952  $conds = $this->normalizeConditions( $conds, $fname );
1953  $column = $this->extractSingleFieldFromList( $var );
1954  if ( is_string( $column ) && !in_array( $column, [ '*', '1' ] ) ) {
1955  $conds[] = "$column IS NOT NULL";
1956  }
1957 
1958  $res = $this->select(
1959  [
1960  'tmp_count' => $this->buildSelectSubquery(
1961  $tables,
1962  '1',
1963  $conds,
1964  $fname,
1965  $options,
1966  $join_conds
1967  )
1968  ],
1969  [ 'rowcount' => 'COUNT(*)' ],
1970  [],
1971  $fname
1972  );
1973  $row = $res ? $this->fetchRow( $res ) : [];
1974 
1975  return isset( $row['rowcount'] ) ? (int)$row['rowcount'] : 0;
1976  }
1977 
1982  private function selectOptionsIncludeLocking( $options ) {
1983  $options = (array)$options;
1984  foreach ( [ 'FOR UPDATE', 'LOCK IN SHARE MODE' ] as $lock ) {
1985  if ( in_array( $lock, $options, true ) ) {
1986  return true;
1987  }
1988  }
1989 
1990  return false;
1991  }
1992 
1998  private function selectFieldsOrOptionsAggregate( $fields, $options ) {
1999  foreach ( (array)$options as $key => $value ) {
2000  if ( is_string( $key ) ) {
2001  if ( preg_match( '/^(?:GROUP BY|HAVING)$/i', $key ) ) {
2002  return true;
2003  }
2004  } elseif ( is_string( $value ) ) {
2005  if ( preg_match( '/^(?:DISTINCT|DISTINCTROW)$/i', $value ) ) {
2006  return true;
2007  }
2008  }
2009  }
2010 
2011  $regex = '/^(?:COUNT|MIN|MAX|SUM|GROUP_CONCAT|LISTAGG|ARRAY_AGG)\s*\\(/i';
2012  foreach ( (array)$fields as $field ) {
2013  if ( is_string( $field ) && preg_match( $regex, $field ) ) {
2014  return true;
2015  }
2016  }
2017 
2018  return false;
2019  }
2020 
2026  final protected function normalizeConditions( $conds, $fname ) {
2027  if ( $conds === null || $conds === false ) {
2028  $this->queryLogger->warning(
2029  __METHOD__
2030  . ' called from '
2031  . $fname
2032  . ' with incorrect parameters: $conds must be a string or an array'
2033  );
2034  $conds = '';
2035  }
2036 
2037  if ( !is_array( $conds ) ) {
2038  $conds = ( $conds === '' ) ? [] : [ $conds ];
2039  }
2040 
2041  return $conds;
2042  }
2043 
2049  final protected function extractSingleFieldFromList( $var ) {
2050  if ( is_array( $var ) ) {
2051  if ( !$var ) {
2052  $column = null;
2053  } elseif ( count( $var ) == 1 ) {
2054  $column = $var[0] ?? reset( $var );
2055  } else {
2056  throw new DBUnexpectedError( $this, __METHOD__ . ': got multiple columns' );
2057  }
2058  } else {
2059  $column = $var;
2060  }
2061 
2062  return $column;
2063  }
2064 
2065  public function lockForUpdate(
2066  $table, $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
2067  ) {
2068  if ( !$this->trxLevel() && !$this->getFlag( self::DBO_TRX ) ) {
2069  throw new DBUnexpectedError(
2070  $this,
2071  __METHOD__ . ': no transaction is active nor is DBO_TRX set'
2072  );
2073  }
2074 
2075  $options = (array)$options;
2076  $options[] = 'FOR UPDATE';
2077 
2078  return $this->selectRowCount( $table, '*', $conds, $fname, $options, $join_conds );
2079  }
2080 
2081  public function fieldExists( $table, $field, $fname = __METHOD__ ) {
2082  $info = $this->fieldInfo( $table, $field );
2083 
2084  return (bool)$info;
2085  }
2086 
2087  public function indexExists( $table, $index, $fname = __METHOD__ ) {
2088  if ( !$this->tableExists( $table ) ) {
2089  return null;
2090  }
2091 
2092  $info = $this->indexInfo( $table, $index, $fname );
2093  if ( is_null( $info ) ) {
2094  return null;
2095  } else {
2096  return $info !== false;
2097  }
2098  }
2099 
2100  abstract public function tableExists( $table, $fname = __METHOD__ );
2101 
2102  public function indexUnique( $table, $index ) {
2103  $indexInfo = $this->indexInfo( $table, $index );
2104 
2105  if ( !$indexInfo ) {
2106  return null;
2107  }
2108 
2109  return !$indexInfo[0]->Non_unique;
2110  }
2111 
2118  protected function makeInsertOptions( $options ) {
2119  return implode( ' ', $options );
2120  }
2121 
2126  final protected function isMultiRowArray( array $a ) {
2127  return ( isset( $a[0] ) && is_array( $a[0] ) );
2128  }
2129 
2130  public function insert( $table, $rows, $fname = __METHOD__, $options = [] ) {
2131  # No rows to insert, easy just return now
2132  if ( !count( $rows ) ) {
2133  return true;
2134  }
2135 
2136  $table = $this->tableName( $table );
2137 
2138  if ( !is_array( $options ) ) {
2139  $options = [ $options ];
2140  }
2141 
2142  $options = $this->makeInsertOptions( $options );
2143 
2144  $multi = $this->isMultiRowArray( $rows );
2145  if ( $multi ) {
2146  $multi = true;
2147  $keys = array_keys( $rows[0] );
2148  } else {
2149  $multi = false;
2150  $keys = array_keys( $rows );
2151  }
2152 
2153  $sql = 'INSERT ' . $options .
2154  " INTO $table (" . implode( ',', $keys ) . ') VALUES ';
2155 
2156  if ( $multi ) {
2157  $first = true;
2158  foreach ( $rows as $row ) {
2159  if ( $first ) {
2160  $first = false;
2161  } else {
2162  $sql .= ',';
2163  }
2164  $sql .= '(' . $this->makeList( $row ) . ')';
2165  }
2166  } else {
2167  $sql .= '(' . $this->makeList( $rows ) . ')';
2168  }
2169 
2170  $this->query( $sql, $fname );
2171 
2172  return true;
2173  }
2174 
2181  protected function makeUpdateOptionsArray( $options ) {
2182  if ( !is_array( $options ) ) {
2183  $options = [ $options ];
2184  }
2185 
2186  $opts = [];
2187 
2188  if ( in_array( 'IGNORE', $options ) ) {
2189  $opts[] = 'IGNORE';
2190  }
2191 
2192  return $opts;
2193  }
2194 
2201  protected function makeUpdateOptions( $options ) {
2202  $opts = $this->makeUpdateOptionsArray( $options );
2203 
2204  return implode( ' ', $opts );
2205  }
2206 
2207  public function update( $table, $values, $conds, $fname = __METHOD__, $options = [] ) {
2208  $table = $this->tableName( $table );
2209  $opts = $this->makeUpdateOptions( $options );
2210  $sql = "UPDATE $opts $table SET " . $this->makeList( $values, self::LIST_SET );
2211 
2212  if ( $conds !== [] && $conds !== '*' ) {
2213  $sql .= " WHERE " . $this->makeList( $conds, self::LIST_AND );
2214  }
2215 
2216  $this->query( $sql, $fname );
2217 
2218  return true;
2219  }
2220 
2221  public function makeList( $a, $mode = self::LIST_COMMA ) {
2222  if ( !is_array( $a ) ) {
2223  throw new DBUnexpectedError( $this, __METHOD__ . ' called with incorrect parameters' );
2224  }
2225 
2226  $first = true;
2227  $list = '';
2228 
2229  foreach ( $a as $field => $value ) {
2230  if ( !$first ) {
2231  if ( $mode == self::LIST_AND ) {
2232  $list .= ' AND ';
2233  } elseif ( $mode == self::LIST_OR ) {
2234  $list .= ' OR ';
2235  } else {
2236  $list .= ',';
2237  }
2238  } else {
2239  $first = false;
2240  }
2241 
2242  if ( ( $mode == self::LIST_AND || $mode == self::LIST_OR ) && is_numeric( $field ) ) {
2243  $list .= "($value)";
2244  } elseif ( $mode == self::LIST_SET && is_numeric( $field ) ) {
2245  $list .= "$value";
2246  } elseif (
2247  ( $mode == self::LIST_AND || $mode == self::LIST_OR ) && is_array( $value )
2248  ) {
2249  // Remove null from array to be handled separately if found
2250  $includeNull = false;
2251  foreach ( array_keys( $value, null, true ) as $nullKey ) {
2252  $includeNull = true;
2253  unset( $value[$nullKey] );
2254  }
2255  if ( count( $value ) == 0 && !$includeNull ) {
2256  throw new InvalidArgumentException(
2257  __METHOD__ . ": empty input for field $field" );
2258  } elseif ( count( $value ) == 0 ) {
2259  // only check if $field is null
2260  $list .= "$field IS NULL";
2261  } else {
2262  // IN clause contains at least one valid element
2263  if ( $includeNull ) {
2264  // Group subconditions to ensure correct precedence
2265  $list .= '(';
2266  }
2267  if ( count( $value ) == 1 ) {
2268  // Special-case single values, as IN isn't terribly efficient
2269  // Don't necessarily assume the single key is 0; we don't
2270  // enforce linear numeric ordering on other arrays here.
2271  $value = array_values( $value )[0];
2272  $list .= $field . " = " . $this->addQuotes( $value );
2273  } else {
2274  $list .= $field . " IN (" . $this->makeList( $value ) . ") ";
2275  }
2276  // if null present in array, append IS NULL
2277  if ( $includeNull ) {
2278  $list .= " OR $field IS NULL)";
2279  }
2280  }
2281  } elseif ( $value === null ) {
2282  if ( $mode == self::LIST_AND || $mode == self::LIST_OR ) {
2283  $list .= "$field IS ";
2284  } elseif ( $mode == self::LIST_SET ) {
2285  $list .= "$field = ";
2286  }
2287  $list .= 'NULL';
2288  } else {
2289  if (
2290  $mode == self::LIST_AND || $mode == self::LIST_OR || $mode == self::LIST_SET
2291  ) {
2292  $list .= "$field = ";
2293  }
2294  $list .= $mode == self::LIST_NAMES ? $value : $this->addQuotes( $value );
2295  }
2296  }
2297 
2298  return $list;
2299  }
2300 
2301  public function makeWhereFrom2d( $data, $baseKey, $subKey ) {
2302  $conds = [];
2303 
2304  foreach ( $data as $base => $sub ) {
2305  if ( count( $sub ) ) {
2306  $conds[] = $this->makeList(
2307  [ $baseKey => $base, $subKey => array_keys( $sub ) ],
2308  self::LIST_AND );
2309  }
2310  }
2311 
2312  if ( $conds ) {
2313  return $this->makeList( $conds, self::LIST_OR );
2314  } else {
2315  // Nothing to search for...
2316  return false;
2317  }
2318  }
2319 
2320  public function aggregateValue( $valuedata, $valuename = 'value' ) {
2321  return $valuename;
2322  }
2323 
2324  public function bitNot( $field ) {
2325  return "(~$field)";
2326  }
2327 
2328  public function bitAnd( $fieldLeft, $fieldRight ) {
2329  return "($fieldLeft & $fieldRight)";
2330  }
2331 
2332  public function bitOr( $fieldLeft, $fieldRight ) {
2333  return "($fieldLeft | $fieldRight)";
2334  }
2335 
2336  public function buildConcat( $stringList ) {
2337  return 'CONCAT(' . implode( ',', $stringList ) . ')';
2338  }
2339 
2340  public function buildGroupConcatField(
2341  $delim, $table, $field, $conds = '', $join_conds = []
2342  ) {
2343  $fld = "GROUP_CONCAT($field SEPARATOR " . $this->addQuotes( $delim ) . ')';
2344 
2345  return '(' . $this->selectSQLText( $table, $fld, $conds, null, [], $join_conds ) . ')';
2346  }
2347 
2348  public function buildSubstring( $input, $startPosition, $length = null ) {
2349  $this->assertBuildSubstringParams( $startPosition, $length );
2350  $functionBody = "$input FROM $startPosition";
2351  if ( $length !== null ) {
2352  $functionBody .= " FOR $length";
2353  }
2354  return 'SUBSTRING(' . $functionBody . ')';
2355  }
2356 
2369  protected function assertBuildSubstringParams( $startPosition, $length ) {
2370  if ( !is_int( $startPosition ) || $startPosition <= 0 ) {
2371  throw new InvalidArgumentException(
2372  '$startPosition must be a positive integer'
2373  );
2374  }
2375  if ( !( is_int( $length ) && $length >= 0 || $length === null ) ) {
2376  throw new InvalidArgumentException(
2377  '$length must be null or an integer greater than or equal to 0'
2378  );
2379  }
2380  }
2381 
2382  public function buildStringCast( $field ) {
2383  // In theory this should work for any standards-compliant
2384  // SQL implementation, although it may not be the best way to do it.
2385  return "CAST( $field AS CHARACTER )";
2386  }
2387 
2388  public function buildIntegerCast( $field ) {
2389  return 'CAST( ' . $field . ' AS INTEGER )';
2390  }
2391 
2392  public function buildSelectSubquery(
2393  $table, $vars, $conds = '', $fname = __METHOD__,
2394  $options = [], $join_conds = []
2395  ) {
2396  return new Subquery(
2397  $this->selectSQLText( $table, $vars, $conds, $fname, $options, $join_conds )
2398  );
2399  }
2400 
2401  public function databasesAreIndependent() {
2402  return false;
2403  }
2404 
2405  final public function selectDB( $db ) {
2406  $this->selectDomain( new DatabaseDomain(
2407  $db,
2408  $this->currentDomain->getSchema(),
2409  $this->currentDomain->getTablePrefix()
2410  ) );
2411 
2412  return true;
2413  }
2414 
2415  final public function selectDomain( $domain ) {
2416  $this->doSelectDomain( DatabaseDomain::newFromId( $domain ) );
2417  }
2418 
2425  protected function doSelectDomain( DatabaseDomain $domain ) {
2426  $this->currentDomain = $domain;
2427  }
2428 
2429  public function getDBname() {
2430  return $this->currentDomain->getDatabase();
2431  }
2432 
2433  public function getServer() {
2434  return $this->server;
2435  }
2436 
2437  public function tableName( $name, $format = 'quoted' ) {
2438  if ( $name instanceof Subquery ) {
2439  throw new DBUnexpectedError(
2440  $this,
2441  __METHOD__ . ': got Subquery instance when expecting a string'
2442  );
2443  }
2444 
2445  # Skip the entire process when we have a string quoted on both ends.
2446  # Note that we check the end so that we will still quote any use of
2447  # use of `database`.table. But won't break things if someone wants
2448  # to query a database table with a dot in the name.
2449  if ( $this->isQuotedIdentifier( $name ) ) {
2450  return $name;
2451  }
2452 
2453  # Lets test for any bits of text that should never show up in a table
2454  # name. Basically anything like JOIN or ON which are actually part of
2455  # SQL queries, but may end up inside of the table value to combine
2456  # sql. Such as how the API is doing.
2457  # Note that we use a whitespace test rather than a \b test to avoid
2458  # any remote case where a word like on may be inside of a table name
2459  # surrounded by symbols which may be considered word breaks.
2460  if ( preg_match( '/(^|\s)(DISTINCT|JOIN|ON|AS)(\s|$)/i', $name ) !== 0 ) {
2461  $this->queryLogger->warning(
2462  __METHOD__ . ": use of subqueries is not supported this way",
2463  [ 'trace' => ( new RuntimeException() )->getTraceAsString() ]
2464  );
2465 
2466  return $name;
2467  }
2468 
2469  # Split database and table into proper variables.
2470  list( $database, $schema, $prefix, $table ) = $this->qualifiedTableComponents( $name );
2471 
2472  # Quote $table and apply the prefix if not quoted.
2473  # $tableName might be empty if this is called from Database::replaceVars()
2474  $tableName = "{$prefix}{$table}";
2475  if ( $format === 'quoted'
2476  && !$this->isQuotedIdentifier( $tableName )
2477  && $tableName !== ''
2478  ) {
2479  $tableName = $this->addIdentifierQuotes( $tableName );
2480  }
2481 
2482  # Quote $schema and $database and merge them with the table name if needed
2483  $tableName = $this->prependDatabaseOrSchema( $schema, $tableName, $format );
2484  $tableName = $this->prependDatabaseOrSchema( $database, $tableName, $format );
2485 
2486  return $tableName;
2487  }
2488 
2495  protected function qualifiedTableComponents( $name ) {
2496  # We reverse the explode so that database.table and table both output the correct table.
2497  $dbDetails = explode( '.', $name, 3 );
2498  if ( count( $dbDetails ) == 3 ) {
2499  list( $database, $schema, $table ) = $dbDetails;
2500  # We don't want any prefix added in this case
2501  $prefix = '';
2502  } elseif ( count( $dbDetails ) == 2 ) {
2503  list( $database, $table ) = $dbDetails;
2504  # We don't want any prefix added in this case
2505  $prefix = '';
2506  # In dbs that support it, $database may actually be the schema
2507  # but that doesn't affect any of the functionality here
2508  $schema = '';
2509  } else {
2510  list( $table ) = $dbDetails;
2511  if ( isset( $this->tableAliases[$table] ) ) {
2512  $database = $this->tableAliases[$table]['dbname'];
2513  $schema = is_string( $this->tableAliases[$table]['schema'] )
2514  ? $this->tableAliases[$table]['schema']
2515  : $this->relationSchemaQualifier();
2516  $prefix = is_string( $this->tableAliases[$table]['prefix'] )
2517  ? $this->tableAliases[$table]['prefix']
2518  : $this->tablePrefix();
2519  } else {
2520  $database = '';
2521  $schema = $this->relationSchemaQualifier(); # Default schema
2522  $prefix = $this->tablePrefix(); # Default prefix
2523  }
2524  }
2525 
2526  return [ $database, $schema, $prefix, $table ];
2527  }
2528 
2535  private function prependDatabaseOrSchema( $namespace, $relation, $format ) {
2536  if ( strlen( $namespace ) ) {
2537  if ( $format === 'quoted' && !$this->isQuotedIdentifier( $namespace ) ) {
2538  $namespace = $this->addIdentifierQuotes( $namespace );
2539  }
2540  $relation = $namespace . '.' . $relation;
2541  }
2542 
2543  return $relation;
2544  }
2545 
2546  public function tableNames( ...$tables ) {
2547  $retVal = [];
2548 
2549  foreach ( $tables as $name ) {
2550  $retVal[$name] = $this->tableName( $name );
2551  }
2552 
2553  return $retVal;
2554  }
2555 
2556  public function tableNamesN( ...$tables ) {
2557  $retVal = [];
2558 
2559  foreach ( $tables as $name ) {
2560  $retVal[] = $this->tableName( $name );
2561  }
2562 
2563  return $retVal;
2564  }
2565 
2577  protected function tableNameWithAlias( $table, $alias = false ) {
2578  if ( is_string( $table ) ) {
2579  $quotedTable = $this->tableName( $table );
2580  } elseif ( $table instanceof Subquery ) {
2581  $quotedTable = (string)$table;
2582  } else {
2583  throw new InvalidArgumentException( "Table must be a string or Subquery" );
2584  }
2585 
2586  if ( $alias === false || $alias === $table ) {
2587  if ( $table instanceof Subquery ) {
2588  throw new InvalidArgumentException( "Subquery table missing alias" );
2589  }
2590 
2591  return $quotedTable;
2592  } else {
2593  return $quotedTable . ' ' . $this->addIdentifierQuotes( $alias );
2594  }
2595  }
2596 
2603  protected function tableNamesWithAlias( $tables ) {
2604  $retval = [];
2605  foreach ( $tables as $alias => $table ) {
2606  if ( is_numeric( $alias ) ) {
2607  $alias = $table;
2608  }
2609  $retval[] = $this->tableNameWithAlias( $table, $alias );
2610  }
2611 
2612  return $retval;
2613  }
2614 
2623  protected function fieldNameWithAlias( $name, $alias = false ) {
2624  if ( !$alias || (string)$alias === (string)$name ) {
2625  return $name;
2626  } else {
2627  return $name . ' AS ' . $this->addIdentifierQuotes( $alias ); // PostgreSQL needs AS
2628  }
2629  }
2630 
2637  protected function fieldNamesWithAlias( $fields ) {
2638  $retval = [];
2639  foreach ( $fields as $alias => $field ) {
2640  if ( is_numeric( $alias ) ) {
2641  $alias = $field;
2642  }
2643  $retval[] = $this->fieldNameWithAlias( $field, $alias );
2644  }
2645 
2646  return $retval;
2647  }
2648 
2660  $tables, $use_index = [], $ignore_index = [], $join_conds = []
2661  ) {
2662  $ret = [];
2663  $retJOIN = [];
2664  $use_index = (array)$use_index;
2665  $ignore_index = (array)$ignore_index;
2666  $join_conds = (array)$join_conds;
2667 
2668  foreach ( $tables as $alias => $table ) {
2669  if ( !is_string( $alias ) ) {
2670  // No alias? Set it equal to the table name
2671  $alias = $table;
2672  }
2673 
2674  if ( is_array( $table ) ) {
2675  // A parenthesized group
2676  if ( count( $table ) > 1 ) {
2677  $joinedTable = '(' .
2679  $table, $use_index, $ignore_index, $join_conds ) . ')';
2680  } else {
2681  // Degenerate case
2682  $innerTable = reset( $table );
2683  $innerAlias = key( $table );
2684  $joinedTable = $this->tableNameWithAlias(
2685  $innerTable,
2686  is_string( $innerAlias ) ? $innerAlias : $innerTable
2687  );
2688  }
2689  } else {
2690  $joinedTable = $this->tableNameWithAlias( $table, $alias );
2691  }
2692 
2693  // Is there a JOIN clause for this table?
2694  if ( isset( $join_conds[$alias] ) ) {
2695  list( $joinType, $conds ) = $join_conds[$alias];
2696  $tableClause = $joinType;
2697  $tableClause .= ' ' . $joinedTable;
2698  if ( isset( $use_index[$alias] ) ) { // has USE INDEX?
2699  $use = $this->useIndexClause( implode( ',', (array)$use_index[$alias] ) );
2700  if ( $use != '' ) {
2701  $tableClause .= ' ' . $use;
2702  }
2703  }
2704  if ( isset( $ignore_index[$alias] ) ) { // has IGNORE INDEX?
2705  $ignore = $this->ignoreIndexClause(
2706  implode( ',', (array)$ignore_index[$alias] ) );
2707  if ( $ignore != '' ) {
2708  $tableClause .= ' ' . $ignore;
2709  }
2710  }
2711  $on = $this->makeList( (array)$conds, self::LIST_AND );
2712  if ( $on != '' ) {
2713  $tableClause .= ' ON (' . $on . ')';
2714  }
2715 
2716  $retJOIN[] = $tableClause;
2717  } elseif ( isset( $use_index[$alias] ) ) {
2718  // Is there an INDEX clause for this table?
2719  $tableClause = $joinedTable;
2720  $tableClause .= ' ' . $this->useIndexClause(
2721  implode( ',', (array)$use_index[$alias] )
2722  );
2723 
2724  $ret[] = $tableClause;
2725  } elseif ( isset( $ignore_index[$alias] ) ) {
2726  // Is there an INDEX clause for this table?
2727  $tableClause = $joinedTable;
2728  $tableClause .= ' ' . $this->ignoreIndexClause(
2729  implode( ',', (array)$ignore_index[$alias] )
2730  );
2731 
2732  $ret[] = $tableClause;
2733  } else {
2734  $tableClause = $joinedTable;
2735 
2736  $ret[] = $tableClause;
2737  }
2738  }
2739 
2740  // We can't separate explicit JOIN clauses with ',', use ' ' for those
2741  $implicitJoins = implode( ',', $ret );
2742  $explicitJoins = implode( ' ', $retJOIN );
2743 
2744  // Compile our final table clause
2745  return implode( ' ', [ $implicitJoins, $explicitJoins ] );
2746  }
2747 
2754  protected function indexName( $index ) {
2755  return $this->indexAliases[$index] ?? $index;
2756  }
2757 
2758  public function addQuotes( $s ) {
2759  if ( $s instanceof Blob ) {
2760  $s = $s->fetch();
2761  }
2762  if ( $s === null ) {
2763  return 'NULL';
2764  } elseif ( is_bool( $s ) ) {
2765  return (int)$s;
2766  } else {
2767  # This will also quote numeric values. This should be harmless,
2768  # and protects against weird problems that occur when they really
2769  # _are_ strings such as article titles and string->number->string
2770  # conversion is not 1:1.
2771  return "'" . $this->strencode( $s ) . "'";
2772  }
2773  }
2774 
2775  public function addIdentifierQuotes( $s ) {
2776  return '"' . str_replace( '"', '""', $s ) . '"';
2777  }
2778 
2788  public function isQuotedIdentifier( $name ) {
2789  return $name[0] == '"' && substr( $name, -1, 1 ) == '"';
2790  }
2791 
2797  protected function escapeLikeInternal( $s, $escapeChar = '`' ) {
2798  return str_replace( [ $escapeChar, '%', '_' ],
2799  [ "{$escapeChar}{$escapeChar}", "{$escapeChar}%", "{$escapeChar}_" ],
2800  $s );
2801  }
2802 
2803  public function buildLike( $param, ...$params ) {
2804  if ( is_array( $param ) ) {
2805  $params = $param;
2806  } else {
2807  $params = func_get_args();
2808  }
2809 
2810  $s = '';
2811 
2812  // We use ` instead of \ as the default LIKE escape character, since addQuotes()
2813  // may escape backslashes, creating problems of double escaping. The `
2814  // character has good cross-DBMS compatibility, avoiding special operators
2815  // in MS SQL like ^ and %
2816  $escapeChar = '`';
2817 
2818  foreach ( $params as $value ) {
2819  if ( $value instanceof LikeMatch ) {
2820  $s .= $value->toString();
2821  } else {
2822  $s .= $this->escapeLikeInternal( $value, $escapeChar );
2823  }
2824  }
2825 
2826  return ' LIKE ' .
2827  $this->addQuotes( $s ) . ' ESCAPE ' . $this->addQuotes( $escapeChar ) . ' ';
2828  }
2829 
2830  public function anyChar() {
2831  return new LikeMatch( '_' );
2832  }
2833 
2834  public function anyString() {
2835  return new LikeMatch( '%' );
2836  }
2837 
2838  public function nextSequenceValue( $seqName ) {
2839  return null;
2840  }
2841 
2852  public function useIndexClause( $index ) {
2853  return '';
2854  }
2855 
2866  public function ignoreIndexClause( $index ) {
2867  return '';
2868  }
2869 
2870  public function replace( $table, $uniqueIndexes, $rows, $fname = __METHOD__ ) {
2871  if ( count( $rows ) == 0 ) {
2872  return;
2873  }
2874 
2875  $uniqueIndexes = (array)$uniqueIndexes;
2876  // Single row case
2877  if ( !is_array( reset( $rows ) ) ) {
2878  $rows = [ $rows ];
2879  }
2880 
2881  try {
2882  $this->startAtomic( $fname, self::ATOMIC_CANCELABLE );
2883  $affectedRowCount = 0;
2884  foreach ( $rows as $row ) {
2885  // Delete rows which collide with this one
2886  $indexWhereClauses = [];
2887  foreach ( $uniqueIndexes as $index ) {
2888  $indexColumns = (array)$index;
2889  $indexRowValues = array_intersect_key( $row, array_flip( $indexColumns ) );
2890  if ( count( $indexRowValues ) != count( $indexColumns ) ) {
2891  throw new DBUnexpectedError(
2892  $this,
2893  'New record does not provide all values for unique key (' .
2894  implode( ', ', $indexColumns ) . ')'
2895  );
2896  } elseif ( in_array( null, $indexRowValues, true ) ) {
2897  throw new DBUnexpectedError(
2898  $this,
2899  'New record has a null value for unique key (' .
2900  implode( ', ', $indexColumns ) . ')'
2901  );
2902  }
2903  $indexWhereClauses[] = $this->makeList( $indexRowValues, LIST_AND );
2904  }
2905 
2906  if ( $indexWhereClauses ) {
2907  $this->delete( $table, $this->makeList( $indexWhereClauses, LIST_OR ), $fname );
2908  $affectedRowCount += $this->affectedRows();
2909  }
2910 
2911  // Now insert the row
2912  $this->insert( $table, $row, $fname );
2913  $affectedRowCount += $this->affectedRows();
2914  }
2915  $this->endAtomic( $fname );
2916  $this->affectedRowCount = $affectedRowCount;
2917  } catch ( Exception $e ) {
2918  $this->cancelAtomic( $fname );
2919  throw $e;
2920  }
2921  }
2922 
2931  protected function nativeReplace( $table, $rows, $fname ) {
2932  $table = $this->tableName( $table );
2933 
2934  # Single row case
2935  if ( !is_array( reset( $rows ) ) ) {
2936  $rows = [ $rows ];
2937  }
2938 
2939  $sql = "REPLACE INTO $table (" . implode( ',', array_keys( $rows[0] ) ) . ') VALUES ';
2940  $first = true;
2941 
2942  foreach ( $rows as $row ) {
2943  if ( $first ) {
2944  $first = false;
2945  } else {
2946  $sql .= ',';
2947  }
2948 
2949  $sql .= '(' . $this->makeList( $row ) . ')';
2950  }
2951 
2952  $this->query( $sql, $fname );
2953  }
2954 
2955  public function upsert( $table, array $rows, $uniqueIndexes, array $set,
2956  $fname = __METHOD__
2957  ) {
2958  if ( $rows === [] ) {
2959  return true; // nothing to do
2960  }
2961 
2962  $uniqueIndexes = (array)$uniqueIndexes;
2963  if ( !is_array( reset( $rows ) ) ) {
2964  $rows = [ $rows ];
2965  }
2966 
2967  if ( count( $uniqueIndexes ) ) {
2968  $clauses = []; // list WHERE clauses that each identify a single row
2969  foreach ( $rows as $row ) {
2970  foreach ( $uniqueIndexes as $index ) {
2971  $index = is_array( $index ) ? $index : [ $index ]; // columns
2972  $rowKey = []; // unique key to this row
2973  foreach ( $index as $column ) {
2974  $rowKey[$column] = $row[$column];
2975  }
2976  $clauses[] = $this->makeList( $rowKey, self::LIST_AND );
2977  }
2978  }
2979  $where = [ $this->makeList( $clauses, self::LIST_OR ) ];
2980  } else {
2981  $where = false;
2982  }
2983 
2984  $affectedRowCount = 0;
2985  try {
2986  $this->startAtomic( $fname, self::ATOMIC_CANCELABLE );
2987  # Update any existing conflicting row(s)
2988  if ( $where !== false ) {
2989  $this->update( $table, $set, $where, $fname );
2990  $affectedRowCount += $this->affectedRows();
2991  }
2992  # Now insert any non-conflicting row(s)
2993  $this->insert( $table, $rows, $fname, [ 'IGNORE' ] );
2994  $affectedRowCount += $this->affectedRows();
2995  $this->endAtomic( $fname );
2996  $this->affectedRowCount = $affectedRowCount;
2997  } catch ( Exception $e ) {
2998  $this->cancelAtomic( $fname );
2999  throw $e;
3000  }
3001 
3002  return true;
3003  }
3004 
3005  public function deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds,
3006  $fname = __METHOD__
3007  ) {
3008  if ( !$conds ) {
3009  throw new DBUnexpectedError( $this, __METHOD__ . ' called with empty $conds' );
3010  }
3011 
3012  $delTable = $this->tableName( $delTable );
3013  $joinTable = $this->tableName( $joinTable );
3014  $sql = "DELETE FROM $delTable WHERE $delVar IN (SELECT $joinVar FROM $joinTable ";
3015  if ( $conds != '*' ) {
3016  $sql .= 'WHERE ' . $this->makeList( $conds, self::LIST_AND );
3017  }
3018  $sql .= ')';
3019 
3020  $this->query( $sql, $fname );
3021  }
3022 
3023  public function textFieldSize( $table, $field ) {
3024  $table = $this->tableName( $table );
3025  $sql = "SHOW COLUMNS FROM $table LIKE \"$field\"";
3026  $res = $this->query( $sql, __METHOD__ );
3027  $row = $this->fetchObject( $res );
3028 
3029  $m = [];
3030 
3031  if ( preg_match( '/\((.*)\)/', $row->Type, $m ) ) {
3032  $size = $m[1];
3033  } else {
3034  $size = -1;
3035  }
3036 
3037  return $size;
3038  }
3039 
3040  public function delete( $table, $conds, $fname = __METHOD__ ) {
3041  if ( !$conds ) {
3042  throw new DBUnexpectedError( $this, __METHOD__ . ' called with no conditions' );
3043  }
3044 
3045  $table = $this->tableName( $table );
3046  $sql = "DELETE FROM $table";
3047 
3048  if ( $conds != '*' ) {
3049  if ( is_array( $conds ) ) {
3050  $conds = $this->makeList( $conds, self::LIST_AND );
3051  }
3052  $sql .= ' WHERE ' . $conds;
3053  }
3054 
3055  $this->query( $sql, $fname );
3056 
3057  return true;
3058  }
3059 
3060  final public function insertSelect(
3061  $destTable, $srcTable, $varMap, $conds,
3062  $fname = __METHOD__, $insertOptions = [], $selectOptions = [], $selectJoinConds = []
3063  ) {
3064  static $hints = [ 'NO_AUTO_COLUMNS' ];
3065 
3066  $insertOptions = (array)$insertOptions;
3067  $selectOptions = (array)$selectOptions;
3068 
3069  if ( $this->cliMode && $this->isInsertSelectSafe( $insertOptions, $selectOptions ) ) {
3070  // For massive migrations with downtime, we don't want to select everything
3071  // into memory and OOM, so do all this native on the server side if possible.
3072  $this->nativeInsertSelect(
3073  $destTable,
3074  $srcTable,
3075  $varMap,
3076  $conds,
3077  $fname,
3078  array_diff( $insertOptions, $hints ),
3079  $selectOptions,
3080  $selectJoinConds
3081  );
3082  } else {
3083  $this->nonNativeInsertSelect(
3084  $destTable,
3085  $srcTable,
3086  $varMap,
3087  $conds,
3088  $fname,
3089  array_diff( $insertOptions, $hints ),
3090  $selectOptions,
3091  $selectJoinConds
3092  );
3093  }
3094 
3095  return true;
3096  }
3097 
3104  protected function isInsertSelectSafe( array $insertOptions, array $selectOptions ) {
3105  return true;
3106  }
3107 
3122  protected function nonNativeInsertSelect( $destTable, $srcTable, $varMap, $conds,
3123  $fname = __METHOD__,
3124  $insertOptions = [], $selectOptions = [], $selectJoinConds = []
3125  ) {
3126  // For web requests, do a locking SELECT and then INSERT. This puts the SELECT burden
3127  // on only the master (without needing row-based-replication). It also makes it easy to
3128  // know how big the INSERT is going to be.
3129  $fields = [];
3130  foreach ( $varMap as $dstColumn => $sourceColumnOrSql ) {
3131  $fields[] = $this->fieldNameWithAlias( $sourceColumnOrSql, $dstColumn );
3132  }
3133  $selectOptions[] = 'FOR UPDATE';
3134  $res = $this->select(
3135  $srcTable, implode( ',', $fields ), $conds, $fname, $selectOptions, $selectJoinConds
3136  );
3137  if ( !$res ) {
3138  return;
3139  }
3140 
3141  try {
3142  $affectedRowCount = 0;
3143  $this->startAtomic( $fname, self::ATOMIC_CANCELABLE );
3144  $rows = [];
3145  $ok = true;
3146  foreach ( $res as $row ) {
3147  $rows[] = (array)$row;
3148 
3149  // Avoid inserts that are too huge
3150  if ( count( $rows ) >= $this->nonNativeInsertSelectBatchSize ) {
3151  $ok = $this->insert( $destTable, $rows, $fname, $insertOptions );
3152  if ( !$ok ) {
3153  break;
3154  }
3155  $affectedRowCount += $this->affectedRows();
3156  $rows = [];
3157  }
3158  }
3159  if ( $rows && $ok ) {
3160  $ok = $this->insert( $destTable, $rows, $fname, $insertOptions );
3161  if ( $ok ) {
3162  $affectedRowCount += $this->affectedRows();
3163  }
3164  }
3165  if ( $ok ) {
3166  $this->endAtomic( $fname );
3167  $this->affectedRowCount = $affectedRowCount;
3168  } else {
3169  $this->cancelAtomic( $fname );
3170  }
3171  } catch ( Exception $e ) {
3172  $this->cancelAtomic( $fname );
3173  throw $e;
3174  }
3175  }
3176 
3191  protected function nativeInsertSelect( $destTable, $srcTable, $varMap, $conds,
3192  $fname = __METHOD__,
3193  $insertOptions = [], $selectOptions = [], $selectJoinConds = []
3194  ) {
3195  $destTable = $this->tableName( $destTable );
3196 
3197  if ( !is_array( $insertOptions ) ) {
3198  $insertOptions = [ $insertOptions ];
3199  }
3200 
3201  $insertOptions = $this->makeInsertOptions( $insertOptions );
3202 
3203  $selectSql = $this->selectSQLText(
3204  $srcTable,
3205  array_values( $varMap ),
3206  $conds,
3207  $fname,
3208  $selectOptions,
3209  $selectJoinConds
3210  );
3211 
3212  $sql = "INSERT $insertOptions" .
3213  " INTO $destTable (" . implode( ',', array_keys( $varMap ) ) . ') ' .
3214  $selectSql;
3215 
3216  $this->query( $sql, $fname );
3217  }
3218 
3219  public function limitResult( $sql, $limit, $offset = false ) {
3220  if ( !is_numeric( $limit ) ) {
3221  throw new DBUnexpectedError(
3222  $this,
3223  "Invalid non-numeric limit passed to " . __METHOD__
3224  );
3225  }
3226  // This version works in MySQL and SQLite. It will very likely need to be
3227  // overridden for most other RDBMS subclasses.
3228  return "$sql LIMIT "
3229  . ( ( is_numeric( $offset ) && $offset != 0 ) ? "{$offset}," : "" )
3230  . "{$limit} ";
3231  }
3232 
3233  public function unionSupportsOrderAndLimit() {
3234  return true; // True for almost every DB supported
3235  }
3236 
3237  public function unionQueries( $sqls, $all ) {
3238  $glue = $all ? ') UNION ALL (' : ') UNION (';
3239 
3240  return '(' . implode( $glue, $sqls ) . ')';
3241  }
3242 
3244  $table, $vars, array $permute_conds, $extra_conds = '', $fname = __METHOD__,
3245  $options = [], $join_conds = []
3246  ) {
3247  // First, build the Cartesian product of $permute_conds
3248  $conds = [ [] ];
3249  foreach ( $permute_conds as $field => $values ) {
3250  if ( !$values ) {
3251  // Skip empty $values
3252  continue;
3253  }
3254  $values = array_unique( $values ); // For sanity
3255  $newConds = [];
3256  foreach ( $conds as $cond ) {
3257  foreach ( $values as $value ) {
3258  $cond[$field] = $value;
3259  $newConds[] = $cond; // Arrays are by-value, not by-reference, so this works
3260  }
3261  }
3262  $conds = $newConds;
3263  }
3264 
3265  $extra_conds = $extra_conds === '' ? [] : (array)$extra_conds;
3266 
3267  // If there's just one condition and no subordering, hand off to
3268  // selectSQLText directly.
3269  if ( count( $conds ) === 1 &&
3270  ( !isset( $options['INNER ORDER BY'] ) || !$this->unionSupportsOrderAndLimit() )
3271  ) {
3272  return $this->selectSQLText(
3273  $table, $vars, $conds[0] + $extra_conds, $fname, $options, $join_conds
3274  );
3275  }
3276 
3277  // Otherwise, we need to pull out the order and limit to apply after
3278  // the union. Then build the SQL queries for each set of conditions in
3279  // $conds. Then union them together (using UNION ALL, because the
3280  // product *should* already be distinct).
3281  $orderBy = $this->makeOrderBy( $options );
3282  $limit = $options['LIMIT'] ?? null;
3283  $offset = $options['OFFSET'] ?? false;
3284  $all = empty( $options['NOTALL'] ) && !in_array( 'NOTALL', $options );
3285  if ( !$this->unionSupportsOrderAndLimit() ) {
3286  unset( $options['ORDER BY'], $options['LIMIT'], $options['OFFSET'] );
3287  } else {
3288  if ( array_key_exists( 'INNER ORDER BY', $options ) ) {
3289  $options['ORDER BY'] = $options['INNER ORDER BY'];
3290  }
3291  if ( $limit !== null && is_numeric( $offset ) && $offset != 0 ) {
3292  // We need to increase the limit by the offset rather than
3293  // using the offset directly, otherwise it'll skip incorrectly
3294  // in the subqueries.
3295  $options['LIMIT'] = $limit + $offset;
3296  unset( $options['OFFSET'] );
3297  }
3298  }
3299 
3300  $sqls = [];
3301  foreach ( $conds as $cond ) {
3302  $sqls[] = $this->selectSQLText(
3303  $table, $vars, $cond + $extra_conds, $fname, $options, $join_conds
3304  );
3305  }
3306  $sql = $this->unionQueries( $sqls, $all ) . $orderBy;
3307  if ( $limit !== null ) {
3308  $sql = $this->limitResult( $sql, $limit, $offset );
3309  }
3310 
3311  return $sql;
3312  }
3313 
3314  public function conditional( $cond, $trueVal, $falseVal ) {
3315  if ( is_array( $cond ) ) {
3316  $cond = $this->makeList( $cond, self::LIST_AND );
3317  }
3318 
3319  return " (CASE WHEN $cond THEN $trueVal ELSE $falseVal END) ";
3320  }
3321 
3322  public function strreplace( $orig, $old, $new ) {
3323  return "REPLACE({$orig}, {$old}, {$new})";
3324  }
3325 
3326  public function getServerUptime() {
3327  return 0;
3328  }
3329 
3330  public function wasDeadlock() {
3331  return false;
3332  }
3333 
3334  public function wasLockTimeout() {
3335  return false;
3336  }
3337 
3338  public function wasConnectionLoss() {
3339  return $this->wasConnectionError( $this->lastErrno() );
3340  }
3341 
3342  public function wasReadOnlyError() {
3343  return false;
3344  }
3345 
3346  public function wasErrorReissuable() {
3347  return (
3348  $this->wasDeadlock() ||
3349  $this->wasLockTimeout() ||
3350  $this->wasConnectionLoss()
3351  );
3352  }
3353 
3360  public function wasConnectionError( $errno ) {
3361  return false;
3362  }
3363 
3370  protected function wasKnownStatementRollbackError() {
3371  return false; // don't know; it could have caused a transaction rollback
3372  }
3373 
3374  public function deadlockLoop( ...$args ) {
3375  $function = array_shift( $args );
3376  $tries = self::$DEADLOCK_TRIES;
3377 
3378  $this->begin( __METHOD__ );
3379 
3380  $retVal = null;
3382  $e = null;
3383  do {
3384  try {
3385  $retVal = $function( ...$args );
3386  break;
3387  } catch ( DBQueryError $e ) {
3388  if ( $this->wasDeadlock() ) {
3389  // Retry after a randomized delay
3390  usleep( mt_rand( self::$DEADLOCK_DELAY_MIN, self::$DEADLOCK_DELAY_MAX ) );
3391  } else {
3392  // Throw the error back up
3393  throw $e;
3394  }
3395  }
3396  } while ( --$tries > 0 );
3397 
3398  if ( $tries <= 0 ) {
3399  // Too many deadlocks; give up
3400  $this->rollback( __METHOD__ );
3401  throw $e;
3402  } else {
3403  $this->commit( __METHOD__ );
3404 
3405  return $retVal;
3406  }
3407  }
3408 
3409  public function masterPosWait( DBMasterPos $pos, $timeout ) {
3410  # Real waits are implemented in the subclass.
3411  return 0;
3412  }
3413 
3414  public function getReplicaPos() {
3415  # Stub
3416  return false;
3417  }
3418 
3419  public function getMasterPos() {
3420  # Stub
3421  return false;
3422  }
3423 
3424  public function serverIsReadOnly() {
3425  return false;
3426  }
3427 
3428  final public function onTransactionResolution( callable $callback, $fname = __METHOD__ ) {
3429  if ( !$this->trxLevel() ) {
3430  throw new DBUnexpectedError( $this, "No transaction is active" );
3431  }
3432  $this->trxEndCallbacks[] = [ $callback, $fname, $this->currentAtomicSectionId() ];
3433  }
3434 
3435  final public function onTransactionCommitOrIdle( callable $callback, $fname = __METHOD__ ) {
3436  if ( !$this->trxLevel() && $this->getTransactionRoundId() ) {
3437  // Start an implicit transaction similar to how query() does
3438  $this->begin( __METHOD__, self::TRANSACTION_INTERNAL );
3439  $this->trxAutomatic = true;
3440  }
3441 
3442  $this->trxIdleCallbacks[] = [ $callback, $fname, $this->currentAtomicSectionId() ];
3443  if ( !$this->trxLevel() ) {
3444  $this->runOnTransactionIdleCallbacks( self::TRIGGER_IDLE );
3445  }
3446  }
3447 
3448  final public function onTransactionIdle( callable $callback, $fname = __METHOD__ ) {
3449  $this->onTransactionCommitOrIdle( $callback, $fname );
3450  }
3451 
3452  final public function onTransactionPreCommitOrIdle( callable $callback, $fname = __METHOD__ ) {
3453  if ( !$this->trxLevel() && $this->getTransactionRoundId() ) {
3454  // Start an implicit transaction similar to how query() does
3455  $this->begin( __METHOD__, self::TRANSACTION_INTERNAL );
3456  $this->trxAutomatic = true;
3457  }
3458 
3459  if ( $this->trxLevel() ) {
3460  $this->trxPreCommitCallbacks[] = [ $callback, $fname, $this->currentAtomicSectionId() ];
3461  } else {
3462  // No transaction is active nor will start implicitly, so make one for this callback
3463  $this->startAtomic( __METHOD__, self::ATOMIC_CANCELABLE );
3464  try {
3465  $callback( $this );
3466  $this->endAtomic( __METHOD__ );
3467  } catch ( Exception $e ) {
3468  $this->cancelAtomic( __METHOD__ );
3469  throw $e;
3470  }
3471  }
3472  }
3473 
3474  final public function onAtomicSectionCancel( callable $callback, $fname = __METHOD__ ) {
3475  if ( !$this->trxLevel() || !$this->trxAtomicLevels ) {
3476  throw new DBUnexpectedError( $this, "No atomic section is open (got $fname)" );
3477  }
3478  $this->trxSectionCancelCallbacks[] = [ $callback, $fname, $this->currentAtomicSectionId() ];
3479  }
3480 
3484  private function currentAtomicSectionId() {
3485  if ( $this->trxLevel() && $this->trxAtomicLevels ) {
3486  $levelInfo = end( $this->trxAtomicLevels );
3487 
3488  return $levelInfo[1];
3489  }
3490 
3491  return null;
3492  }
3493 
3502  ) {
3503  foreach ( $this->trxPreCommitCallbacks as $key => $info ) {
3504  if ( $info[2] === $old ) {
3505  $this->trxPreCommitCallbacks[$key][2] = $new;
3506  }
3507  }
3508  foreach ( $this->trxIdleCallbacks as $key => $info ) {
3509  if ( $info[2] === $old ) {
3510  $this->trxIdleCallbacks[$key][2] = $new;
3511  }
3512  }
3513  foreach ( $this->trxEndCallbacks as $key => $info ) {
3514  if ( $info[2] === $old ) {
3515  $this->trxEndCallbacks[$key][2] = $new;
3516  }
3517  }
3518  foreach ( $this->trxSectionCancelCallbacks as $key => $info ) {
3519  if ( $info[2] === $old ) {
3520  $this->trxSectionCancelCallbacks[$key][2] = $new;
3521  }
3522  }
3523  }
3524 
3544  private function modifyCallbacksForCancel(
3545  array $sectionIds, AtomicSectionIdentifier $newSectionId = null
3546  ) {
3547  // Cancel the "on commit" callbacks owned by this savepoint
3548  $this->trxIdleCallbacks = array_filter(
3549  $this->trxIdleCallbacks,
3550  function ( $entry ) use ( $sectionIds ) {
3551  return !in_array( $entry[2], $sectionIds, true );
3552  }
3553  );
3554  $this->trxPreCommitCallbacks = array_filter(
3555  $this->trxPreCommitCallbacks,
3556  function ( $entry ) use ( $sectionIds ) {
3557  return !in_array( $entry[2], $sectionIds, true );
3558  }
3559  );
3560  // Make "on resolution" callbacks owned by this savepoint to perceive a rollback
3561  foreach ( $this->trxEndCallbacks as $key => $entry ) {
3562  if ( in_array( $entry[2], $sectionIds, true ) ) {
3563  $callback = $entry[0];
3564  $this->trxEndCallbacks[$key][0] = function () use ( $callback ) {
3565  return $callback( self::TRIGGER_ROLLBACK, $this );
3566  };
3567  // This "on resolution" callback no longer belongs to a section.
3568  $this->trxEndCallbacks[$key][2] = null;
3569  }
3570  }
3571  // Hoist callback ownership for section cancel callbacks to the new top section
3572  foreach ( $this->trxSectionCancelCallbacks as $key => $entry ) {
3573  if ( in_array( $entry[2], $sectionIds, true ) ) {
3574  $this->trxSectionCancelCallbacks[$key][2] = $newSectionId;
3575  }
3576  }
3577  }
3578 
3579  final public function setTransactionListener( $name, callable $callback = null ) {
3580  if ( $callback ) {
3581  $this->trxRecurringCallbacks[$name] = $callback;
3582  } else {
3583  unset( $this->trxRecurringCallbacks[$name] );
3584  }
3585  }
3586 
3595  final public function setTrxEndCallbackSuppression( $suppress ) {
3596  $this->trxEndCallbacksSuppressed = $suppress;
3597  }
3598 
3609  public function runOnTransactionIdleCallbacks( $trigger ) {
3610  if ( $this->trxLevel() ) { // sanity
3611  throw new DBUnexpectedError( $this, __METHOD__ . ': a transaction is still open' );
3612  }
3613 
3614  if ( $this->trxEndCallbacksSuppressed ) {
3615  return 0;
3616  }
3617 
3618  $count = 0;
3619  $autoTrx = $this->getFlag( self::DBO_TRX ); // automatic begin() enabled?
3621  $e = null; // first exception
3622  do { // callbacks may add callbacks :)
3623  $callbacks = array_merge(
3624  $this->trxIdleCallbacks,
3625  $this->trxEndCallbacks // include "transaction resolution" callbacks
3626  );
3627  $this->trxIdleCallbacks = []; // consumed (and recursion guard)
3628  $this->trxEndCallbacks = []; // consumed (recursion guard)
3629 
3630  // Only run trxSectionCancelCallbacks on rollback, not commit.
3631  // But always consume them.
3632  if ( $trigger === self::TRIGGER_ROLLBACK ) {
3633  $callbacks = array_merge( $callbacks, $this->trxSectionCancelCallbacks );
3634  }
3635  $this->trxSectionCancelCallbacks = []; // consumed (recursion guard)
3636 
3637  foreach ( $callbacks as $callback ) {
3638  ++$count;
3639  list( $phpCallback ) = $callback;
3640  $this->clearFlag( self::DBO_TRX ); // make each query its own transaction
3641  try {
3642  // @phan-suppress-next-line PhanParamTooManyCallable
3643  call_user_func( $phpCallback, $trigger, $this );
3644  } catch ( Exception $ex ) {
3645  call_user_func( $this->errorLogger, $ex );
3646  $e = $e ?: $ex;
3647  // Some callbacks may use startAtomic/endAtomic, so make sure
3648  // their transactions are ended so other callbacks don't fail
3649  if ( $this->trxLevel() ) {
3650  $this->rollback( __METHOD__, self::FLUSHING_INTERNAL );
3651  }
3652  } finally {
3653  if ( $autoTrx ) {
3654  $this->setFlag( self::DBO_TRX ); // restore automatic begin()
3655  } else {
3656  $this->clearFlag( self::DBO_TRX ); // restore auto-commit
3657  }
3658  }
3659  }
3660  } while ( count( $this->trxIdleCallbacks ) );
3661 
3662  if ( $e instanceof Exception ) {
3663  throw $e; // re-throw any first exception
3664  }
3665 
3666  return $count;
3667  }
3668 
3679  $count = 0;
3680 
3681  $e = null; // first exception
3682  do { // callbacks may add callbacks :)
3683  $callbacks = $this->trxPreCommitCallbacks;
3684  $this->trxPreCommitCallbacks = []; // consumed (and recursion guard)
3685  foreach ( $callbacks as $callback ) {
3686  try {
3687  ++$count;
3688  list( $phpCallback ) = $callback;
3689  // @phan-suppress-next-line PhanUndeclaredInvokeInCallable
3690  $phpCallback( $this );
3691  } catch ( Exception $ex ) {
3692  ( $this->errorLogger )( $ex );
3693  $e = $e ?: $ex;
3694  }
3695  }
3696  } while ( count( $this->trxPreCommitCallbacks ) );
3697 
3698  if ( $e instanceof Exception ) {
3699  throw $e; // re-throw any first exception
3700  }
3701 
3702  return $count;
3703  }
3704 
3713  $trigger, array $sectionIds = null
3714  ) {
3716  $e = null; // first exception
3717 
3718  $notCancelled = [];
3719  do {
3720  $callbacks = $this->trxSectionCancelCallbacks;
3721  $this->trxSectionCancelCallbacks = []; // consumed (recursion guard)
3722  foreach ( $callbacks as $entry ) {
3723  if ( $sectionIds === null || in_array( $entry[2], $sectionIds, true ) ) {
3724  try {
3725  // @phan-suppress-next-line PhanUndeclaredInvokeInCallable
3726  $entry[0]( $trigger, $this );
3727  } catch ( Exception $ex ) {
3728  ( $this->errorLogger )( $ex );
3729  $e = $e ?: $ex;
3730  } catch ( Throwable $ex ) {
3731  // @todo: Log?
3732  $e = $e ?: $ex;
3733  }
3734  } else {
3735  $notCancelled[] = $entry;
3736  }
3737  }
3738  } while ( count( $this->trxSectionCancelCallbacks ) );
3739  $this->trxSectionCancelCallbacks = $notCancelled;
3740 
3741  if ( $e !== null ) {
3742  throw $e; // re-throw any first Exception/Throwable
3743  }
3744  }
3745 
3755  public function runTransactionListenerCallbacks( $trigger ) {
3756  if ( $this->trxEndCallbacksSuppressed ) {
3757  return;
3758  }
3759 
3761  $e = null; // first exception
3762 
3763  foreach ( $this->trxRecurringCallbacks as $phpCallback ) {
3764  try {
3765  $phpCallback( $trigger, $this );
3766  } catch ( Exception $ex ) {
3767  ( $this->errorLogger )( $ex );
3768  $e = $e ?: $ex;
3769  }
3770  }
3771 
3772  if ( $e instanceof Exception ) {
3773  throw $e; // re-throw any first exception
3774  }
3775  }
3776 
3787  protected function doSavepoint( $identifier, $fname ) {
3788  $this->query( 'SAVEPOINT ' . $this->addIdentifierQuotes( $identifier ), $fname );
3789  }
3790 
3801  protected function doReleaseSavepoint( $identifier, $fname ) {
3802  $this->query( 'RELEASE SAVEPOINT ' . $this->addIdentifierQuotes( $identifier ), $fname );
3803  }
3804 
3815  protected function doRollbackToSavepoint( $identifier, $fname ) {
3816  $this->query( 'ROLLBACK TO SAVEPOINT ' . $this->addIdentifierQuotes( $identifier ), $fname );
3817  }
3818 
3823  private function nextSavepointId( $fname ) {
3824  $savepointId = self::$SAVEPOINT_PREFIX . ++$this->trxAtomicCounter;
3825  if ( strlen( $savepointId ) > 30 ) {
3826  // 30 == Oracle's identifier length limit (pre 12c)
3827  // With a 22 character prefix, that puts the highest number at 99999999.
3828  throw new DBUnexpectedError(
3829  $this,
3830  'There have been an excessively large number of atomic sections in a transaction'
3831  . " started by $this->trxFname (at $fname)"
3832  );
3833  }
3834 
3835  return $savepointId;
3836  }
3837 
3838  final public function startAtomic(
3839  $fname = __METHOD__, $cancelable = self::ATOMIC_NOT_CANCELABLE
3840  ) {
3841  $savepointId = $cancelable === self::ATOMIC_CANCELABLE ? self::$NOT_APPLICABLE : null;
3842 
3843  if ( !$this->trxLevel() ) {
3844  $this->begin( $fname, self::TRANSACTION_INTERNAL ); // sets trxAutomatic
3845  // If DBO_TRX is set, a series of startAtomic/endAtomic pairs will result
3846  // in all changes being in one transaction to keep requests transactional.
3847  if ( $this->getFlag( self::DBO_TRX ) ) {
3848  // Since writes could happen in between the topmost atomic sections as part
3849  // of the transaction, those sections will need savepoints.
3850  $savepointId = $this->nextSavepointId( $fname );
3851  $this->doSavepoint( $savepointId, $fname );
3852  } else {
3853  $this->trxAutomaticAtomic = true;
3854  }
3855  } elseif ( $cancelable === self::ATOMIC_CANCELABLE ) {
3856  $savepointId = $this->nextSavepointId( $fname );
3857  $this->doSavepoint( $savepointId, $fname );
3858  }
3859 
3860  $sectionId = new AtomicSectionIdentifier;
3861  $this->trxAtomicLevels[] = [ $fname, $sectionId, $savepointId ];
3862  $this->queryLogger->debug( 'startAtomic: entering level ' .
3863  ( count( $this->trxAtomicLevels ) - 1 ) . " ($fname)" );
3864 
3865  return $sectionId;
3866  }
3867 
3868  final public function endAtomic( $fname = __METHOD__ ) {
3869  if ( !$this->trxLevel() || !$this->trxAtomicLevels ) {
3870  throw new DBUnexpectedError( $this, "No atomic section is open (got $fname)" );
3871  }
3872 
3873  // Check if the current section matches $fname
3874  $pos = count( $this->trxAtomicLevels ) - 1;
3875  list( $savedFname, $sectionId, $savepointId ) = $this->trxAtomicLevels[$pos];
3876  $this->queryLogger->debug( "endAtomic: leaving level $pos ($fname)" );
3877 
3878  if ( $savedFname !== $fname ) {
3879  throw new DBUnexpectedError(
3880  $this,
3881  "Invalid atomic section ended (got $fname but expected $savedFname)"
3882  );
3883  }
3884 
3885  // Remove the last section (no need to re-index the array)
3886  array_pop( $this->trxAtomicLevels );
3887 
3888  if ( !$this->trxAtomicLevels && $this->trxAutomaticAtomic ) {
3889  $this->commit( $fname, self::FLUSHING_INTERNAL );
3890  } elseif ( $savepointId !== null && $savepointId !== self::$NOT_APPLICABLE ) {
3891  $this->doReleaseSavepoint( $savepointId, $fname );
3892  }
3893 
3894  // Hoist callback ownership for callbacks in the section that just ended;
3895  // all callbacks should have an owner that is present in trxAtomicLevels.
3896  $currentSectionId = $this->currentAtomicSectionId();
3897  if ( $currentSectionId ) {
3898  $this->reassignCallbacksForSection( $sectionId, $currentSectionId );
3899  }
3900  }
3901 
3902  final public function cancelAtomic(
3903  $fname = __METHOD__, AtomicSectionIdentifier $sectionId = null
3904  ) {
3905  if ( !$this->trxLevel() || !$this->trxAtomicLevels ) {
3906  throw new DBUnexpectedError( $this, "No atomic section is open (got $fname)" );
3907  }
3908 
3909  $excisedIds = [];
3910  $newTopSection = $this->currentAtomicSectionId();
3911  try {
3912  $excisedFnames = [];
3913  if ( $sectionId !== null ) {
3914  // Find the (last) section with the given $sectionId
3915  $pos = -1;
3916  foreach ( $this->trxAtomicLevels as $i => list( $asFname, $asId, $spId ) ) {
3917  if ( $asId === $sectionId ) {
3918  $pos = $i;
3919  }
3920  }
3921  if ( $pos < 0 ) {
3922  throw new DBUnexpectedError( $this, "Atomic section not found (for $fname)" );
3923  }
3924  // Remove all descendant sections and re-index the array
3925  $len = count( $this->trxAtomicLevels );
3926  for ( $i = $pos + 1; $i < $len; ++$i ) {
3927  $excisedFnames[] = $this->trxAtomicLevels[$i][0];
3928  $excisedIds[] = $this->trxAtomicLevels[$i][1];
3929  }
3930  $this->trxAtomicLevels = array_slice( $this->trxAtomicLevels, 0, $pos + 1 );
3931  $newTopSection = $this->currentAtomicSectionId();
3932  }
3933 
3934  // Check if the current section matches $fname
3935  $pos = count( $this->trxAtomicLevels ) - 1;
3936  list( $savedFname, $savedSectionId, $savepointId ) = $this->trxAtomicLevels[$pos];
3937 
3938  if ( $excisedFnames ) {
3939  $this->queryLogger->debug( "cancelAtomic: canceling level $pos ($savedFname) " .
3940  "and descendants " . implode( ', ', $excisedFnames ) );
3941  } else {
3942  $this->queryLogger->debug( "cancelAtomic: canceling level $pos ($savedFname)" );
3943  }
3944 
3945  if ( $savedFname !== $fname ) {
3946  throw new DBUnexpectedError(
3947  $this,
3948  "Invalid atomic section ended (got $fname but expected $savedFname)"
3949  );
3950  }
3951 
3952  // Remove the last section (no need to re-index the array)
3953  array_pop( $this->trxAtomicLevels );
3954  $excisedIds[] = $savedSectionId;
3955  $newTopSection = $this->currentAtomicSectionId();
3956 
3957  if ( $savepointId !== null ) {
3958  // Rollback the transaction to the state just before this atomic section
3959  if ( $savepointId === self::$NOT_APPLICABLE ) {
3960  $this->rollback( $fname, self::FLUSHING_INTERNAL );
3961  // Note: rollback() will run trxSectionCancelCallbacks
3962  } else {
3963  $this->doRollbackToSavepoint( $savepointId, $fname );
3964  $this->trxStatus = self::STATUS_TRX_OK; // no exception; recovered
3965  $this->trxStatusIgnoredCause = null;
3966 
3967  // Run trxSectionCancelCallbacks now.
3968  $this->runOnAtomicSectionCancelCallbacks( self::TRIGGER_CANCEL, $excisedIds );
3969  }
3970  } elseif ( $this->trxStatus > self::STATUS_TRX_ERROR ) {
3971  // Put the transaction into an error state if it's not already in one
3972  $this->trxStatus = self::STATUS_TRX_ERROR;
3973  $this->trxStatusCause = new DBUnexpectedError(
3974  $this,
3975  "Uncancelable atomic section canceled (got $fname)"
3976  );
3977  }
3978  } finally {
3979  // Fix up callbacks owned by the sections that were just cancelled.
3980  // All callbacks should have an owner that is present in trxAtomicLevels.
3981  $this->modifyCallbacksForCancel( $excisedIds, $newTopSection );
3982  }
3983 
3984  $this->affectedRowCount = 0; // for the sake of consistency
3985  }
3986 
3987  final public function doAtomicSection(
3988  $fname, callable $callback, $cancelable = self::ATOMIC_NOT_CANCELABLE
3989  ) {
3990  $sectionId = $this->startAtomic( $fname, $cancelable );
3991  try {
3992  $res = $callback( $this, $fname );
3993  } catch ( Exception $e ) {
3994  $this->cancelAtomic( $fname, $sectionId );
3995 
3996  throw $e;
3997  }
3998  $this->endAtomic( $fname );
3999 
4000  return $res;
4001  }
4002 
4003  final public function begin( $fname = __METHOD__, $mode = self::TRANSACTION_EXPLICIT ) {
4004  static $modes = [ self::TRANSACTION_EXPLICIT, self::TRANSACTION_INTERNAL ];
4005  if ( !in_array( $mode, $modes, true ) ) {
4006  throw new DBUnexpectedError( $this, "$fname: invalid mode parameter '$mode'" );
4007  }
4008 
4009  // Protect against mismatched atomic section, transaction nesting, and snapshot loss
4010  if ( $this->trxLevel() ) {
4011  if ( $this->trxAtomicLevels ) {
4012  $levels = $this->flatAtomicSectionList();
4013  $msg = "$fname: got explicit BEGIN while atomic section(s) $levels are open";
4014  throw new DBUnexpectedError( $this, $msg );
4015  } elseif ( !$this->trxAutomatic ) {
4016  $msg = "$fname: explicit transaction already active (from {$this->trxFname})";
4017  throw new DBUnexpectedError( $this, $msg );
4018  } else {
4019  $msg = "$fname: implicit transaction already active (from {$this->trxFname})";
4020  throw new DBUnexpectedError( $this, $msg );
4021  }
4022  } elseif ( $this->getFlag( self::DBO_TRX ) && $mode !== self::TRANSACTION_INTERNAL ) {
4023  $msg = "$fname: implicit transaction expected (DBO_TRX set)";
4024  throw new DBUnexpectedError( $this, $msg );
4025  }
4026 
4027  $this->assertHasConnectionHandle();
4028 
4029  $this->doBegin( $fname );
4030  $this->trxShortId = sprintf( '%06x', mt_rand( 0, 0xffffff ) );
4031  $this->trxStatus = self::STATUS_TRX_OK;
4032  $this->trxStatusIgnoredCause = null;
4033  $this->trxAtomicCounter = 0;
4034  $this->trxTimestamp = microtime( true );
4035  $this->trxFname = $fname;
4036  $this->trxDoneWrites = false;
4037  $this->trxAutomaticAtomic = false;
4038  $this->trxAtomicLevels = [];
4039  $this->trxWriteDuration = 0.0;
4040  $this->trxWriteQueryCount = 0;
4041  $this->trxWriteAffectedRows = 0;
4042  $this->trxWriteAdjDuration = 0.0;
4043  $this->trxWriteAdjQueryCount = 0;
4044  $this->trxWriteCallers = [];
4045  // First SELECT after BEGIN will establish the snapshot in REPEATABLE-READ.
4046  // Get an estimate of the replication lag before any such queries.
4047  $this->trxReplicaLag = null; // clear cached value first
4048  $this->trxReplicaLag = $this->getApproximateLagStatus()['lag'];
4049  // T147697: make explicitTrxActive() return true until begin() finishes. This way, no
4050  // caller will think its OK to muck around with the transaction just because startAtomic()
4051  // has not yet completed (e.g. setting trxAtomicLevels).
4052  $this->trxAutomatic = ( $mode === self::TRANSACTION_INTERNAL );
4053  }
4054 
4062  protected function doBegin( $fname ) {
4063  $this->query( 'BEGIN', $fname );
4064  }
4065 
4066  final public function commit( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) {
4067  static $modes = [ self::FLUSHING_ONE, self::FLUSHING_ALL_PEERS, self::FLUSHING_INTERNAL ];
4068  if ( !in_array( $flush, $modes, true ) ) {
4069  throw new DBUnexpectedError( $this, "$fname: invalid flush parameter '$flush'" );
4070  }
4071 
4072  if ( $this->trxLevel() && $this->trxAtomicLevels ) {
4073  // There are still atomic sections open; this cannot be ignored
4074  $levels = $this->flatAtomicSectionList();
4075  throw new DBUnexpectedError(
4076  $this,
4077  "$fname: got COMMIT while atomic sections $levels are still open"
4078  );
4079  }
4080 
4081  if ( $flush === self::FLUSHING_INTERNAL || $flush === self::FLUSHING_ALL_PEERS ) {
4082  if ( !$this->trxLevel() ) {
4083  return; // nothing to do
4084  } elseif ( !$this->trxAutomatic ) {
4085  throw new DBUnexpectedError(
4086  $this,
4087  "$fname: flushing an explicit transaction, getting out of sync"
4088  );
4089  }
4090  } elseif ( !$this->trxLevel() ) {
4091  $this->queryLogger->error(
4092  "$fname: no transaction to commit, something got out of sync" );
4093  return; // nothing to do
4094  } elseif ( $this->trxAutomatic ) {
4095  throw new DBUnexpectedError(
4096  $this,
4097  "$fname: expected mass commit of all peer transactions (DBO_TRX set)"
4098  );
4099  }
4100 
4101  $this->assertHasConnectionHandle();
4102 
4104 
4105  $writeTime = $this->pendingWriteQueryDuration( self::ESTIMATE_DB_APPLY );
4106  $this->doCommit( $fname );
4107  $oldTrxShortId = $this->consumeTrxShortId();
4108  $this->trxStatus = self::STATUS_TRX_NONE;
4109 
4110  if ( $this->trxDoneWrites ) {
4111  $this->lastWriteTime = microtime( true );
4112  $this->trxProfiler->transactionWritingOut(
4113  $this->server,
4114  $this->getDomainID(),
4115  $oldTrxShortId,
4116  $writeTime,
4117  $this->trxWriteAffectedRows
4118  );
4119  }
4120 
4121  // With FLUSHING_ALL_PEERS, callbacks will be explicitly run later
4122  if ( $flush !== self::FLUSHING_ALL_PEERS ) {
4123  $this->runOnTransactionIdleCallbacks( self::TRIGGER_COMMIT );
4124  $this->runTransactionListenerCallbacks( self::TRIGGER_COMMIT );
4125  }
4126  }
4127 
4135  protected function doCommit( $fname ) {
4136  if ( $this->trxLevel() ) {
4137  $this->query( 'COMMIT', $fname );
4138  }
4139  }
4140 
4141  final public function rollback( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) {
4142  $trxActive = $this->trxLevel();
4143 
4144  if ( $flush !== self::FLUSHING_INTERNAL
4145  && $flush !== self::FLUSHING_ALL_PEERS
4146  && $this->getFlag( self::DBO_TRX )
4147  ) {
4148  throw new DBUnexpectedError(
4149  $this,
4150  "$fname: Expected mass rollback of all peer transactions (DBO_TRX set)"
4151  );
4152  }
4153 
4154  if ( $trxActive ) {
4155  $this->assertHasConnectionHandle();
4156 
4157  $this->doRollback( $fname );
4158  $oldTrxShortId = $this->consumeTrxShortId();
4159  $this->trxStatus = self::STATUS_TRX_NONE;
4160  $this->trxAtomicLevels = [];
4161  // Estimate the RTT via a query now that trxStatus is OK
4162  $writeTime = $this->pingAndCalculateLastTrxApplyTime();
4163 
4164  if ( $this->trxDoneWrites ) {
4165  $this->trxProfiler->transactionWritingOut(
4166  $this->server,
4167  $this->getDomainID(),
4168  $oldTrxShortId,
4169  $writeTime,
4170  $this->trxWriteAffectedRows
4171  );
4172  }
4173  }
4174 
4175  // Clear any commit-dependant callbacks. They might even be present
4176  // only due to transaction rounds, with no SQL transaction being active
4177  $this->trxIdleCallbacks = [];
4178  $this->trxPreCommitCallbacks = [];
4179 
4180  // With FLUSHING_ALL_PEERS, callbacks will be explicitly run later
4181  if ( $trxActive && $flush !== self::FLUSHING_ALL_PEERS ) {
4182  try {
4183  $this->runOnTransactionIdleCallbacks( self::TRIGGER_ROLLBACK );
4184  } catch ( Exception $e ) {
4185  // already logged; finish and let LoadBalancer move on during mass-rollback
4186  }
4187  try {
4188  $this->runTransactionListenerCallbacks( self::TRIGGER_ROLLBACK );
4189  } catch ( Exception $e ) {
4190  // already logged; let LoadBalancer move on during mass-rollback
4191  }
4192 
4193  $this->affectedRowCount = 0; // for the sake of consistency
4194  }
4195  }
4196 
4204  protected function doRollback( $fname ) {
4205  if ( $this->trxLevel() ) {
4206  # Disconnects cause rollback anyway, so ignore those errors
4207  $ignoreErrors = true;
4208  $this->query( 'ROLLBACK', $fname, $ignoreErrors );
4209  }
4210  }
4211 
4212  public function flushSnapshot( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) {
4213  if ( $this->explicitTrxActive() ) {
4214  // Committing this transaction would break callers that assume it is still open
4215  throw new DBUnexpectedError(
4216  $this,
4217  "$fname: Cannot flush snapshot; " .
4218  "explicit transaction '{$this->trxFname}' is still open"
4219  );
4220  } elseif ( $this->writesOrCallbacksPending() ) {
4221  // This only flushes transactions to clear snapshots, not to write data
4222  $fnames = implode( ', ', $this->pendingWriteAndCallbackCallers() );
4223  throw new DBUnexpectedError(
4224  $this,
4225  "$fname: Cannot flush snapshot; " .
4226  "writes from transaction {$this->trxFname} are still pending ($fnames)"
4227  );
4228  } elseif (
4229  $this->trxLevel() &&
4230  $this->getTransactionRoundId() &&
4231  $flush !== self::FLUSHING_INTERNAL &&
4232  $flush !== self::FLUSHING_ALL_PEERS
4233  ) {
4234  $this->queryLogger->warning(
4235  "$fname: Expected mass snapshot flush of all peer transactions " .
4236  "in the explicit transactions round '{$this->getTransactionRoundId()}'",
4237  [ 'trace' => ( new RuntimeException() )->getTraceAsString() ]
4238  );
4239  }
4240 
4241  $this->commit( $fname, self::FLUSHING_INTERNAL );
4242  }
4243 
4244  public function explicitTrxActive() {
4245  return $this->trxLevel() && ( $this->trxAtomicLevels || !$this->trxAutomatic );
4246  }
4247 
4248  public function duplicateTableStructure(
4249  $oldName, $newName, $temporary = false, $fname = __METHOD__
4250  ) {
4251  throw new RuntimeException( __METHOD__ . ' is not implemented in descendant class' );
4252  }
4253 
4254  public function listTables( $prefix = null, $fname = __METHOD__ ) {
4255  throw new RuntimeException( __METHOD__ . ' is not implemented in descendant class' );
4256  }
4257 
4258  public function listViews( $prefix = null, $fname = __METHOD__ ) {
4259  throw new RuntimeException( __METHOD__ . ' is not implemented in descendant class' );
4260  }
4261 
4262  public function timestamp( $ts = 0 ) {
4263  $t = new ConvertibleTimestamp( $ts );
4264  // Let errors bubble up to avoid putting garbage in the DB
4265  return $t->getTimestamp( TS_MW );
4266  }
4267 
4268  public function timestampOrNull( $ts = null ) {
4269  if ( is_null( $ts ) ) {
4270  return null;
4271  } else {
4272  return $this->timestamp( $ts );
4273  }
4274  }
4275 
4276  public function affectedRows() {
4277  return ( $this->affectedRowCount === null )
4278  ? $this->fetchAffectedRowCount() // default to driver value
4280  }
4281 
4285  abstract protected function fetchAffectedRowCount();
4286 
4299  protected function resultObject( $result ) {
4300  if ( !$result ) {
4301  return false; // failed query
4302  } elseif ( $result instanceof IResultWrapper ) {
4303  return $result;
4304  } elseif ( $result === true ) {
4305  return $result; // successful write query
4306  } else {
4307  return new ResultWrapper( $this, $result );
4308  }
4309  }
4310 
4311  public function ping( &$rtt = null ) {
4312  // Avoid hitting the server if it was hit recently
4313  if ( $this->isOpen() && ( microtime( true ) - $this->lastPing ) < self::$PING_TTL ) {
4314  if ( !func_num_args() || $this->lastRoundTripEstimate > 0 ) {
4316  return true; // don't care about $rtt
4317  }
4318  }
4319 
4320  // This will reconnect if possible or return false if not
4321  $flags = self::QUERY_IGNORE_DBO_TRX | self::QUERY_SILENCE_ERRORS;
4322  $ok = ( $this->query( self::$PING_QUERY, __METHOD__, $flags ) !== false );
4323  if ( $ok ) {
4325  }
4326 
4327  return $ok;
4328  }
4329 
4336  protected function replaceLostConnection( $fname ) {
4337  $this->closeConnection();
4338  $this->conn = null;
4339 
4340  $this->handleSessionLossPreconnect();
4341 
4342  try {
4343  $this->open(
4344  $this->server,
4345  $this->user,
4346  $this->password,
4347  $this->currentDomain->getDatabase(),
4348  $this->currentDomain->getSchema(),
4349  $this->tablePrefix()
4350  );
4351  $this->lastPing = microtime( true );
4352  $ok = true;
4353 
4354  $this->connLogger->warning(
4355  $fname . ': lost connection to {dbserver}; reconnected',
4356  [
4357  'dbserver' => $this->getServer(),
4358  'trace' => ( new RuntimeException() )->getTraceAsString()
4359  ]
4360  );
4361  } catch ( DBConnectionError $e ) {
4362  $ok = false;
4363 
4364  $this->connLogger->error(
4365  $fname . ': lost connection to {dbserver} permanently',
4366  [ 'dbserver' => $this->getServer() ]
4367  );
4368  }
4369 
4371 
4372  return $ok;
4373  }
4374 
4375  public function getSessionLagStatus() {
4376  return $this->getRecordedTransactionLagStatus() ?: $this->getApproximateLagStatus();
4377  }
4378 
4392  final protected function getRecordedTransactionLagStatus() {
4393  return ( $this->trxLevel() && $this->trxReplicaLag !== null )
4394  ? [ 'lag' => $this->trxReplicaLag, 'since' => $this->trxTimestamp() ]
4395  : null;
4396  }
4397 
4406  protected function getApproximateLagStatus() {
4407  return [
4408  'lag' => ( $this->topologyRole === self::ROLE_STREAMING_REPLICA ) ? $this->getLag() : 0,
4409  'since' => microtime( true )
4410  ];
4411  }
4412 
4432  public static function getCacheSetOptions( IDatabase $db1, IDatabase $db2 = null ) {
4433  $res = [ 'lag' => 0, 'since' => INF, 'pending' => false ];
4434  foreach ( func_get_args() as $db ) {
4436  $status = $db->getSessionLagStatus();
4437  if ( $status['lag'] === false ) {
4438  $res['lag'] = false;
4439  } elseif ( $res['lag'] !== false ) {
4440  $res['lag'] = max( $res['lag'], $status['lag'] );
4441  }
4442  $res['since'] = min( $res['since'], $status['since'] );
4443  $res['pending'] = $res['pending'] ?: $db->writesPending();
4444  }
4445 
4446  return $res;
4447  }
4448 
4449  public function getLag() {
4450  if ( $this->topologyRole === self::ROLE_STREAMING_MASTER ) {
4451  return 0; // this is the master
4452  } elseif ( $this->topologyRole === self::ROLE_STATIC_CLONE ) {
4453  return 0; // static dataset
4454  }
4455 
4456  return $this->doGetLag();
4457  }
4458 
4459  protected function doGetLag() {
4460  return 0;
4461  }
4462 
4463  public function maxListLen() {
4464  return 0;
4465  }
4466 
4467  public function encodeBlob( $b ) {
4468  return $b;
4469  }
4470 
4471  public function decodeBlob( $b ) {
4472  if ( $b instanceof Blob ) {
4473  $b = $b->fetch();
4474  }
4475  return $b;
4476  }
4477 
4478  public function setSessionOptions( array $options ) {
4479  }
4480 
4481  public function sourceFile(
4482  $filename,
4483  callable $lineCallback = null,
4484  callable $resultCallback = null,
4485  $fname = false,
4486  callable $inputCallback = null
4487  ) {
4488  AtEase::suppressWarnings();
4489  $fp = fopen( $filename, 'r' );
4490  AtEase::restoreWarnings();
4491 
4492  if ( $fp === false ) {
4493  throw new RuntimeException( "Could not open \"{$filename}\"" );
4494  }
4495 
4496  if ( !$fname ) {
4497  $fname = __METHOD__ . "( $filename )";
4498  }
4499 
4500  try {
4501  $error = $this->sourceStream(
4502  $fp, $lineCallback, $resultCallback, $fname, $inputCallback );
4503  } catch ( Exception $e ) {
4504  fclose( $fp );
4505  throw $e;
4506  }
4507 
4508  fclose( $fp );
4509 
4510  return $error;
4511  }
4512 
4513  public function setSchemaVars( $vars ) {
4514  $this->schemaVars = is_array( $vars ) ? $vars : null;
4515  }
4516 
4517  public function sourceStream(
4518  $fp,
4519  callable $lineCallback = null,
4520  callable $resultCallback = null,
4521  $fname = __METHOD__,
4522  callable $inputCallback = null
4523  ) {
4524  $delimiterReset = new ScopedCallback(
4525  function ( $delimiter ) {
4526  $this->delimiter = $delimiter;
4527  },
4528  [ $this->delimiter ]
4529  );
4530  $cmd = '';
4531 
4532  while ( !feof( $fp ) ) {
4533  if ( $lineCallback ) {
4534  call_user_func( $lineCallback );
4535  }
4536 
4537  $line = trim( fgets( $fp ) );
4538 
4539  if ( $line == '' ) {
4540  continue;
4541  }
4542 
4543  if ( $line[0] == '-' && $line[1] == '-' ) {
4544  continue;
4545  }
4546 
4547  if ( $cmd != '' ) {
4548  $cmd .= ' ';
4549  }
4550 
4551  $done = $this->streamStatementEnd( $cmd, $line );
4552 
4553  $cmd .= "$line\n";
4554 
4555  if ( $done || feof( $fp ) ) {
4556  $cmd = $this->replaceVars( $cmd );
4557 
4558  if ( $inputCallback ) {
4559  $callbackResult = $inputCallback( $cmd );
4560 
4561  if ( is_string( $callbackResult ) || !$callbackResult ) {
4562  $cmd = $callbackResult;
4563  }
4564  }
4565 
4566  if ( $cmd ) {
4567  $res = $this->query( $cmd, $fname );
4568 
4569  if ( $resultCallback ) {
4570  $resultCallback( $res, $this );
4571  }
4572 
4573  if ( $res === false ) {
4574  $err = $this->lastError();
4575 
4576  return "Query \"{$cmd}\" failed with error code \"$err\".\n";
4577  }
4578  }
4579  $cmd = '';
4580  }
4581  }
4582 
4583  ScopedCallback::consume( $delimiterReset );
4584  return true;
4585  }
4586 
4594  public function streamStatementEnd( &$sql, &$newLine ) {
4595  if ( $this->delimiter ) {
4596  $prev = $newLine;
4597  $newLine = preg_replace(
4598  '/' . preg_quote( $this->delimiter, '/' ) . '$/', '', $newLine );
4599  if ( $newLine != $prev ) {
4600  return true;
4601  }
4602  }
4603 
4604  return false;
4605  }
4606 
4627  protected function replaceVars( $ins ) {
4628  $vars = $this->getSchemaVars();
4629  return preg_replace_callback(
4630  '!
4631  /\* (\$wgDBprefix|[_i]) \*/ (\w*) | # 1-2. tableName, indexName
4632  \'\{\$ (\w+) }\' | # 3. addQuotes
4633  `\{\$ (\w+) }` | # 4. addIdentifierQuotes
4634  /\*\$ (\w+) \*/ # 5. leave unencoded
4635  !x',
4636  function ( $m ) use ( $vars ) {
4637  // Note: Because of <https://bugs.php.net/bug.php?id=51881>,
4638  // check for both nonexistent keys *and* the empty string.
4639  if ( isset( $m[1] ) && $m[1] !== '' ) {
4640  if ( $m[1] === 'i' ) {
4641  return $this->indexName( $m[2] );
4642  } else {
4643  return $this->tableName( $m[2] );
4644  }
4645  } elseif ( isset( $m[3] ) && $m[3] !== '' && array_key_exists( $m[3], $vars ) ) {
4646  return $this->addQuotes( $vars[$m[3]] );
4647  } elseif ( isset( $m[4] ) && $m[4] !== '' && array_key_exists( $m[4], $vars ) ) {
4648  return $this->addIdentifierQuotes( $vars[$m[4]] );
4649  } elseif ( isset( $m[5] ) && $m[5] !== '' && array_key_exists( $m[5], $vars ) ) {
4650  return $vars[$m[5]];
4651  } else {
4652  return $m[0];
4653  }
4654  },
4655  $ins
4656  );
4657  }
4658 
4665  protected function getSchemaVars() {
4666  return $this->schemaVars ?? $this->getDefaultSchemaVars();
4667  }
4668 
4677  protected function getDefaultSchemaVars() {
4678  return [];
4679  }
4680 
4681  public function lockIsFree( $lockName, $method ) {
4682  // RDBMs methods for checking named locks may or may not count this thread itself.
4683  // In MySQL, IS_FREE_LOCK() returns 0 if the thread already has the lock. This is
4684  // the behavior chosen by the interface for this method.
4685  return !isset( $this->sessionNamedLocks[$lockName] );
4686  }
4687 
4688  public function lock( $lockName, $method, $timeout = 5 ) {
4689  $this->sessionNamedLocks[$lockName] = 1;
4690 
4691  return true;
4692  }
4693 
4694  public function unlock( $lockName, $method ) {
4695  unset( $this->sessionNamedLocks[$lockName] );
4696 
4697  return true;
4698  }
4699 
4700  public function getScopedLockAndFlush( $lockKey, $fname, $timeout ) {
4701  if ( $this->writesOrCallbacksPending() ) {
4702  // This only flushes transactions to clear snapshots, not to write data
4703  $fnames = implode( ', ', $this->pendingWriteAndCallbackCallers() );
4704  throw new DBUnexpectedError(
4705  $this,
4706  "$fname: Cannot flush pre-lock snapshot; " .
4707  "writes from transaction {$this->trxFname} are still pending ($fnames)"
4708  );
4709  }
4710 
4711  if ( !$this->lock( $lockKey, $fname, $timeout ) ) {
4712  return null;
4713  }
4714 
4715  $unlocker = new ScopedCallback( function () use ( $lockKey, $fname ) {
4716  if ( $this->trxLevel() ) {
4717  // There is a good chance an exception was thrown, causing any early return
4718  // from the caller. Let any error handler get a chance to issue rollback().
4719  // If there isn't one, let the error bubble up and trigger server-side rollback.
4720  $this->onTransactionResolution(
4721  function () use ( $lockKey, $fname ) {
4722  $this->unlock( $lockKey, $fname );
4723  },
4724  $fname
4725  );
4726  } else {
4727  $this->unlock( $lockKey, $fname );
4728  }
4729  } );
4730 
4731  $this->commit( $fname, self::FLUSHING_INTERNAL );
4732 
4733  return $unlocker;
4734  }
4735 
4736  public function namedLocksEnqueue() {
4737  return false;
4738  }
4739 
4741  return true;
4742  }
4743 
4744  final public function lockTables( array $read, array $write, $method ) {
4745  if ( $this->writesOrCallbacksPending() ) {
4746  throw new DBUnexpectedError( $this, "Transaction writes or callbacks still pending" );
4747  }
4748 
4749  if ( $this->tableLocksHaveTransactionScope() ) {
4750  $this->startAtomic( $method );
4751  }
4752 
4753  return $this->doLockTables( $read, $write, $method );
4754  }
4755 
4764  protected function doLockTables( array $read, array $write, $method ) {
4765  return true;
4766  }
4767 
4768  final public function unlockTables( $method ) {
4769  if ( $this->tableLocksHaveTransactionScope() ) {
4770  $this->endAtomic( $method );
4771 
4772  return true; // locks released on COMMIT/ROLLBACK
4773  }
4774 
4775  return $this->doUnlockTables( $method );
4776  }
4777 
4784  protected function doUnlockTables( $method ) {
4785  return true;
4786  }
4787 
4795  public function dropTable( $tableName, $fName = __METHOD__ ) {
4796  if ( !$this->tableExists( $tableName, $fName ) ) {
4797  return false;
4798  }
4799  $sql = "DROP TABLE " . $this->tableName( $tableName ) . " CASCADE";
4800 
4801  return $this->query( $sql, $fName );
4802  }
4803 
4804  public function getInfinity() {
4805  return 'infinity';
4806  }
4807 
4808  public function encodeExpiry( $expiry ) {
4809  return ( $expiry == '' || $expiry == 'infinity' || $expiry == $this->getInfinity() )
4810  ? $this->getInfinity()
4811  : $this->timestamp( $expiry );
4812  }
4813 
4814  public function decodeExpiry( $expiry, $format = TS_MW ) {
4815  if ( $expiry == '' || $expiry == 'infinity' || $expiry == $this->getInfinity() ) {
4816  return 'infinity';
4817  }
4818 
4819  return ConvertibleTimestamp::convert( $format, $expiry );
4820  }
4821 
4822  public function setBigSelects( $value = true ) {
4823  // no-op
4824  }
4825 
4826  public function isReadOnly() {
4827  return ( $this->getReadOnlyReason() !== false );
4828  }
4829 
4833  protected function getReadOnlyReason() {
4834  if ( $this->topologyRole === self::ROLE_STREAMING_REPLICA ) {
4835  return [ 'Server is configured as a read-only replica database.', 'role' ];
4836  } elseif ( $this->topologyRole === self::ROLE_STATIC_CLONE ) {
4837  return [ 'Server is configured as a read-only static clone database.', 'role' ];
4838  }
4839 
4840  $reason = $this->getLBInfo( self::LB_READ_ONLY_REASON );
4841  if ( is_string( $reason ) ) {
4842  return [ $reason, 'lb' ];
4843  }
4844 
4845  return false;
4846  }
4847 
4848  public function setTableAliases( array $aliases ) {
4849  $this->tableAliases = $aliases;
4850  }
4851 
4852  public function setIndexAliases( array $aliases ) {
4853  $this->indexAliases = $aliases;
4854  }
4855 
4862  final protected function fieldHasBit( $field, $flags ) {
4863  return ( ( $field & $flags ) === $flags );
4864  }
4865 
4877  protected function getBindingHandle() {
4878  if ( !$this->conn ) {
4879  throw new DBUnexpectedError(
4880  $this,
4881  'DB connection was already closed or the connection dropped'
4882  );
4883  }
4884 
4885  return $this->conn;
4886  }
4887 
4888  public function __toString() {
4889  // spl_object_id is PHP >= 7.2
4890  $id = function_exists( 'spl_object_id' )
4891  ? spl_object_id( $this )
4892  : spl_object_hash( $this );
4893 
4894  $description = $this->getType() . ' object #' . $id;
4895  if ( is_resource( $this->conn ) ) {
4896  $description .= ' (' . (string)$this->conn . ')'; // "resource id #<ID>"
4897  } elseif ( is_object( $this->conn ) ) {
4898  // spl_object_id is PHP >= 7.2
4899  $handleId = function_exists( 'spl_object_id' )
4900  ? spl_object_id( $this->conn )
4901  : spl_object_hash( $this->conn );
4902  $description .= " (handle id #$handleId)";
4903  }
4904 
4905  return $description;
4906  }
4907 
4912  public function __clone() {
4913  $this->connLogger->warning(
4914  "Cloning " . static::class . " is not recommended; forking connection",
4915  [ 'trace' => ( new RuntimeException() )->getTraceAsString() ]
4916  );
4917 
4918  if ( $this->isOpen() ) {
4919  // Open a new connection resource without messing with the old one
4920  $this->conn = null;
4921  $this->trxEndCallbacks = []; // don't copy
4922  $this->trxSectionCancelCallbacks = []; // don't copy
4923  $this->handleSessionLossPreconnect(); // no trx or locks anymore
4924  $this->open(
4925  $this->server,
4926  $this->user,
4927  $this->password,
4928  $this->currentDomain->getDatabase(),
4929  $this->currentDomain->getSchema(),
4930  $this->tablePrefix()
4931  );
4932  $this->lastPing = microtime( true );
4933  }
4934  }
4935 
4941  public function __sleep() {
4942  throw new RuntimeException( 'Database serialization may cause problems, since ' .
4943  'the connection is not restored on wakeup' );
4944  }
4945 
4949  public function __destruct() {
4950  if ( $this->trxLevel() && $this->trxDoneWrites ) {
4951  trigger_error( "Uncommitted DB writes (transaction from {$this->trxFname})" );
4952  }
4953 
4954  $danglingWriters = $this->pendingWriteAndCallbackCallers();
4955  if ( $danglingWriters ) {
4956  $fnames = implode( ', ', $danglingWriters );
4957  trigger_error( "DB transaction writes or callbacks still pending ($fnames)" );
4958  }
4959 
4960  if ( $this->conn ) {
4961  // Avoid connection leaks for sanity. Normally, resources close at script completion.
4962  // The connection might already be closed in PHP by now, so suppress warnings.
4963  AtEase::suppressWarnings();
4964  $this->closeConnection();
4965  AtEase::restoreWarnings();
4966  $this->conn = null;
4967  }
4968  }
4969 }
4970 
4974 class_alias( Database::class, 'DatabaseBase' );
4975 
4979 class_alias( Database::class, 'Database' );
getLazyMasterHandle()
Get a handle to the master server of the cluster to which this server belongs.
Definition: Database.php:636
Helper class that detects high-contention DB queries via profiling calls.
int $nonNativeInsertSelectBatchSize
Row batch size to use for emulated INSERT SELECT queries.
Definition: Database.php:93
normalizeConditions( $conds, $fname)
Definition: Database.php:2026
setIndexAliases(array $aliases)
Convert certain index names to alternative names before querying the DB.
Definition: Database.php:4852
rollback( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
Rollback a transaction previously started using begin()
Definition: Database.php:4141
canRecoverFromDisconnect( $sql, $priorWritesPending)
Determine whether it is safe to retry queries after a database connection is lost.
Definition: Database.php:1468
conditional( $cond, $trueVal, $falseVal)
Returns an SQL expression for a simple conditional.
Definition: Database.php:3314
clearFlag( $flag, $remember=self::REMEMBER_NOTHING)
Clear a flag for this connection.
Definition: Database.php:774
close( $fname=__METHOD__, $owner=null)
Close the database connection.
Definition: Database.php:892
executeQueryAttempt( $sql, $commentedSql, $isPermWrite, $fname, $flags)
Wrapper for doQuery() that handles DBO_TRX, profiling, logging, affected row count tracking...
Definition: Database.php:1282
static float $SMALL_WRITE_ROWS
Assume an insert of this many rows or less should be fast to replicate.
Definition: Database.php:233
decodeExpiry( $expiry, $format=TS_MW)
Decode an expiry time into a DBMS independent format.
Definition: Database.php:4814
isTransactableQuery( $sql)
Determine whether a SQL statement is sensitive to isolation level.
Definition: Database.php:1088
setSessionOptions(array $options)
Override database&#39;s default behavior.
Definition: Database.php:4478
namedLocksEnqueue()
Check to see if a named lock used by lock() use blocking queues.
Definition: Database.php:4736
getFlag( $flag)
Returns a boolean whether the flag $flag is set for this connection.
Definition: Database.php:802
freeResult( $res)
Free a result object returned by query() or select()
Definition: Database.php:1649
databasesAreIndependent()
Returns true if DBs are assumed to be on potentially different servers.
Definition: Database.php:2401
bool $trxAutomatic
Whether the current transaction was started implicitly due to DBO_TRX.
Definition: Database.php:135
unlockTables( $method)
Unlock all tables locked via lockTables()
Definition: Database.php:4768
flushSnapshot( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
Commit any transaction but error out if writes or callbacks are pending.
Definition: Database.php:4212
timestamp( $ts=0)
Convert a timestamp in one of the formats accepted by ConvertibleTimestamp to the format used for ins...
Definition: Database.php:4262
affectedRows()
Get the number of rows affected by the last write query.
Definition: Database.php:4276
encodeBlob( $b)
Some DBMSs have a special format for inserting into blob fields, they don&#39;t allow simple quoted strin...
Definition: Database.php:4467
fieldInfo( $table, $field)
mysql_fetch_field() wrapper Returns false if the field doesn&#39;t exist
fetchObject( $res)
Fetch the next row from the given result object, in object form.
tableNamesN(... $tables)
Fetch a number of table names into an zero-indexed numerical array This is handy when you need to con...
Definition: Database.php:2556
int $trxWriteAdjQueryCount
Number of write queries counted in trxWriteAdjDuration.
Definition: Database.php:153
array $sessionTempTables
Map of (table name => 1) for TEMPORARY tables.
Definition: Database.php:116
doSelectDomain(DatabaseDomain $domain)
Definition: Database.php:2425
lastErrno()
Get the last error number.
getTempWrites( $sql, $pseudoPermanent)
Definition: Database.php:1104
escapeLikeInternal( $s, $escapeChar='`')
Definition: Database.php:2797
buildConcat( $stringList)
Build a concatenation list to feed into a SQL query.
Definition: Database.php:2336
setLBInfo( $nameOrArray, $value=null)
Set the entire array or a particular key of the managing load balancer info array.
Definition: Database.php:616
selectDomain( $domain)
Set the current domain (database, schema, and table prefix)
Definition: Database.php:2415
pendingWriteQueryDuration( $type=self::ESTIMATE_TOTAL)
Get the time spend running write queries for this transaction.
Definition: Database.php:684
begin( $fname=__METHOD__, $mode=self::TRANSACTION_EXPLICIT)
Begin a transaction.
Definition: Database.php:4003
encodeExpiry( $expiry)
Encode an expiry time into the DBMS dependent format.
Definition: Database.php:4808
Result wrapper for grabbing data queried from an IDatabase object.
pendingWriteCallers()
Get the list of method names that did write queries for this transaction.
Definition: Database.php:714
static int $TEMP_PSEUDO_PERMANENT
Writes to this temporary table effect lastDoneWrites()
Definition: Database.php:214
array null $trxStatusIgnoredCause
Error details of the last statement-only rollback.
Definition: Database.php:125
const LIST_NAMES
Definition: Defines.php:41
ignoreIndexClause( $index)
IGNORE INDEX clause.
Definition: Database.php:2866
static string $SAVEPOINT_PREFIX
Prefix to the atomic section counter used to make savepoint IDs.
Definition: Database.php:209
getScopedLockAndFlush( $lockKey, $fname, $timeout)
Acquire a named lock, flush any transaction, and return an RAII style unlocker object.
Definition: Database.php:4700
numRows( $res)
Get the number of rows in a query result.
anyChar()
Returns a token for buildLike() that denotes a &#39;_&#39; to be used in a LIKE query.
Definition: Database.php:2830
executeQuery( $sql, $fname, $flags)
Execute a query, retrying it if there is a recoverable connection loss.
Definition: Database.php:1192
__sleep()
Called by serialize.
Definition: Database.php:4941
static int $DEADLOCK_DELAY_MIN
Minimum time to wait before retry, in microseconds.
Definition: Database.php:219
getServer()
Get the server hostname or IP address.
Definition: Database.php:2433
assertBuildSubstringParams( $startPosition, $length)
Check type and bounds for parameters to self::buildSubstring()
Definition: Database.php:2369
string $trxShortId
ID of the active transaction or the empty string otherwise.
Definition: Database.php:119
Exception null $trxStatusCause
The last error that caused the status to become STATUS_TRX_ERROR.
Definition: Database.php:123
setTrxEndCallbackSuppression( $suppress)
Whether to disable running of post-COMMIT/ROLLBACK callbacks.
Definition: Database.php:3595
selectFieldValues( $table, $var, $cond='', $fname=__METHOD__, $options=[], $join_conds=[])
A SELECT wrapper which returns a list of single field values from result rows.
Definition: Database.php:1678
getSessionLagStatus()
Get the replica DB lag when the current transaction started or a general lag estimate if not transact...
Definition: Database.php:4375
__clone()
Make sure that copies do not share the same client binding handle.
Definition: Database.php:4912
array $connectionParams
Parameters used by initConnection() to establish a connection.
Definition: Database.php:89
selectDB( $db)
Change the current database.
Definition: Database.php:2405
reassignCallbacksForSection(AtomicSectionIdentifier $old, AtomicSectionIdentifier $new)
Hoist callback ownership for callbacks in a section to a parent section.
Definition: Database.php:3500
writesOrCallbacksPending()
Whether there is a transaction open with either possible write queries or unresolved pre-commit/commi...
Definition: Database.php:656
selectField( $table, $var, $cond='', $fname=__METHOD__, $options=[], $join_conds=[])
A SELECT wrapper which returns a single field from a single result row.
Definition: Database.php:1652
$source
DatabaseDomain $currentDomain
Definition: Database.php:66
int $flags
Current bit field of class DBO_* constants.
Definition: Database.php:96
makeWhereFrom2d( $data, $baseKey, $subKey)
Build a partial where clause from a 2-d array such as used for LinkBatch.
Definition: Database.php:2301
onTransactionIdle(callable $callback, $fname=__METHOD__)
Alias for onTransactionCommitOrIdle() for backwards-compatibility.
Definition: Database.php:3448
getDomainID()
Return the currently selected domain ID.
Definition: Database.php:806
buildSelectSubquery( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Equivalent to IDatabase::selectSQLText() except wraps the result in Subqyery.
Definition: Database.php:2392
limitResult( $sql, $limit, $offset=false)
Construct a LIMIT query with optional offset.
Definition: Database.php:3219
nonNativeInsertSelect( $destTable, $srcTable, $varMap, $conds, $fname=__METHOD__, $insertOptions=[], $selectOptions=[], $selectJoinConds=[])
Implementation of insertSelect() based on select() and insert()
Definition: Database.php:3122
trxLevel()
Gets the current transaction level.
Definition: Database.php:550
callable [] $trxRecurringCallbacks
Map of (name => callable)
Definition: Database.php:166
startAtomic( $fname=__METHOD__, $cancelable=self::ATOMIC_NOT_CANCELABLE)
Begin an atomic section of SQL statements.
Definition: Database.php:3838
update( $table, $values, $conds, $fname=__METHOD__, $options=[])
UPDATE wrapper.
Definition: Database.php:2207
replaceVars( $ins)
Database independent variable replacement.
Definition: Database.php:4627
string bool null $htmlErrors
Stashed value of html_errors INI setting.
Definition: Database.php:109
fieldNameWithAlias( $name, $alias=false)
Get an aliased field name e.g.
Definition: Database.php:2623
nativeReplace( $table, $rows, $fname)
REPLACE query wrapper for MySQL and SQLite, which have a native REPLACE statement.
Definition: Database.php:2931
implicitOrderby()
Returns true if this database does an implicit order by when the column has an index For example: SEL...
Definition: Database.php:640
endAtomic( $fname=__METHOD__)
Ends an atomic section of SQL statements.
Definition: Database.php:3868
doCommit( $fname)
Issues the COMMIT command to the database server.
Definition: Database.php:4135
query( $sql, $fname=__METHOD__, $flags=0)
Run an SQL query and return the result.
Definition: Database.php:1155
string $server
Server that this instance is currently connected to.
Definition: Database.php:75
getLBInfo( $name=null)
Get properties passed down from the server info array of the load balancer.
Definition: Database.php:604
nextSequenceValue( $seqName)
Deprecated method, calls should be removed.
Definition: Database.php:2838
handleSessionLossPreconnect()
Clean things up after session (and thus transaction) loss before reconnect.
Definition: Database.php:1493
buildGroupConcatField( $delim, $table, $field, $conds='', $join_conds=[])
Build a GROUP_CONCAT or equivalent statement for a query.
Definition: Database.php:2340
doLockTables(array $read, array $write, $method)
Helper function for lockTables() that handles the actual table locking.
Definition: Database.php:4764
textFieldSize( $table, $field)
Returns the size of a text field, or -1 for "unlimited".
Definition: Database.php:3023
bufferResults( $buffer=null)
Backwards-compatibility no-op method for disabling query buffering.
Definition: Database.php:546
fieldExists( $table, $field, $fname=__METHOD__)
Determines whether a field exists in a table.
Definition: Database.php:2081
float $lastPing
UNIX timestamp.
Definition: Database.php:174
callable $errorLogger
Error logging callback.
Definition: Database.php:57
const DBO_DDLMODE
Definition: defines.php:16
bitAnd( $fieldLeft, $fieldRight)
Definition: Database.php:2328
callable null $profiler
Definition: Database.php:61
Lazy-loaded wrapper for simplification and scrubbing of SQL queries for profiling.
getServerVersion()
A string describing the current software version, like from mysql_get_server_info() ...
maxListLen()
Return the maximum number of items allowed in a list, or 0 for unlimited.
Definition: Database.php:4463
doSavepoint( $identifier, $fname)
Create a savepoint.
Definition: Database.php:3787
newExceptionAfterConnectError( $error)
Definition: Database.php:1634
if( $line===false) $args
Definition: cdb.php:64
isWriteQuery( $sql)
Determine whether a query writes to the DB.
Definition: Database.php:1047
int null $ownerId
Integer ID of the managing LBFactory instance or null if none.
Definition: Database.php:185
listViews( $prefix=null, $fname=__METHOD__)
Lists all the VIEWs in the database.
Definition: Database.php:4258
strreplace( $orig, $old, $new)
Returns a SQL expression for simple string replacement (e.g.
Definition: Database.php:3322
getMasterPos()
Get the position of this master.
Definition: Database.php:3419
__destruct()
Run a few simple sanity checks and close dangling connections.
Definition: Database.php:4949
installErrorHandler()
Set a custom error handler for logging errors during database connection.
Definition: Database.php:830
getDBname()
Get the current DB name.
Definition: Database.php:2429
static int $DBO_MUTABLE
Bit field of all DBO_* flags that can be changed after connection.
Definition: Database.php:243
string [] int [] float [] $connectionVariables
SQL variables values to use for all new connections.
Definition: Database.php:91
LoggerInterface $queryLogger
Definition: Database.php:55
setLogger(LoggerInterface $logger)
Set the PSR-3 logger interface to use for query logging.
Definition: Database.php:523
array $sessionNamedLocks
Map of (name => 1) for locks obtained via lock()
Definition: Database.php:114
static int $DEADLOCK_DELAY_MAX
Maximum time to wait before retry.
Definition: Database.php:221
setBigSelects( $value=true)
Allow or deny "big selects" for this session only.
Definition: Database.php:4822
replaceLostConnection( $fname)
Close any existing (dead) database connection and open a new connection.
Definition: Database.php:4336
float $trxReplicaLag
Replication lag estimate at the time of BEGIN for the last transaction.
Definition: Database.php:129
decodeBlob( $b)
Some DBMSs return a special placeholder object representing blob fields in result objects...
Definition: Database.php:4471
buildLike( $param,... $params)
LIKE statement wrapper.
Definition: Database.php:2803
aggregateValue( $valuedata, $valuename='value')
Return aggregated value alias.
Definition: Database.php:2320
array $lbInfo
Current LoadBalancer tracking information.
Definition: Database.php:98
timestampOrNull( $ts=null)
Convert a timestamp in one of the formats accepted by ConvertibleTimestamp to the format used for ins...
Definition: Database.php:4268
addQuotes( $s)
Escape and quote a raw value string for use in a SQL query.
Definition: Database.php:2758
estimateRowCount( $tables, $var=' *', $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Estimate the number of rows in dataset.
Definition: Database.php:1932
int $trxWriteAffectedRows
Number of rows affected by write queries for the current transaction.
Definition: Database.php:149
TransactionProfiler $trxProfiler
Definition: Database.php:63
const DBO_DEBUG
Definition: defines.php:9
const LIST_AND
Definition: Defines.php:39
makeInsertOptions( $options)
Helper for Database::insert().
Definition: Database.php:2118
static getClass( $dbType, $driver=null)
Definition: Database.php:461
assertHasConnectionHandle()
Make sure there is an open connection handle (alive or not) as a sanity check.
Definition: Database.php:970
selectOptionsIncludeLocking( $options)
Definition: Database.php:1982
sourceFile( $filename, callable $lineCallback=null, callable $resultCallback=null, $fname=false, callable $inputCallback=null)
Read and execute SQL commands from a file.
Definition: Database.php:4481
doRollback( $fname)
Issues the ROLLBACK command to the database server.
Definition: Database.php:4204
onAtomicSectionCancel(callable $callback, $fname=__METHOD__)
Run a callback when the atomic section is cancelled.
Definition: Database.php:3474
static float $TINY_WRITE_SEC
Guess of how many seconds it takes to replicate a small insert.
Definition: Database.php:229
beginIfImplied( $sql, $fname)
Start an implicit transaction if DBO_TRX is enabled and no transaction is active. ...
Definition: Database.php:1370
reportQueryError( $error, $errno, $sql, $fname, $ignore=false)
Report a query error.
Definition: Database.php:1583
An object representing a master or replica DB position in a replicated setup.
Definition: DBMasterPos.php:12
indexExists( $table, $index, $fname=__METHOD__)
Determines whether an index exists.
Definition: Database.php:2087
assertQueryIsCurrentlyAllowed( $sql, $fname)
Error out if the DB is not in a valid state for a query via query()
Definition: Database.php:1422
open( $server, $user, $password, $dbName, $schema, $tablePrefix)
Open a new connection to the database (closing any existing one)
static string $PING_QUERY
Dummy SQL query.
Definition: Database.php:226
indexName( $index)
Allows for index remapping in queries where this is not consistent across DBMS.
Definition: Database.php:2754
static string [] $MUTABLE_FLAGS
List of DBO_* flags that can be changed after connection.
Definition: Database.php:236
handleSessionLossPostconnect()
Clean things up after session (and thus transaction) loss after reconnect.
Definition: Database.php:1530
string $trxFname
Name of the function that start the last transaction.
Definition: Database.php:131
const LIST_COMMA
Definition: Defines.php:38
doHandleSessionLossPreconnect()
Reset any additional subclass trx* and session* fields.
Definition: Database.php:1523
fieldNamesWithAlias( $fields)
Gets an array of aliased field names.
Definition: Database.php:2637
insertSelect( $destTable, $srcTable, $varMap, $conds, $fname=__METHOD__, $insertOptions=[], $selectOptions=[], $selectJoinConds=[])
INSERT SELECT wrapper.
Definition: Database.php:3060
doRollbackToSavepoint( $identifier, $fname)
Rollback to a savepoint.
Definition: Database.php:3815
tableName( $name, $format='quoted')
Format a table name ready for use in constructing an SQL query.
Definition: Database.php:2437
runOnTransactionIdleCallbacks( $trigger)
Actually consume and run any "on transaction idle/resolution" callbacks.
Definition: Database.php:3609
getServerUptime()
Determines how long the server has been up.
Definition: Database.php:3326
unionConditionPermutations( $table, $vars, array $permute_conds, $extra_conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Construct a UNION query for permutations of conditions.
Definition: Database.php:3243
string $delimiter
Current SQL query delimiter.
Definition: Database.php:100
setSchemaVars( $vars)
Set schema variables to be used when streaming commands from SQL files or stdin.
Definition: Database.php:4513
bool $trxAutomaticAtomic
Whether the current transaction was started implicitly by startAtomic()
Definition: Database.php:141
getTopologyRole()
Get the replication topology role of this server.
Definition: Database.php:531
int $trxAtomicCounter
Counter for atomic savepoint identifiers (reset with each transaction)
Definition: Database.php:137
doQuery( $sql)
Run a query and return a DBMS-dependent wrapper or boolean.
onTransactionCommitOrIdle(callable $callback, $fname=__METHOD__)
Run a callback as soon as there is no transaction pending.
Definition: Database.php:3435
Result wrapper for grabbing data queried from an IDatabase object.
indexUnique( $table, $index)
Determines if a given index is unique.
Definition: Database.php:2102
tableNameWithAlias( $table, $alias=false)
Get an aliased table name.
Definition: Database.php:2577
getInfinity()
Find out when &#39;infinity&#39; is.
Definition: Database.php:4804
makeSelectOptions(array $options)
Returns an optional USE INDEX clause to go after the table, and a string to go at the end of the quer...
Definition: Database.php:1714
static string $NOT_APPLICABLE
Idiom used when a cancelable atomic section started the transaction.
Definition: Database.php:207
string $lastQuery
The last SQL query attempted.
Definition: Database.php:176
static int $PING_TTL
How long before it is worth doing a dummy query to test the connection.
Definition: Database.php:224
array $trxAtomicLevels
List of (name, unique ID, savepoint ID) for each active atomic section level.
Definition: Database.php:139
static int $DEADLOCK_TRIES
Number of times to re-try an operation in case of deadlock.
Definition: Database.php:217
string [] $trxWriteCallers
Write query callers of the current transaction.
Definition: Database.php:143
runTransactionListenerCallbacks( $trigger)
Actually run any "transaction listener" callbacks.
Definition: Database.php:3755
getTopologyRootMaster()
Get the host (or address) of the root master server for the replication topology. ...
Definition: Database.php:535
getApproximateLagStatus()
Get a replica DB lag estimate for this server at the start of a transaction.
Definition: Database.php:4406
lastError()
Get a description of the last error.
setFlag( $flag, $remember=self::REMEMBER_NOTHING)
Set a flag for this connection.
Definition: Database.php:759
makeUpdateOptions( $options)
Make UPDATE options for the Database::update function.
Definition: Database.php:2201
IDatabase null $lazyMasterHandle
Lazy handle to the master DB this server replicates from.
Definition: Database.php:72
tableNamesWithIndexClauseOrJOIN( $tables, $use_index=[], $ignore_index=[], $join_conds=[])
Get the aliased table name clause for a FROM clause which might have a JOIN and/or USE INDEX or IGNOR...
Definition: Database.php:2659
prependDatabaseOrSchema( $namespace, $relation, $format)
Definition: Database.php:2535
integer null $affectedRowCount
Rows affected by the last query to query() or its CRUD wrappers.
Definition: Database.php:171
doReleaseSavepoint( $identifier, $fname)
Release a savepoint.
Definition: Database.php:3801
isInsertSelectSafe(array $insertOptions, array $selectOptions)
Definition: Database.php:3104
float $trxWriteAdjDuration
Like trxWriteQueryCount but excludes lock-bound, easy to replicate, queries.
Definition: Database.php:151
initConnection()
Initialize the connection to the database over the wire (or to local files)
Definition: Database.php:298
lockForUpdate( $table, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Lock all rows meeting the given conditions/options FOR UPDATE.
Definition: Database.php:2065
restoreFlags( $state=self::RESTORE_PRIOR)
Restore the flags to their prior state before the last setFlag/clearFlag call.
Definition: Database.php:789
selectSQLText( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Take the same arguments as IDatabase::select() and return the SQL it would use.
Definition: Database.php:1831
makeList( $a, $mode=self::LIST_COMMA)
Makes an encoded list of strings from an array.
Definition: Database.php:2221
__construct(array $params)
Definition: Database.php:251
makeUpdateOptionsArray( $options)
Make UPDATE options array for Database::makeUpdateOptions.
Definition: Database.php:2181
connectionErrorLogger( $errno, $errstr)
Error handler for logging errors during database connection This method should not be used outside of...
Definition: Database.php:871
nativeInsertSelect( $destTable, $srcTable, $varMap, $conds, $fname=__METHOD__, $insertOptions=[], $selectOptions=[], $selectJoinConds=[])
Native server-side implementation of insertSelect() for situations where we don&#39;t want to select ever...
Definition: Database.php:3191
qualifiedTableComponents( $name)
Get the table components needed for a query given the currently selected database.
Definition: Database.php:2495
tableExists( $table, $fname=__METHOD__)
Query whether a given table exists.
getRecordedTransactionLagStatus()
Get the replica DB lag when the current transaction started.
Definition: Database.php:4392
runOnTransactionPreCommitCallbacks()
Actually consume and run any "on transaction pre-commit" callbacks.
Definition: Database.php:3678
const LIST_SET
Definition: Defines.php:40
setTableAliases(array $aliases)
Make certain table names use their own database, schema, and table prefix when passed into SQL querie...
Definition: Database.php:4848
trxTimestamp()
Get the UNIX timestamp of the time that the transaction was established.
Definition: Database.php:554
tablePrefix( $prefix=null)
Get/set the table prefix.
Definition: Database.php:566
insert( $table, $rows, $fname=__METHOD__, $options=[])
INSERT wrapper, inserts an array into a table.
Definition: Database.php:2130
const LIST_OR
Definition: Defines.php:42
const DBO_TRX
Definition: defines.php:12
isQuotedIdentifier( $name)
Returns if the given identifier looks quoted or not according to the database convention for quoting ...
Definition: Database.php:2788
BagOStuff $srvCache
APC cache.
Definition: Database.php:51
registerTempWrites( $ret, $tmpType, $tmpNew, $tmpDel)
Definition: Database.php:1144
cancelAtomic( $fname=__METHOD__, AtomicSectionIdentifier $sectionId=null)
Cancel an atomic section of SQL statements.
Definition: Database.php:3902
getServerInfo()
Get a human-readable string describing the current software version.
Definition: Database.php:527
float bool $lastWriteTime
UNIX timestamp of last write query.
Definition: Database.php:178
deadlockLoop(... $args)
Perform a deadlock-prone transaction.
Definition: Database.php:3374
const DBO_NOBUFFER
Definition: defines.php:10
string $agent
Agent name for query profiling.
Definition: Database.php:83
unlock( $lockName, $method)
Release a lock.
Definition: Database.php:4694
int $trxStatus
Transaction status.
Definition: Database.php:121
doUnlockTables( $method)
Helper function for unlockTables() that handles the actual table unlocking.
Definition: Database.php:4784
getQueryException( $error, $errno, $sql, $fname)
Definition: Database.php:1620
ping(&$rtt=null)
Ping the server and try to reconnect if it there is no connection.
Definition: Database.php:4311
getType()
Get the type of the DBMS (e.g.
lastDoneWrites()
Get the last time the connection may have been used for a write query.
Definition: Database.php:648
LoggerInterface $connLogger
Definition: Database.php:53
tableNamesWithAlias( $tables)
Gets an array of aliased table names.
Definition: Database.php:2603
bitOr( $fieldLeft, $fieldRight)
Definition: Database.php:2332
Class to handle database/schema/prefix specifications for IDatabase.
array [] $trxIdleCallbacks
List of (callable, method name, atomic section id)
Definition: Database.php:155
bool $trxDoneWrites
Whether possible write queries were done in the last transaction started.
Definition: Database.php:133
Basic database interface for live and lazy-loaded relation database handles.
Definition: IDatabase.php:38
float null $trxTimestamp
UNIX timestamp at the time of BEGIN for the last transaction.
Definition: Database.php:127
getLogContext(array $extras=[])
Create a log context to pass to PSR-3 logger functions.
Definition: Database.php:881
selectRow( $table, $vars, $conds, $fname=__METHOD__, $options=[], $join_conds=[])
Wrapper to IDatabase::select() that only fetches one row (via LIMIT)
Definition: Database.php:1914
assertNoOpenTransactions()
Assert that all explicit transactions or atomic sections have been closed.
Definition: Database.php:1449
upsert( $table, array $rows, $uniqueIndexes, array $set, $fname=__METHOD__)
INSERT ON DUPLICATE KEY UPDATE wrapper, upserts an array into a table.
Definition: Database.php:2955
Relational database abstraction object.
Definition: Database.php:49
array [] $trxEndCallbacks
List of (callable, method name, atomic section id) -var array<array{0:callable,1:string,2:AtomicSectionIdentifier|null}>
Definition: Database.php:162
unionQueries( $sqls, $all)
Construct a UNION query.
Definition: Database.php:3237
static attributesFromType( $dbType, $driver=null)
Definition: Database.php:443
wasErrorReissuable()
Determines if the last query error was due to something outside of the query itself.
Definition: Database.php:3346
indexInfo( $table, $index, $fname=__METHOD__)
Get information about an index into an object.
select( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Execute a SELECT query constructed using the various parameters provided.
Definition: Database.php:1823
Advanced database interface for IDatabase handles that include maintenance methods.
buildSubstring( $input, $startPosition, $length=null)
Definition: Database.php:2348
wasConnectionError( $errno)
Do not use this method outside of Database/DBError classes.
Definition: Database.php:3360
bool $trxEndCallbacksSuppressed
Whether to suppress triggering of transaction end callbacks.
Definition: Database.php:168
lastQuery()
Get the last query that sent on account of IDatabase::query()
Definition: Database.php:644
pendingWriteAndCallbackCallers()
List the methods that have write queries or callbacks for the current transaction.
Definition: Database.php:730
commit( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
Commits a transaction previously started using begin()
Definition: Database.php:4066
onTransactionResolution(callable $callback, $fname=__METHOD__)
Run a callback as soon as the current transaction commits or rolls back.
Definition: Database.php:3428
listTables( $prefix=null, $fname=__METHOD__)
List all tables on the database.
Definition: Database.php:4254
$line
Definition: cdb.php:59
doAtomicSection( $fname, callable $callback, $cancelable=self::ATOMIC_NOT_CANCELABLE)
Perform an atomic section of reversable SQL statements from a callback.
Definition: Database.php:3987
restoreErrorHandler()
Restore the previous error handler and return the last PHP error for this DB.
Definition: Database.php:841
array [] $trxPreCommitCallbacks
List of (callable, method name, atomic section id)
Definition: Database.php:157
object resource null $conn
Database connection.
Definition: Database.php:69
assertIsWritableMaster()
Make sure that this server is not marked as a replica nor read-only as a sanity check.
Definition: Database.php:981
setTransactionListener( $name, callable $callback=null)
Run a callback after each time any transaction commits or rolls back.
Definition: Database.php:3579
Used by Database::buildLike() to represent characters that have special meaning in SQL LIKE clauses a...
Definition: LikeMatch.php:10
dbSchema( $schema=null)
Get/set the db schema.
Definition: Database.php:579
static int $TEMP_NORMAL
Writes to this temporary table do not affect lastDoneWrites()
Definition: Database.php:212
dropTable( $tableName, $fName=__METHOD__)
Delete a table.
Definition: Database.php:4795
doInitConnection()
Actually connect to the database over the wire (or to local files)
Definition: Database.php:312
deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds, $fname=__METHOD__)
DELETE where the condition is a join.
Definition: Database.php:3005
masterPosWait(DBMasterPos $pos, $timeout)
Wait for the replica DB to catch up to a given master position.
Definition: Database.php:3409
string $user
User that this instance is currently connected under the name of.
Definition: Database.php:77
lock( $lockName, $method, $timeout=5)
Acquire a named lock.
Definition: Database.php:4688
static float $SLOW_WRITE_SEC
Consider a write slow if it took more than this many seconds.
Definition: Database.php:231
callable $deprecationLogger
Deprecation logging callback.
Definition: Database.php:59
addIdentifierQuotes( $s)
Escape a SQL identifier (e.g.
Definition: Database.php:2775
Error thrown when a query times out.
strencode( $s)
Wrapper for addslashes()
string null $topologyRootMaster
Host (or address) of the root master server for the replication topology.
Definition: Database.php:87
selectFieldsOrOptionsAggregate( $fields, $options)
Definition: Database.php:1998
string $topologyRole
Replication topology role of the server; one of the class ROLE_* constants.
Definition: Database.php:85
static getCacheSetOptions(IDatabase $db1, IDatabase $db2=null)
Merge the result of getSessionLagStatus() for several DBs using the most pessimistic values to estima...
Definition: Database.php:4432
lockTables(array $read, array $write, $method)
Lock specific tables.
Definition: Database.php:4744
makeOrderBy( $options)
Returns an optional ORDER BY.
Definition: Database.php:1811
wasReadOnlyError()
Determines if the last failure was due to the database being read-only.
Definition: Database.php:3342
selectRowCount( $tables, $var=' *', $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Get the number of rows in dataset.
Definition: Database.php:1949
wasConnectionLoss()
Determines if the last query error was due to a dropped connection.
Definition: Database.php:3338
int $trxWriteQueryCount
Number of write queries for the current transaction.
Definition: Database.php:147
tableLocksHaveTransactionScope()
Checks if table locks acquired by lockTables() are transaction-bound in their scope.
Definition: Database.php:4740
getSchemaVars()
Get schema variables.
Definition: Database.php:4665
Exception class for attempted DB write access to a DBConnRef with the DB_REPLICA role.
int [] $priorFlags
Prior flags member variable values.
Definition: Database.php:111
closeConnection()
Closes underlying database connection.
string bool $lastPhpError
Definition: Database.php:180
lockIsFree( $lockName, $method)
Check to see if a named lock is not locked by any thread (non-blocking)
Definition: Database.php:4681
makeGroupByWithHaving( $options)
Returns an optional GROUP BY with an optional HAVING.
Definition: Database.php:1785
bool $cliMode
Whether this PHP instance is for a CLI script.
Definition: Database.php:81
tableNames(... $tables)
Fetch a number of table names into an array This is handy when you need to construct SQL for joins...
Definition: Database.php:2546
runOnAtomicSectionCancelCallbacks( $trigger, array $sectionIds=null)
Actually run any "atomic section cancel" callbacks.
Definition: Database.php:3712
doBegin( $fname)
Issues the BEGIN command to the database server.
Definition: Database.php:4062
wasDeadlock()
Determines if the last failure was due to a deadlock.
Definition: Database.php:3330
replace( $table, $uniqueIndexes, $rows, $fname=__METHOD__)
REPLACE query wrapper.
Definition: Database.php:2870
streamStatementEnd(&$sql, &$newLine)
Called by sourceStream() to check if we&#39;ve reached a statement end.
Definition: Database.php:4594
Class used for token representing identifiers for atomic sections from IDatabase instances.
getLag()
Get the amount of replication lag for this database server.
Definition: Database.php:4449
fetchRow( $res)
Fetch the next row from the given result object, in associative array form.
duplicateTableStructure( $oldName, $newName, $temporary=false, $fname=__METHOD__)
Creates a new table with structure copied from existing table.
Definition: Database.php:4248
anyString()
Returns a token for buildLike() that denotes a &#39;&#39; to be used in a LIKE query.
Definition: Database.php:2834
array [] $tableAliases
Current map of (table => (dbname, schema, prefix) map)
Definition: Database.php:102
wasLockTimeout()
Determines if the last failure was due to a lock timeout.
Definition: Database.php:3334
static factory( $type, $params=[], $connect=self::NEW_CONNECTED)
Construct a Database subclass instance given a database type and parameters.
Definition: Database.php:389
useIndexClause( $index)
USE INDEX clause.
Definition: Database.php:2852
unionSupportsOrderAndLimit()
Determine if the RDBMS supports ORDER BY and LIMIT for separate subqueries within UNION...
Definition: Database.php:3233
updateTrxWriteQueryTime( $sql, $runtime, $affected)
Update the estimated run-time of a query, not counting large row lock times.
Definition: Database.php:1393
array null $schemaVars
Current variables use for schema element placeholders.
Definition: Database.php:106
wasQueryTimeout( $error, $errno)
Checks whether the cause of the error is detected to be a timeout.
Definition: Database.php:1568
getBindingHandle()
Get the underlying binding connection handle.
Definition: Database.php:4877
pendingWriteRowsAffected()
Get the number of affected rows from pending write queries.
Definition: Database.php:718
__toString()
Get a debugging string that mentions the database type, the ID of this instance, and the ID of any un...
Definition: Database.php:4888
string [] $indexAliases
Current map of (index alias => index)
Definition: Database.php:104
array [] $trxSectionCancelCallbacks
List of (callable, method name, atomic section id)
Definition: Database.php:164
resultObject( $result)
Take a query result and wrap it in an iterable result wrapper if necessary.
Definition: Database.php:4299
fieldHasBit( $field, $flags)
Definition: Database.php:4862
modifyCallbacksForCancel(array $sectionIds, AtomicSectionIdentifier $newSectionId=null)
Update callbacks that were owned by cancelled atomic sections.
Definition: Database.php:3544
string $password
Password used to establish the current connection.
Definition: Database.php:79
float $trxWriteDuration
Seconds spent in write queries for the current transaction.
Definition: Database.php:145
getQueryExceptionAndLog( $error, $errno, $sql, $fname)
Definition: Database.php:1598
consumeTrxShortId()
Reset the transaction ID and return the old one.
Definition: Database.php:1551
onTransactionPreCommitOrIdle(callable $callback, $fname=__METHOD__)
Run a callback before the current transaction commits or now if there is none.
Definition: Database.php:3452
sourceStream( $fp, callable $lineCallback=null, callable $resultCallback=null, $fname=__METHOD__, callable $inputCallback=null)
Read and execute commands from an open file handle.
Definition: Database.php:4517
$matches
float $lastRoundTripEstimate
Query round trip time estimate.
Definition: Database.php:182
getReplicaPos()
Get the replication position of this replica DB.
Definition: Database.php:3414
getDefaultSchemaVars()
Get schema variables to use if none have been set via setSchemaVars().
Definition: Database.php:4677