MediaWiki  master
Database.php
Go to the documentation of this file.
1 <?php
26 namespace Wikimedia\Rdbms;
27 
28 use BagOStuff;
29 use HashBagOStuff;
30 use InvalidArgumentException;
31 use LogicException;
32 use Psr\Log\LoggerAwareInterface;
33 use Psr\Log\LoggerInterface;
34 use Psr\Log\NullLogger;
35 use RuntimeException;
36 use Throwable;
37 use UnexpectedValueException;
38 use Wikimedia\Assert\Assert;
39 use Wikimedia\AtEase\AtEase;
40 use Wikimedia\RequestTimeout\CriticalSectionProvider;
41 use Wikimedia\RequestTimeout\CriticalSectionScope;
42 use Wikimedia\ScopedCallback;
43 use Wikimedia\Timestamp\ConvertibleTimestamp;
44 
52 abstract class Database implements IDatabase, IMaintainableDatabase, LoggerAwareInterface {
54  protected $srvCache;
56  protected $csProvider;
58  protected $connLogger;
60  protected $queryLogger;
62  protected $replLogger;
64  protected $errorLogger;
66  protected $deprecationLogger;
68  protected $profiler;
70  protected $trxProfiler;
71 
73  protected $currentDomain;
74 
75  // phpcs:ignore MediaWiki.Commenting.PropertyDocumentation.ObjectTypeHintVar
77  protected $conn;
78 
81 
83  protected $server;
85  protected $user;
87  protected $password;
89  protected $serverName;
91  protected $cliMode;
93  protected $agent;
95  protected $topologyRole;
99  protected $connectionParams;
104 
106  protected $flags;
108  protected $lbInfo = [];
110  protected $delimiter = ';';
112  protected $tableAliases = [];
114  protected $indexAliases = [];
116  protected $schemaVars;
117 
119  private $htmlErrors;
121  private $priorFlags = [];
122 
124  protected $sessionNamedLocks = [];
126  protected $sessionTempTables = [];
128  protected $sessionDirtyTempTables = [];
129 
131  private $trxId = '';
133  private $trxStatus = self::STATUS_TRX_NONE;
139  private $trxTimestamp = null;
141  private $trxReplicaLagStatus = null;
143  private $trxFname = null;
145  private $trxDoneWrites = false;
147  private $trxAutomatic = false;
149  private $trxAtomicCounter = 0;
151  private $trxAtomicLevels = [];
153  private $trxAutomaticAtomic = false;
155  private $trxWriteCallers = [];
157  private $trxWriteDuration = 0.0;
159  private $trxWriteQueryCount = 0;
163  private $trxWriteAdjDuration = 0.0;
174  private $trxEndCallbacks = [];
180  private $trxEndCallbacksSuppressed = false;
181 
183  protected $affectedRowCount;
184 
186  private $lastPing = 0.0;
188  private $lastQuery = '';
190  private $lastWriteTime = false;
192  private $lastPhpError = false;
194  private $lastRoundTripEstimate = 0.0;
195 
197  private $csmId;
199  private $csmFname;
201  private $csmError;
202 
204  private $ownerId;
205 
207  public const ATTR_DB_IS_FILE = 'db-is-file';
209  public const ATTR_DB_LEVEL_LOCKING = 'db-level-locking';
211  public const ATTR_SCHEMAS_AS_TABLE_GROUPS = 'supports-schemas';
212 
214  public const NEW_UNCONNECTED = 0;
216  public const NEW_CONNECTED = 1;
217 
219  public const STATUS_TRX_ERROR = 1;
221  public const STATUS_TRX_OK = 2;
223  public const STATUS_TRX_NONE = 3;
224 
226  private const NOT_APPLICABLE = 'n/a';
228  private const SAVEPOINT_PREFIX = 'wikimedia_rdbms_atomic';
229 
231  private const TEMP_NORMAL = 1;
233  private const TEMP_PSEUDO_PERMANENT = 2;
234 
236  private const DEADLOCK_TRIES = 4;
238  private const DEADLOCK_DELAY_MIN = 500000;
240  private const DEADLOCK_DELAY_MAX = 1500000;
241 
243  private const PING_TTL = 1.0;
245  private const PING_QUERY = 'SELECT 1 AS ping';
246 
248  private const TINY_WRITE_SEC = 0.010;
250  private const SLOW_WRITE_SEC = 0.500;
252  private const SMALL_WRITE_ROWS = 100;
253 
255  protected const MUTABLE_FLAGS = [
256  'DBO_DEBUG',
257  'DBO_NOBUFFER',
258  'DBO_TRX',
259  'DBO_DDLMODE',
260  ];
262  protected const DBO_MUTABLE = (
264  );
265 
267  protected const CONN_HOST = 'host';
269  protected const CONN_USER = 'user';
271  protected const CONN_PASSWORD = 'password';
273  protected const CONN_INITIAL_DB = 'dbname';
275  protected const CONN_INITIAL_SCHEMA = 'schema';
277  protected const CONN_INITIAL_TABLE_PREFIX = 'tablePrefix';
278 
284  public function __construct( array $params ) {
285  $this->connectionParams = [
286  self::CONN_HOST => ( isset( $params['host'] ) && $params['host'] !== '' )
287  ? $params['host']
288  : null,
289  self::CONN_USER => ( isset( $params['user'] ) && $params['user'] !== '' )
290  ? $params['user']
291  : null,
292  self::CONN_INITIAL_DB => ( isset( $params['dbname'] ) && $params['dbname'] !== '' )
293  ? $params['dbname']
294  : null,
295  self::CONN_INITIAL_SCHEMA => ( isset( $params['schema'] ) && $params['schema'] !== '' )
296  ? $params['schema']
297  : null,
298  self::CONN_PASSWORD => is_string( $params['password'] ) ? $params['password'] : null,
299  self::CONN_INITIAL_TABLE_PREFIX => (string)$params['tablePrefix']
300  ];
301 
302  $this->lbInfo = $params['lbInfo'] ?? [];
303  $this->lazyMasterHandle = $params['lazyMasterHandle'] ?? null;
304  $this->connectionVariables = $params['variables'] ?? [];
305 
306  $this->flags = (int)$params['flags'];
307  $this->cliMode = (bool)$params['cliMode'];
308  $this->agent = (string)$params['agent'];
309  $this->serverName = $params['serverName'];
310  $this->topologyRole = $params['topologyRole'];
311  $this->topologyRootMaster = $params['topologicalMaster'];
312  $this->nonNativeInsertSelectBatchSize = $params['nonNativeInsertSelectBatchSize'] ?? 10000;
313 
314  $this->srvCache = $params['srvCache'];
315  $this->profiler = is_callable( $params['profiler'] ) ? $params['profiler'] : null;
316  $this->trxProfiler = $params['trxProfiler'];
317  $this->connLogger = $params['connLogger'];
318  $this->queryLogger = $params['queryLogger'];
319  $this->replLogger = $params['replLogger'];
320  $this->errorLogger = $params['errorLogger'];
321  $this->deprecationLogger = $params['deprecationLogger'];
322 
323  $this->csProvider = $params['criticalSectionProvider'] ?? null;
324 
325  // Set initial dummy domain until open() sets the final DB/prefix
326  $this->currentDomain = new DatabaseDomain(
327  $params['dbname'] != '' ? $params['dbname'] : null,
328  $params['schema'] != '' ? $params['schema'] : null,
329  $params['tablePrefix']
330  );
331 
332  $this->ownerId = $params['ownerId'] ?? null;
333  }
334 
343  final public function initConnection() {
344  if ( $this->isOpen() ) {
345  throw new LogicException( __METHOD__ . ': already connected' );
346  }
347  // Establish the connection
348  $this->doInitConnection();
349  }
350 
357  protected function doInitConnection() {
358  $this->open(
359  $this->connectionParams[self::CONN_HOST],
360  $this->connectionParams[self::CONN_USER],
361  $this->connectionParams[self::CONN_PASSWORD],
362  $this->connectionParams[self::CONN_INITIAL_DB],
363  $this->connectionParams[self::CONN_INITIAL_SCHEMA],
364  $this->connectionParams[self::CONN_INITIAL_TABLE_PREFIX]
365  );
366  }
367 
379  abstract protected function open( $server, $user, $password, $db, $schema, $tablePrefix );
380 
436  final public static function factory( $type, $params = [], $connect = self::NEW_CONNECTED ) {
437  $class = self::getClass( $type, $params['driver'] ?? null );
438 
439  if ( class_exists( $class ) && is_subclass_of( $class, IDatabase::class ) ) {
440  $params += [
441  // Default configuration
442  'host' => null,
443  'user' => null,
444  'password' => null,
445  'dbname' => null,
446  'schema' => null,
447  'tablePrefix' => '',
448  'flags' => 0,
449  'variables' => [],
450  'lbInfo' => [],
451  'cliMode' => ( PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg' ),
452  'agent' => '',
453  'ownerId' => null,
454  'serverName' => null,
455  'topologyRole' => null,
456  'topologicalMaster' => null,
457  // Objects and callbacks
458  'lazyMasterHandle' => $params['lazyMasterHandle'] ?? null,
459  'srvCache' => $params['srvCache'] ?? new HashBagOStuff(),
460  'profiler' => $params['profiler'] ?? null,
461  'trxProfiler' => $params['trxProfiler'] ?? new TransactionProfiler(),
462  'connLogger' => $params['connLogger'] ?? new NullLogger(),
463  'queryLogger' => $params['queryLogger'] ?? new NullLogger(),
464  'replLogger' => $params['replLogger'] ?? new NullLogger(),
465  'errorLogger' => $params['errorLogger'] ?? static function ( Throwable $e ) {
466  trigger_error( get_class( $e ) . ': ' . $e->getMessage(), E_USER_WARNING );
467  },
468  'deprecationLogger' => $params['deprecationLogger'] ?? static function ( $msg ) {
469  trigger_error( $msg, E_USER_DEPRECATED );
470  }
471  ];
472 
474  $conn = new $class( $params );
475  if ( $connect === self::NEW_CONNECTED ) {
476  $conn->initConnection();
477  }
478  } else {
479  $conn = null;
480  }
481 
482  return $conn;
483  }
484 
492  final public static function attributesFromType( $dbType, $driver = null ) {
493  static $defaults = [
494  self::ATTR_DB_IS_FILE => false,
495  self::ATTR_DB_LEVEL_LOCKING => false,
496  self::ATTR_SCHEMAS_AS_TABLE_GROUPS => false
497  ];
498 
499  $class = self::getClass( $dbType, $driver );
500 
501  return call_user_func( [ $class, 'getAttributes' ] ) + $defaults;
502  }
503 
510  private static function getClass( $dbType, $driver = null ) {
511  // For database types with built-in support, the below maps type to IDatabase
512  // implementations. For types with multiple driver implementations (PHP extensions),
513  // an array can be used, keyed by extension name. In case of an array, the
514  // optional 'driver' parameter can be used to force a specific driver. Otherwise,
515  // we auto-detect the first available driver. For types without built-in support,
516  // an class named "Database<Type>" us used, eg. DatabaseFoo for type 'foo'.
517  static $builtinTypes = [
518  'mysql' => [ 'mysqli' => DatabaseMysqli::class ],
519  'sqlite' => DatabaseSqlite::class,
520  'postgres' => DatabasePostgres::class,
521  ];
522 
523  $dbType = strtolower( $dbType );
524 
525  if ( !isset( $builtinTypes[$dbType] ) ) {
526  // Not a built in type, assume standard naming scheme
527  return 'Database' . ucfirst( $dbType );
528  }
529 
530  $class = false;
531  $possibleDrivers = $builtinTypes[$dbType];
532  if ( is_string( $possibleDrivers ) ) {
533  $class = $possibleDrivers;
534  } elseif ( (string)$driver !== '' ) {
535  if ( !isset( $possibleDrivers[$driver] ) ) {
536  throw new InvalidArgumentException( __METHOD__ .
537  " type '$dbType' does not support driver '{$driver}'" );
538  }
539 
540  $class = $possibleDrivers[$driver];
541  } else {
542  foreach ( $possibleDrivers as $posDriver => $possibleClass ) {
543  if ( extension_loaded( $posDriver ) ) {
544  $class = $possibleClass;
545  break;
546  }
547  }
548  }
549 
550  if ( $class === false ) {
551  throw new InvalidArgumentException( __METHOD__ .
552  " no viable database extension found for type '$dbType'" );
553  }
554 
555  return $class;
556  }
557 
563  protected static function getAttributes() {
564  return [];
565  }
566 
574  public function setLogger( LoggerInterface $logger ) {
575  $this->queryLogger = $logger;
576  }
577 
578  public function getServerInfo() {
579  return $this->getServerVersion();
580  }
581 
582  public function getTopologyBasedServerId() {
583  return null;
584  }
585 
586  public function getTopologyRole() {
587  return $this->topologyRole;
588  }
589 
590  public function getTopologyRootPrimary() {
592  }
593 
594  final public function trxLevel() {
595  return ( $this->trxId != '' ) ? 1 : 0;
596  }
597 
598  public function trxTimestamp() {
599  return $this->trxLevel() ? $this->trxTimestamp : null;
600  }
601 
606  public function trxStatus() {
607  return $this->trxStatus;
608  }
609 
610  public function tablePrefix( $prefix = null ) {
611  $old = $this->currentDomain->getTablePrefix();
612 
613  if ( $prefix !== null ) {
614  $this->currentDomain = new DatabaseDomain(
615  $this->currentDomain->getDatabase(),
616  $this->currentDomain->getSchema(),
617  $prefix
618  );
619  }
620 
621  return $old;
622  }
623 
624  public function dbSchema( $schema = null ) {
625  $old = $this->currentDomain->getSchema();
626 
627  if ( $schema !== null ) {
628  if ( $schema !== '' && $this->getDBname() === null ) {
629  throw new DBUnexpectedError(
630  $this,
631  "Cannot set schema to '$schema'; no database set"
632  );
633  }
634 
635  $this->currentDomain = new DatabaseDomain(
636  $this->currentDomain->getDatabase(),
637  // DatabaseDomain uses null for unspecified schemas
638  ( $schema !== '' ) ? $schema : null,
639  $this->currentDomain->getTablePrefix()
640  );
641  }
642 
643  return (string)$old;
644  }
645 
650  protected function relationSchemaQualifier() {
651  return $this->dbSchema();
652  }
653 
654  public function getLBInfo( $name = null ) {
655  if ( $name === null ) {
656  return $this->lbInfo;
657  }
658 
659  if ( array_key_exists( $name, $this->lbInfo ) ) {
660  return $this->lbInfo[$name];
661  }
662 
663  return null;
664  }
665 
666  public function setLBInfo( $nameOrArray, $value = null ) {
667  if ( is_array( $nameOrArray ) ) {
668  $this->lbInfo = $nameOrArray;
669  } elseif ( is_string( $nameOrArray ) ) {
670  if ( $value !== null ) {
671  $this->lbInfo[$nameOrArray] = $value;
672  } else {
673  unset( $this->lbInfo[$nameOrArray] );
674  }
675  } else {
676  throw new InvalidArgumentException( "Got non-string key" );
677  }
678  }
679 
686  protected function getLazyMasterHandle() {
688  }
689 
694  public function implicitOrderby() {
695  return true;
696  }
697 
698  public function lastQuery() {
699  return $this->lastQuery;
700  }
701 
702  public function lastDoneWrites() {
703  return $this->lastWriteTime ?: false;
704  }
705 
706  public function writesPending() {
707  return $this->trxLevel() && $this->trxDoneWrites;
708  }
709 
710  public function writesOrCallbacksPending() {
711  return $this->trxLevel() && (
712  $this->trxDoneWrites ||
713  $this->trxPostCommitOrIdleCallbacks ||
714  $this->trxPreCommitOrIdleCallbacks ||
715  $this->trxEndCallbacks ||
717  );
718  }
719 
723  final protected function getTransactionRoundId() {
724  if ( $this->getFlag( self::DBO_TRX ) ) {
725  // LoadBalancer transaction round participation is enabled for this DB handle;
726  // get the ID of the active explicit transaction round (if any)
727  $id = $this->getLBInfo( self::LB_TRX_ROUND_ID );
728 
729  return is_string( $id ) ? $id : null;
730  }
731 
732  return null;
733  }
734 
735  public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL ) {
736  if ( !$this->trxLevel() ) {
737  return false;
738  } elseif ( !$this->trxDoneWrites ) {
739  return 0.0;
740  }
741 
742  switch ( $type ) {
743  case self::ESTIMATE_DB_APPLY:
744  return $this->pingAndCalculateLastTrxApplyTime();
745  default: // everything
747  }
748  }
749 
753  private function pingAndCalculateLastTrxApplyTime() {
754  // passed by reference
755  $rtt = null;
756  $this->ping( $rtt );
757 
758  $rttAdjTotal = $this->trxWriteAdjQueryCount * $rtt;
759  $applyTime = max( $this->trxWriteAdjDuration - $rttAdjTotal, 0 );
760  // For omitted queries, make them count as something at least
761  $omitted = $this->trxWriteQueryCount - $this->trxWriteAdjQueryCount;
762  $applyTime += self::TINY_WRITE_SEC * $omitted;
763 
764  return $applyTime;
765  }
766 
767  public function pendingWriteCallers() {
768  return $this->trxLevel() ? $this->trxWriteCallers : [];
769  }
770 
779  public function pendingWriteAndCallbackCallers() {
780  $fnames = $this->pendingWriteCallers();
781  foreach ( [
782  $this->trxPostCommitOrIdleCallbacks,
783  $this->trxPreCommitOrIdleCallbacks,
784  $this->trxEndCallbacks,
785  $this->trxSectionCancelCallbacks
786  ] as $callbacks ) {
787  foreach ( $callbacks as $callback ) {
788  $fnames[] = $callback[1];
789  }
790  }
791 
792  return $fnames;
793  }
794 
798  private function flatAtomicSectionList() {
799  return array_reduce( $this->trxAtomicLevels, static function ( $accum, $v ) {
800  return $accum === null ? $v[0] : "$accum, " . $v[0];
801  } );
802  }
803 
804  public function isOpen() {
805  return (bool)$this->conn;
806  }
807 
808  public function setFlag( $flag, $remember = self::REMEMBER_NOTHING ) {
809  if ( $flag & ~static::DBO_MUTABLE ) {
810  throw new DBUnexpectedError(
811  $this,
812  "Got $flag (allowed: " . implode( ', ', static::MUTABLE_FLAGS ) . ')'
813  );
814  }
815 
816  if ( $remember === self::REMEMBER_PRIOR ) {
817  $this->priorFlags[] = $this->flags;
818  }
819 
820  $this->flags |= $flag;
821  }
822 
823  public function clearFlag( $flag, $remember = self::REMEMBER_NOTHING ) {
824  if ( $flag & ~static::DBO_MUTABLE ) {
825  throw new DBUnexpectedError(
826  $this,
827  "Got $flag (allowed: " . implode( ', ', static::MUTABLE_FLAGS ) . ')'
828  );
829  }
830 
831  if ( $remember === self::REMEMBER_PRIOR ) {
832  $this->priorFlags[] = $this->flags;
833  }
834 
835  $this->flags &= ~$flag;
836  }
837 
838  public function restoreFlags( $state = self::RESTORE_PRIOR ) {
839  if ( !$this->priorFlags ) {
840  return;
841  }
842 
843  if ( $state === self::RESTORE_INITIAL ) {
844  $this->flags = reset( $this->priorFlags );
845  $this->priorFlags = [];
846  } else {
847  $this->flags = array_pop( $this->priorFlags );
848  }
849  }
850 
851  public function getFlag( $flag ) {
852  return ( ( $this->flags & $flag ) === $flag );
853  }
854 
855  public function getDomainID() {
856  return $this->currentDomain->getId();
857  }
858 
859  public function fetchObject( IResultWrapper $res ) {
860  return $res->fetchObject();
861  }
862 
863  public function fetchRow( IResultWrapper $res ) {
864  return $res->fetchRow();
865  }
866 
867  public function numRows( $res ) {
868  if ( is_bool( $res ) ) {
869  return 0;
870  } else {
871  return $res->numRows();
872  }
873  }
874 
875  public function freeResult( IResultWrapper $res ) {
876  $res->free();
877  }
878 
888  abstract public function indexInfo( $table, $index, $fname = __METHOD__ );
889 
897  abstract public function strencode( $s );
898 
902  protected function installErrorHandler() {
903  $this->lastPhpError = false;
904  $this->htmlErrors = ini_set( 'html_errors', '0' );
905  set_error_handler( [ $this, 'connectionErrorLogger' ] );
906  }
907 
913  protected function restoreErrorHandler() {
914  restore_error_handler();
915  if ( $this->htmlErrors !== false ) {
916  ini_set( 'html_errors', $this->htmlErrors );
917  }
918 
919  return $this->getLastPHPError();
920  }
921 
925  protected function getLastPHPError() {
926  if ( $this->lastPhpError ) {
927  $error = preg_replace( '!\[<a.*</a>\]!', '', $this->lastPhpError );
928  $error = preg_replace( '!^.*?:\s?(.*)$!', '$1', $error );
929 
930  return $error;
931  }
932 
933  return false;
934  }
935 
944  public function connectionErrorLogger( $errno, $errstr ) {
945  $this->lastPhpError = $errstr;
946  }
947 
954  protected function getLogContext( array $extras = [] ) {
955  return array_merge(
956  [
957  'db_server' => $this->getServerName(),
958  'db_name' => $this->getDBname(),
959  'db_user' => $this->connectionParams[self::CONN_USER],
960  ],
961  $extras
962  );
963  }
964 
965  final public function close( $fname = __METHOD__, $owner = null ) {
966  $error = null; // error to throw after disconnecting
967 
968  $wasOpen = (bool)$this->conn;
969  // This should mostly do nothing if the connection is already closed
970  if ( $this->conn ) {
971  // Roll back any dangling transaction first
972  if ( $this->trxLevel() ) {
973  if ( $this->trxAtomicLevels ) {
974  // Cannot let incomplete atomic sections be committed
975  $levels = $this->flatAtomicSectionList();
976  $error = "$fname: atomic sections $levels are still open";
977  } elseif ( $this->trxAutomatic ) {
978  // Only the connection manager can commit non-empty DBO_TRX transactions
979  // (empty ones we can silently roll back)
980  if ( $this->writesOrCallbacksPending() ) {
981  $error = "$fname: " .
982  "expected mass rollback of all peer transactions (DBO_TRX set)";
983  }
984  } else {
985  // Manual transactions should have been committed or rolled
986  // back, even if empty.
987  $error = "$fname: transaction is still open (from {$this->trxFname})";
988  }
989 
990  if ( $this->trxEndCallbacksSuppressed && $error === null ) {
991  $error = "$fname: callbacks are suppressed; cannot properly commit";
992  }
993 
994  // Rollback the changes and run any callbacks as needed
995  $this->rollback( __METHOD__, self::FLUSHING_INTERNAL );
997  }
998 
999  // Close the actual connection in the binding handle
1000  $closed = $this->closeConnection();
1001  } else {
1002  $closed = true; // already closed; nothing to do
1003  }
1004 
1005  $this->conn = null;
1006 
1007  // Log or throw any unexpected errors after having disconnected
1008  if ( $error !== null ) {
1009  // T217819, T231443: if this is probably just LoadBalancer trying to recover from
1010  // errors and shutdown, then log any problems and move on since the request has to
1011  // end one way or another. Throwing errors is not very useful at some point.
1012  if ( $this->ownerId !== null && $owner === $this->ownerId ) {
1013  $this->queryLogger->error( $error );
1014  } else {
1015  throw new DBUnexpectedError( $this, $error );
1016  }
1017  }
1018 
1019  // Note that various subclasses call close() at the start of open(), which itself is
1020  // called by replaceLostConnection(). In that case, just because onTransactionResolution()
1021  // callbacks are pending does not mean that an exception should be thrown. Rather, they
1022  // will be executed after the reconnection step.
1023  if ( $wasOpen ) {
1024  // Double check that no callbacks are dangling
1025  $fnames = $this->pendingWriteAndCallbackCallers();
1026  if ( $fnames ) {
1027  throw new RuntimeException(
1028  "Transaction callbacks are still pending: " . implode( ', ', $fnames )
1029  );
1030  }
1031  }
1032 
1033  return $closed;
1034  }
1035 
1044  final protected function assertHasConnectionHandle() {
1045  if ( !$this->isOpen() ) {
1046  throw new DBUnexpectedError( $this, "DB connection was already closed" );
1047  }
1048  }
1049 
1056  protected function assertIsWritablePrimary() {
1057  $info = $this->getReadOnlyReason();
1058  if ( $info ) {
1059  list( $reason, $source ) = $info;
1060  if ( $source === 'role' ) {
1061  throw new DBReadOnlyRoleError( $this, "Database is read-only: $reason" );
1062  } else {
1063  throw new DBReadOnlyError( $this, "Database is read-only: $reason" );
1064  }
1065  }
1066  }
1067 
1072  protected function assertIsWritableMaster() {
1073  wfDeprecated( __METHOD__, '1.37' );
1074  $this->assertIsWritablePrimary();
1075  }
1076 
1082  abstract protected function closeConnection();
1083 
1110  abstract protected function doQuery( $sql );
1111 
1129  protected function isWriteQuery( $sql, $flags ) {
1130  if (
1131  $this->fieldHasBit( $flags, self::QUERY_CHANGE_ROWS ) ||
1132  $this->fieldHasBit( $flags, self::QUERY_CHANGE_SCHEMA ) ||
1133  $this->fieldHasBit( $flags, self::QUERY_CHANGE_LOCKS )
1134  ) {
1135  return true;
1136  } elseif ( $this->fieldHasBit( $flags, self::QUERY_CHANGE_NONE ) ) {
1137  return false;
1138  }
1139  // BEGIN and COMMIT queries are considered read queries here.
1140  // Database backends and drivers (MySQL, MariaDB, php-mysqli) generally
1141  // treat these as write queries, in that their results have "affected rows"
1142  // as meta data as from writes, instead of "num rows" as from reads.
1143  // But, we treat them as read queries because when reading data (from
1144  // either replica or primary DB) we use transactions to enable repeatable-read
1145  // snapshots, which ensures we get consistent results from the same snapshot
1146  // for all queries within a request. Use cases:
1147  // - Treating these as writes would trigger ChronologyProtector (see method doc).
1148  // - We use this method to reject writes to replicas, but we need to allow
1149  // use of transactions on replicas for read snapshots. This is fine given
1150  // that transactions by themselves don't make changes, only actual writes
1151  // within the transaction matter, which we still detect.
1152  return !preg_match(
1153  '/^\s*(?:SELECT|BEGIN|ROLLBACK|COMMIT|SAVEPOINT|RELEASE|SET|SHOW|EXPLAIN|USE|\‍(SELECT)\b/i',
1154  $sql
1155  );
1156  }
1157 
1162  protected function getQueryVerb( $sql ) {
1163  return preg_match( '/^\s*([a-z]+)/i', $sql, $m ) ? strtoupper( $m[1] ) : null;
1164  }
1165 
1180  protected function isTransactableQuery( $sql ) {
1181  return !in_array(
1182  $this->getQueryVerb( $sql ),
1183  [ 'BEGIN', 'ROLLBACK', 'COMMIT', 'SET', 'SHOW', 'CREATE', 'ALTER', 'USE', 'SHOW' ],
1184  true
1185  );
1186  }
1187 
1196  protected function getTempTableWrites( $sql, $pseudoPermanent ) {
1197  // Regexes for basic queries that can create/change/drop temporary tables.
1198  // For simplicity, this only looks for tables with sensible, alphanumeric, names;
1199  // temporary tables only need simple programming names anyway.
1200  static $regexes = null;
1201  if ( $regexes === null ) {
1202  // Regex with a group for quoted table 0 and a group for quoted tables 1..N
1203  $qts = '((?:\w+|`\w+`|\'\w+\'|"\w+")(?:\s*,\s*(?:\w+|`\w+`|\'\w+\'|"\w+"))*)';
1204  // Regex to get query verb, table 0, and tables 1..N
1205  $regexes = [
1206  // DML write queries
1207  "/^(INSERT|REPLACE)\s+(?:\w+\s+)*?INTO\s+$qts/i",
1208  "/^(UPDATE)(?:\s+OR\s+\w+|\s+IGNORE|\s+ONLY)?\s+$qts/i",
1209  "/^(DELETE)\s+(?:\w+\s+)*?FROM(?:\s+ONLY)?\s+$qts/i",
1210  // DDL write queries
1211  "/^(CREATE)\s+TEMPORARY\s+TABLE(?:\s+IF\s+NOT\s+EXISTS)?\s+$qts/i",
1212  "/^(DROP)\s+(?:TEMPORARY\s+)?TABLE(?:\s+IF\s+EXISTS)?\s+$qts/i",
1213  "/^(TRUNCATE)\s+(?:TEMPORARY\s+)?TABLE\s+$qts/i",
1214  "/^(ALTER)\s+TABLE\s+$qts/i"
1215  ];
1216  }
1217 
1218  $queryVerb = null;
1219  $queryTables = [];
1220  foreach ( $regexes as $regex ) {
1221  if ( preg_match( $regex, $sql, $m, PREG_UNMATCHED_AS_NULL ) ) {
1222  $queryVerb = $m[1];
1223  $allTables = preg_split( '/\s*,\s*/', $m[2] );
1224  foreach ( $allTables as $quotedTable ) {
1225  $queryTables[] = trim( $quotedTable, "\"'`" );
1226  }
1227  break;
1228  }
1229  }
1230 
1231  $tempTableChanges = [];
1232  foreach ( $queryTables as $table ) {
1233  if ( $queryVerb === 'CREATE' ) {
1234  // Record the type of temporary table being created
1235  $tableType = $pseudoPermanent ? self::TEMP_PSEUDO_PERMANENT : self::TEMP_NORMAL;
1236  } else {
1237  $tableType = $this->sessionTempTables[$table] ?? null;
1238  }
1239 
1240  if ( $tableType !== null ) {
1241  $tempTableChanges[] = [ $tableType, $queryVerb, $table ];
1242  }
1243  }
1244 
1245  return $tempTableChanges;
1246  }
1247 
1252  protected function registerTempWrites( $ret, array $changes ) {
1253  if ( $ret === false ) {
1254  return;
1255  }
1256 
1257  foreach ( $changes as list( $tmpTableType, $verb, $table ) ) {
1258  switch ( $verb ) {
1259  case 'CREATE':
1260  $this->sessionTempTables[$table] = $tmpTableType;
1261  break;
1262  case 'DROP':
1263  unset( $this->sessionTempTables[$table] );
1264  unset( $this->sessionDirtyTempTables[$table] );
1265  break;
1266  case 'TRUNCATE':
1267  unset( $this->sessionDirtyTempTables[$table] );
1268  break;
1269  default:
1270  $this->sessionDirtyTempTables[$table] = 1;
1271  break;
1272  }
1273  }
1274  }
1275 
1283  protected function isPristineTemporaryTable( $table ) {
1284  $rawTable = $this->tableName( $table, 'raw' );
1285 
1286  return (
1287  isset( $this->sessionTempTables[$rawTable] ) &&
1288  !isset( $this->sessionDirtyTempTables[$rawTable] )
1289  );
1290  }
1291 
1292  public function query( $sql, $fname = __METHOD__, $flags = self::QUERY_NORMAL ) {
1293  $flags = (int)$flags; // b/c; this field used to be a bool
1294  // Double check that the SQL query is appropriate in the current context and is
1295  // allowed for an outside caller (e.g. does not break transaction/session tracking).
1296  $this->assertQueryIsCurrentlyAllowed( $sql, $fname );
1297 
1298  // Send the query to the server and fetch any corresponding errors
1299  list( $ret, $err, $errno, $unignorable ) = $this->executeQuery( $sql, $fname, $flags );
1300  if ( $ret === false ) {
1301  $ignoreErrors = $this->fieldHasBit( $flags, self::QUERY_SILENCE_ERRORS );
1302  // Throw an error unless both the ignore flag was set and a rollback is not needed
1303  $this->reportQueryError( $err, $errno, $sql, $fname, $ignoreErrors && !$unignorable );
1304  }
1305 
1306  return $ret;
1307  }
1308 
1329  final protected function executeQuery( $sql, $fname, $flags ) {
1330  $this->assertHasConnectionHandle();
1331 
1332  $priorTransaction = $this->trxLevel();
1333 
1334  if ( $this->isWriteQuery( $sql, $flags ) ) {
1335  // Do not treat temporary table writes as "meaningful writes" since they are only
1336  // visible to one session and are not permanent. Profile them as reads. Integration
1337  // tests can override this behavior via $flags.
1338  $pseudoPermanent = $this->fieldHasBit( $flags, self::QUERY_PSEUDO_PERMANENT );
1339  $tempTableChanges = $this->getTempTableWrites( $sql, $pseudoPermanent );
1340  $isPermWrite = !$tempTableChanges;
1341  foreach ( $tempTableChanges as list( $tmpType ) ) {
1342  $isPermWrite = $isPermWrite || ( $tmpType !== self::TEMP_NORMAL );
1343  }
1344 
1345  // Permit temporary table writes on replica DB connections
1346  // but require a writable primary DB connection for any persistent writes.
1347  if ( $isPermWrite ) {
1348  $this->assertIsWritablePrimary();
1349 
1350  // DBConnRef uses QUERY_REPLICA_ROLE to enforce the replica role for raw SQL queries
1351  if ( $this->fieldHasBit( $flags, self::QUERY_REPLICA_ROLE ) ) {
1352  throw new DBReadOnlyRoleError( $this, "Cannot write; target role is DB_REPLICA" );
1353  }
1354  }
1355  } else {
1356  // No permanent writes in this query
1357  $isPermWrite = false;
1358  // No temporary tables written to either
1359  $tempTableChanges = [];
1360  }
1361 
1362  // Add trace comment to the begin of the sql string, right after the operator.
1363  // Or, for one-word queries (like "BEGIN" or COMMIT") add it to the end (T44598).
1364  // NOTE: Don't add varying ids such as request id or session id to the comment.
1365  // It would break aggregation of similar queries in analysis tools (see T193050#7512149)
1366  $encName = preg_replace( '/[\x00-\x1F\/]/', '-', "$fname {$this->agent}" );
1367  $commentedSql = preg_replace( '/\s|$/', " /* $encName */ ", $sql, 1 );
1368 
1369  $corruptedTrx = false;
1370 
1371  $cs = $this->commenceCriticalSection( __METHOD__ );
1372 
1373  // Send the query to the server and fetch any corresponding errors.
1374  // This also doubles as a "ping" to see if the connection was dropped.
1375  list( $ret, $err, $errno, $recoverableSR, $recoverableCL, $reconnected ) =
1376  $this->executeQueryAttempt( $sql, $commentedSql, $isPermWrite, $fname, $flags );
1377 
1378  // Check if the query failed due to a recoverable connection loss
1379  $allowRetry = !$this->fieldHasBit( $flags, self::QUERY_NO_RETRY );
1380  if ( $ret === false && $recoverableCL && $reconnected && $allowRetry ) {
1381  // Silently resend the query to the server since it is safe and possible
1382  list( $ret, $err, $errno, $recoverableSR, $recoverableCL ) =
1383  $this->executeQueryAttempt( $sql, $commentedSql, $isPermWrite, $fname, $flags );
1384  }
1385 
1386  // Register creation and dropping of temporary tables
1387  $this->registerTempWrites( $ret, $tempTableChanges );
1388 
1389  if ( $ret === false && $priorTransaction ) {
1390  if ( $recoverableSR ) {
1391  # We're ignoring an error that caused just the current query to be aborted.
1392  # But log the cause so we can log a deprecation notice if a caller actually
1393  # does ignore it.
1394  $this->trxStatusIgnoredCause = [ $err, $errno, $fname ];
1395  } elseif ( !$recoverableCL ) {
1396  # Either the query was aborted or all queries after BEGIN where aborted.
1397  # In the first case, the only options going forward are (a) ROLLBACK, or
1398  # (b) ROLLBACK TO SAVEPOINT (if one was set). If the later case, the only
1399  # option is ROLLBACK, since the snapshots would have been released.
1400  $corruptedTrx = true; // cannot recover
1401  $trxError = $this->getQueryException( $err, $errno, $sql, $fname );
1402  $this->setTransactionError( $trxError );
1403  }
1404  }
1405 
1406  $this->completeCriticalSection( __METHOD__, $cs );
1407 
1408  return [ $ret, $err, $errno, $corruptedTrx ];
1409  }
1410 
1429  private function executeQueryAttempt( $sql, $commentedSql, $isPermWrite, $fname, $flags ) {
1430  $priorWritesPending = $this->writesOrCallbacksPending();
1431 
1432  if ( ( $flags & self::QUERY_IGNORE_DBO_TRX ) == 0 ) {
1433  $this->beginIfImplied( $sql, $fname );
1434  }
1435 
1436  // Keep track of whether the transaction has write queries pending
1437  if ( $isPermWrite ) {
1438  $this->lastWriteTime = microtime( true );
1439  if ( $this->trxLevel() && !$this->trxDoneWrites ) {
1440  $this->trxDoneWrites = true;
1441  $this->trxProfiler->transactionWritingIn(
1442  $this->getServerName(),
1443  $this->getDomainID(),
1444  $this->trxId
1445  );
1446  }
1447  }
1448 
1449  $prefix = $this->topologyRole === IDatabase::ROLE_STREAMING_MASTER ? 'query-m: ' : 'query: ';
1450  $generalizedSql = new GeneralizedSql( $sql, $prefix );
1451 
1452  $startTime = microtime( true );
1453  $ps = $this->profiler
1454  ? ( $this->profiler )( $generalizedSql->stringify() )
1455  : null;
1456  $this->affectedRowCount = null;
1457  $this->lastQuery = $sql;
1458  $ret = $this->doQuery( $commentedSql );
1459  $lastError = $this->lastError();
1460  $lastErrno = $this->lastErrno();
1461 
1462  $this->affectedRowCount = $this->affectedRows();
1463  unset( $ps ); // profile out (if set)
1464  $queryRuntime = max( microtime( true ) - $startTime, 0.0 );
1465 
1466  $recoverableSR = false; // recoverable statement rollback?
1467  $recoverableCL = false; // recoverable connection loss?
1468  $reconnected = false; // reconnection both attempted and succeeded?
1469 
1470  if ( $ret !== false ) {
1471  $this->lastPing = $startTime;
1472  if ( $isPermWrite && $this->trxLevel() ) {
1473  $this->updateTrxWriteQueryTime( $sql, $queryRuntime, $this->affectedRows() );
1474  $this->trxWriteCallers[] = $fname;
1475  }
1476  } elseif ( $this->isConnectionError( $lastErrno ) ) {
1477  # Check if no meaningful session state was lost
1478  $recoverableCL = $this->canRecoverFromDisconnect( $sql, $priorWritesPending );
1479  # Update session state tracking and try to restore the connection
1480  $reconnected = $this->replaceLostConnection( __METHOD__ );
1481  } else {
1482  # Check if only the last query was rolled back
1483  $recoverableSR = $this->wasKnownStatementRollbackError();
1484  }
1485 
1486  if ( $sql === self::PING_QUERY ) {
1487  $this->lastRoundTripEstimate = $queryRuntime;
1488  }
1489 
1490  $numRows = 0;
1491  if ( $ret instanceof IResultWrapper ) {
1492  $numRows = $ret->numRows();
1493  }
1494 
1495  $this->trxProfiler->recordQueryCompletion(
1496  $generalizedSql,
1497  $startTime,
1498  $isPermWrite,
1499  $isPermWrite ? $this->affectedRows() : $numRows,
1500  $this->trxId,
1501  $this->getServerName()
1502  );
1503 
1504  // Avoid the overhead of logging calls unless debug mode is enabled
1505  if ( $this->getFlag( self::DBO_DEBUG ) ) {
1506  $this->queryLogger->debug(
1507  "{method} [{runtime}s] {db_server}: {sql}",
1508  $this->getLogContext( [
1509  'method' => $fname,
1510  'sql' => $sql,
1511  'domain' => $this->getDomainID(),
1512  'runtime' => round( $queryRuntime, 3 )
1513  ] )
1514  );
1515  }
1516 
1517  if ( !is_bool( $ret ) && $ret !== null && !( $ret instanceof IResultWrapper ) ) {
1518  throw new DBUnexpectedError( $this,
1519  static::class . '::doQuery() should return an IResultWrapper' );
1520  }
1521 
1522  return [ $ret, $lastError, $lastErrno, $recoverableSR, $recoverableCL, $reconnected ];
1523  }
1524 
1531  private function beginIfImplied( $sql, $fname ) {
1532  if (
1533  !$this->trxLevel() &&
1534  $this->getFlag( self::DBO_TRX ) &&
1535  $this->isTransactableQuery( $sql )
1536  ) {
1537  $this->begin( __METHOD__ . " ($fname)", self::TRANSACTION_INTERNAL );
1538  $this->trxAutomatic = true;
1539  }
1540  }
1541 
1554  private function updateTrxWriteQueryTime( $sql, $runtime, $affected ) {
1555  // Whether this is indicative of replica DB runtime (except for RBR or ws_repl)
1556  $indicativeOfReplicaRuntime = true;
1557  if ( $runtime > self::SLOW_WRITE_SEC ) {
1558  $verb = $this->getQueryVerb( $sql );
1559  // insert(), upsert(), replace() are fast unless bulky in size or blocked on locks
1560  if ( $verb === 'INSERT' ) {
1561  $indicativeOfReplicaRuntime = $this->affectedRows() > self::SMALL_WRITE_ROWS;
1562  } elseif ( $verb === 'REPLACE' ) {
1563  $indicativeOfReplicaRuntime = $this->affectedRows() > self::SMALL_WRITE_ROWS / 2;
1564  }
1565  }
1566 
1567  $this->trxWriteDuration += $runtime;
1568  $this->trxWriteQueryCount += 1;
1569  $this->trxWriteAffectedRows += $affected;
1570  if ( $indicativeOfReplicaRuntime ) {
1571  $this->trxWriteAdjDuration += $runtime;
1572  $this->trxWriteAdjQueryCount += 1;
1573  }
1574  }
1575 
1584  private function assertQueryIsCurrentlyAllowed( $sql, $fname ) {
1585  $verb = $this->getQueryVerb( $sql );
1586  if ( $verb === 'USE' ) {
1587  throw new DBUnexpectedError( $this, "Got USE query; use selectDomain() instead" );
1588  }
1589 
1590  if ( $verb === 'ROLLBACK' ) { // transaction/savepoint
1591  return;
1592  }
1593 
1594  if ( $this->csmError ) {
1595  throw new DBTransactionStateError(
1596  $this,
1597  "Cannot execute query from $fname while session state is out of sync.\n\n" .
1598  $this->csmError->getMessage() . "\n" .
1599  $this->csmError->getTraceAsString()
1600  );
1601  }
1602 
1603  if ( $this->trxStatus < self::STATUS_TRX_OK ) {
1604  throw new DBTransactionStateError(
1605  $this,
1606  "Cannot execute query from $fname while transaction status is ERROR",
1607  [],
1608  $this->trxStatusCause
1609  );
1610  } elseif ( $this->trxStatus === self::STATUS_TRX_OK && $this->trxStatusIgnoredCause ) {
1611  list( $iLastError, $iLastErrno, $iFname ) = $this->trxStatusIgnoredCause;
1612  call_user_func( $this->deprecationLogger,
1613  "Caller from $fname ignored an error originally raised from $iFname: " .
1614  "[$iLastErrno] $iLastError"
1615  );
1616  $this->trxStatusIgnoredCause = null;
1617  }
1618  }
1619 
1629  private function canRecoverFromDisconnect( $sql, $priorWritesPending ) {
1630  $blockers = [];
1631  if ( $this->sessionNamedLocks ) {
1632  // Named locks were automatically released, breaking the expectations
1633  // of callers relying on those locks for critical section enforcement
1634  $blockers[] = 'named locks';
1635  }
1636  if ( $this->sessionTempTables ) {
1637  // Temp tables were automatically dropped, breaking the expectations
1638  // of callers relying on those tables having been created/populated
1639  $blockers[] = 'temp tables';
1640  }
1641  if ( $priorWritesPending && $sql !== 'ROLLBACK' ) {
1642  // Transaction was automatically rolled back, breaking the expectations
1643  // of callers and DBO_TRX semantics relying on that transaction to provide
1644  // atomic writes (point-in-time snapshot loss is acceptable for DBO_TRX)
1645  $blockers[] = 'transaction writes';
1646  }
1647  if ( $this->explicitTrxActive() && $sql !== 'ROLLBACK' && $sql !== 'COMMIT' ) {
1648  // Transaction was automatically rolled back, breaking the expectations of
1649  // callers relying on that transaction to provide atomic writes, serializability,
1650  // or read results consistent with a single point-in-time snapshot. Disconnection
1651  // on ROLLBACK is not an issue, since the intended result of rolling back the
1652  // transaction was in fact achieved. Disconnection on COMMIT of an empty transaction
1653  // is also not an issue, for similar reasons (T127428).
1654  $blockers[] = 'explicit transaction';
1655  }
1656 
1657  if ( $blockers ) {
1658  $this->connLogger->warning(
1659  "Silent reconnection to {db_server} could not be attempted: {error}",
1660  $this->getLogContext( [
1661  'error' => 'session state loss (' . implode( ', ', $blockers ) . ')',
1662  'exception' => new RuntimeException()
1663  ] )
1664  );
1665 
1666  return false;
1667  }
1668 
1669  return true;
1670  }
1671 
1675  private function handleSessionLossPreconnect() {
1676  // Clean up tracking of session-level things...
1677  // https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html
1678  // https://www.postgresql.org/docs/9.2/static/sql-createtable.html (ignoring ON COMMIT)
1679  $this->sessionTempTables = [];
1680  $this->sessionDirtyTempTables = [];
1681  // https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_get-lock
1682  // https://www.postgresql.org/docs/9.4/static/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS
1683  $this->sessionNamedLocks = [];
1684  // Session loss implies transaction loss
1685  $oldTrxId = $this->consumeTrxId();
1686  $this->trxAtomicCounter = 0;
1687  $this->trxPostCommitOrIdleCallbacks = []; // T67263; transaction already lost
1688  $this->trxPreCommitOrIdleCallbacks = []; // T67263; transaction already lost
1689  // Clear additional subclass fields
1691  // @note: leave trxRecurringCallbacks in place
1692  if ( $this->trxDoneWrites ) {
1693  $this->trxProfiler->transactionWritingOut(
1694  $this->getServerName(),
1695  $this->getDomainID(),
1696  $oldTrxId,
1697  $this->pendingWriteQueryDuration( self::ESTIMATE_TOTAL ),
1698  $this->trxWriteAffectedRows
1699  );
1700  }
1701  }
1702 
1707  protected function doHandleSessionLossPreconnect() {
1708  // no-op
1709  }
1710 
1714  private function handleSessionLossPostconnect() {
1715  // Handle callbacks in trxEndCallbacks, e.g. onTransactionResolution().
1716  // If callback suppression is set then the array will remain unhandled.
1717  $this->runOnTransactionIdleCallbacks( self::TRIGGER_ROLLBACK );
1718  // Handle callbacks in trxRecurringCallbacks, e.g. setTransactionListener()
1719  $this->runTransactionListenerCallbacks( self::TRIGGER_ROLLBACK );
1720  }
1721 
1727  private function consumeTrxId() {
1728  $old = $this->trxId;
1729  $this->trxId = '';
1730 
1731  return $old;
1732  }
1733 
1745  protected function wasQueryTimeout( $error, $errno ) {
1746  return false;
1747  }
1748 
1760  public function reportQueryError( $error, $errno, $sql, $fname, $ignore = false ) {
1761  if ( $ignore ) {
1762  $this->queryLogger->debug( "SQL ERROR (ignored): $error" );
1763  } else {
1764  throw $this->getQueryExceptionAndLog( $error, $errno, $sql, $fname );
1765  }
1766  }
1767 
1775  private function getQueryExceptionAndLog( $error, $errno, $sql, $fname ) {
1776  // Information that instances of the same problem have in common should
1777  // not be normalized (T255202).
1778  $this->queryLogger->error(
1779  "Error $errno from $fname, {error} {sql1line} {db_server}",
1780  $this->getLogContext( [
1781  'method' => __METHOD__,
1782  'errno' => $errno,
1783  'error' => $error,
1784  'sql1line' => mb_substr( str_replace( "\n", "\\n", $sql ), 0, 5 * 1024 ),
1785  'fname' => $fname,
1786  'exception' => new RuntimeException()
1787  ] )
1788  );
1789  return $this->getQueryException( $error, $errno, $sql, $fname );
1790  }
1791 
1799  private function getQueryException( $error, $errno, $sql, $fname ) {
1800  if ( $this->wasQueryTimeout( $error, $errno ) ) {
1801  return new DBQueryTimeoutError( $this, $error, $errno, $sql, $fname );
1802  } elseif ( $this->isConnectionError( $errno ) ) {
1803  return new DBQueryDisconnectedError( $this, $error, $errno, $sql, $fname );
1804  } else {
1805  return new DBQueryError( $this, $error, $errno, $sql, $fname );
1806  }
1807  }
1808 
1813  final protected function newExceptionAfterConnectError( $error ) {
1814  // Connection was not fully initialized and is not safe for use
1815  $this->conn = null;
1816 
1817  $this->connLogger->error(
1818  "Error connecting to {db_server} as user {db_user}: {error}",
1819  $this->getLogContext( [
1820  'error' => $error,
1821  'exception' => new RuntimeException()
1822  ] )
1823  );
1824 
1825  return new DBConnectionError( $this, $error );
1826  }
1827 
1832  return new SelectQueryBuilder( $this );
1833  }
1834 
1835  public function selectField(
1836  $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
1837  ) {
1838  if ( $var === '*' ) {
1839  throw new DBUnexpectedError( $this, "Cannot use a * field" );
1840  } elseif ( is_array( $var ) && count( $var ) !== 1 ) {
1841  throw new DBUnexpectedError( $this, 'Cannot use more than one field' );
1842  }
1843 
1844  $options = $this->normalizeOptions( $options );
1845  $options['LIMIT'] = 1;
1846 
1847  $res = $this->select( $table, $var, $cond, $fname, $options, $join_conds );
1848  if ( $res === false ) {
1849  throw new DBUnexpectedError( $this, "Got false from select()" );
1850  }
1851 
1852  $row = $this->fetchRow( $res );
1853  if ( $row === false ) {
1854  return false;
1855  }
1856 
1857  return reset( $row );
1858  }
1859 
1860  public function selectFieldValues(
1861  $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
1862  ): array {
1863  if ( $var === '*' ) {
1864  throw new DBUnexpectedError( $this, "Cannot use a * field" );
1865  } elseif ( !is_string( $var ) ) {
1866  throw new DBUnexpectedError( $this, "Cannot use an array of fields" );
1867  }
1868 
1869  $options = $this->normalizeOptions( $options );
1870  $res = $this->select( $table, [ 'value' => $var ], $cond, $fname, $options, $join_conds );
1871  if ( $res === false ) {
1872  throw new DBUnexpectedError( $this, "Got false from select()" );
1873  }
1874 
1875  $values = [];
1876  foreach ( $res as $row ) {
1877  $values[] = $row->value;
1878  }
1879 
1880  return $values;
1881  }
1882 
1894  protected function makeSelectOptions( array $options ) {
1895  $preLimitTail = $postLimitTail = '';
1896  $startOpts = '';
1897 
1898  $noKeyOptions = [];
1899 
1900  foreach ( $options as $key => $option ) {
1901  if ( is_numeric( $key ) ) {
1902  $noKeyOptions[$option] = true;
1903  }
1904  }
1905 
1906  $preLimitTail .= $this->makeGroupByWithHaving( $options );
1907 
1908  $preLimitTail .= $this->makeOrderBy( $options );
1909 
1910  if ( isset( $noKeyOptions['FOR UPDATE'] ) ) {
1911  $postLimitTail .= ' FOR UPDATE';
1912  }
1913 
1914  if ( isset( $noKeyOptions['LOCK IN SHARE MODE'] ) ) {
1915  $postLimitTail .= ' LOCK IN SHARE MODE';
1916  }
1917 
1918  if ( isset( $noKeyOptions['DISTINCT'] ) || isset( $noKeyOptions['DISTINCTROW'] ) ) {
1919  $startOpts .= 'DISTINCT';
1920  }
1921 
1922  # Various MySQL extensions
1923  if ( isset( $noKeyOptions['STRAIGHT_JOIN'] ) ) {
1924  $startOpts .= ' /*! STRAIGHT_JOIN */';
1925  }
1926 
1927  if ( isset( $noKeyOptions['SQL_BIG_RESULT'] ) ) {
1928  $startOpts .= ' SQL_BIG_RESULT';
1929  }
1930 
1931  if ( isset( $noKeyOptions['SQL_BUFFER_RESULT'] ) ) {
1932  $startOpts .= ' SQL_BUFFER_RESULT';
1933  }
1934 
1935  if ( isset( $noKeyOptions['SQL_SMALL_RESULT'] ) ) {
1936  $startOpts .= ' SQL_SMALL_RESULT';
1937  }
1938 
1939  if ( isset( $noKeyOptions['SQL_CALC_FOUND_ROWS'] ) ) {
1940  $startOpts .= ' SQL_CALC_FOUND_ROWS';
1941  }
1942 
1943  if ( isset( $options['USE INDEX'] ) && is_string( $options['USE INDEX'] ) ) {
1944  $useIndex = $this->useIndexClause( $options['USE INDEX'] );
1945  } else {
1946  $useIndex = '';
1947  }
1948  if ( isset( $options['IGNORE INDEX'] ) && is_string( $options['IGNORE INDEX'] ) ) {
1949  $ignoreIndex = $this->ignoreIndexClause( $options['IGNORE INDEX'] );
1950  } else {
1951  $ignoreIndex = '';
1952  }
1953 
1954  return [ $startOpts, $useIndex, $preLimitTail, $postLimitTail, $ignoreIndex ];
1955  }
1956 
1965  protected function makeGroupByWithHaving( $options ) {
1966  $sql = '';
1967  if ( isset( $options['GROUP BY'] ) ) {
1968  $gb = is_array( $options['GROUP BY'] )
1969  ? implode( ',', $options['GROUP BY'] )
1970  : $options['GROUP BY'];
1971  $sql .= ' GROUP BY ' . $gb;
1972  }
1973  if ( isset( $options['HAVING'] ) ) {
1974  $having = is_array( $options['HAVING'] )
1975  ? $this->makeList( $options['HAVING'], self::LIST_AND )
1976  : $options['HAVING'];
1977  $sql .= ' HAVING ' . $having;
1978  }
1979 
1980  return $sql;
1981  }
1982 
1991  protected function makeOrderBy( $options ) {
1992  if ( isset( $options['ORDER BY'] ) ) {
1993  $ob = is_array( $options['ORDER BY'] )
1994  ? implode( ',', $options['ORDER BY'] )
1995  : $options['ORDER BY'];
1996 
1997  return ' ORDER BY ' . $ob;
1998  }
1999 
2000  return '';
2001  }
2002 
2003  public function select(
2004  $table, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
2005  ) {
2006  $sql = $this->selectSQLText( $table, $vars, $conds, $fname, $options, $join_conds );
2007 
2008  return $this->query( $sql, $fname, self::QUERY_CHANGE_NONE );
2009  }
2010 
2015  public function selectSQLText( $table, $vars, $conds = '', $fname = __METHOD__,
2016  $options = [], $join_conds = []
2017  ) {
2018  if ( is_array( $vars ) ) {
2019  $fields = implode( ',', $this->fieldNamesWithAlias( $vars ) );
2020  } else {
2021  $fields = $vars;
2022  }
2023 
2024  $options = (array)$options;
2025  $useIndexes = ( isset( $options['USE INDEX'] ) && is_array( $options['USE INDEX'] ) )
2026  ? $options['USE INDEX']
2027  : [];
2028  $ignoreIndexes = (
2029  isset( $options['IGNORE INDEX'] ) &&
2030  is_array( $options['IGNORE INDEX'] )
2031  )
2032  ? $options['IGNORE INDEX']
2033  : [];
2034 
2035  if (
2036  $this->selectOptionsIncludeLocking( $options ) &&
2037  $this->selectFieldsOrOptionsAggregate( $vars, $options )
2038  ) {
2039  // Some DB types (e.g. postgres) disallow FOR UPDATE with aggregate
2040  // functions. Discourage use of such queries to encourage compatibility.
2041  call_user_func(
2042  $this->deprecationLogger,
2043  __METHOD__ . ": aggregation used with a locking SELECT ($fname)"
2044  );
2045  }
2046 
2047  if ( is_array( $table ) ) {
2048  if ( count( $table ) === 0 ) {
2049  $from = '';
2050  } else {
2051  $from = ' FROM ' .
2053  $table, $useIndexes, $ignoreIndexes, $join_conds );
2054  }
2055  } elseif ( $table != '' ) {
2056  $from = ' FROM ' .
2058  [ $table ], $useIndexes, $ignoreIndexes, [] );
2059  } else {
2060  $from = '';
2061  }
2062 
2063  list( $startOpts, $useIndex, $preLimitTail, $postLimitTail, $ignoreIndex ) =
2064  $this->makeSelectOptions( $options );
2065 
2066  if ( is_array( $conds ) ) {
2067  $conds = $this->makeList( $conds, self::LIST_AND );
2068  }
2069 
2070  if ( $conds === null || $conds === false ) {
2071  $this->queryLogger->warning(
2072  __METHOD__
2073  . ' called from '
2074  . $fname
2075  . ' with incorrect parameters: $conds must be a string or an array'
2076  );
2077  $conds = '';
2078  }
2079 
2080  if ( $conds === '' || $conds === '*' ) {
2081  $sql = "SELECT $startOpts $fields $from $useIndex $ignoreIndex $preLimitTail";
2082  } elseif ( is_string( $conds ) ) {
2083  $sql = "SELECT $startOpts $fields $from $useIndex $ignoreIndex " .
2084  "WHERE $conds $preLimitTail";
2085  } else {
2086  throw new DBUnexpectedError( $this, __METHOD__ . ' called with incorrect parameters' );
2087  }
2088 
2089  if ( isset( $options['LIMIT'] ) ) {
2090  $sql = $this->limitResult( $sql, $options['LIMIT'],
2091  $options['OFFSET'] ?? false );
2092  }
2093  $sql = "$sql $postLimitTail";
2094 
2095  if ( isset( $options['EXPLAIN'] ) ) {
2096  $sql = 'EXPLAIN ' . $sql;
2097  }
2098 
2099  return $sql;
2100  }
2101 
2102  public function selectRow( $table, $vars, $conds, $fname = __METHOD__,
2103  $options = [], $join_conds = []
2104  ) {
2105  $options = (array)$options;
2106  $options['LIMIT'] = 1;
2107 
2108  $res = $this->select( $table, $vars, $conds, $fname, $options, $join_conds );
2109  if ( $res === false ) {
2110  throw new DBUnexpectedError( $this, "Got false from select()" );
2111  }
2112 
2113  if ( !$this->numRows( $res ) ) {
2114  return false;
2115  }
2116 
2117  return $res->fetchObject();
2118  }
2119 
2124  public function estimateRowCount(
2125  $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
2126  ) {
2127  $conds = $this->normalizeConditions( $conds, $fname );
2128  $column = $this->extractSingleFieldFromList( $var );
2129  if ( is_string( $column ) && !in_array( $column, [ '*', '1' ] ) ) {
2130  $conds[] = "$column IS NOT NULL";
2131  }
2132 
2133  $res = $this->select(
2134  $tables, [ 'rowcount' => 'COUNT(*)' ], $conds, $fname, $options, $join_conds
2135  );
2136  $row = $res ? $this->fetchRow( $res ) : [];
2137 
2138  return isset( $row['rowcount'] ) ? (int)$row['rowcount'] : 0;
2139  }
2140 
2141  public function selectRowCount(
2142  $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
2143  ) {
2144  $conds = $this->normalizeConditions( $conds, $fname );
2145  $column = $this->extractSingleFieldFromList( $var );
2146  if ( is_string( $column ) && !in_array( $column, [ '*', '1' ] ) ) {
2147  $conds[] = "$column IS NOT NULL";
2148  }
2149 
2150  $res = $this->select(
2151  [
2152  'tmp_count' => $this->buildSelectSubquery(
2153  $tables,
2154  '1',
2155  $conds,
2156  $fname,
2157  $options,
2158  $join_conds
2159  )
2160  ],
2161  [ 'rowcount' => 'COUNT(*)' ],
2162  [],
2163  $fname
2164  );
2165  $row = $res ? $this->fetchRow( $res ) : [];
2166 
2167  return isset( $row['rowcount'] ) ? (int)$row['rowcount'] : 0;
2168  }
2169 
2174  private function selectOptionsIncludeLocking( $options ) {
2175  $options = (array)$options;
2176  foreach ( [ 'FOR UPDATE', 'LOCK IN SHARE MODE' ] as $lock ) {
2177  if ( in_array( $lock, $options, true ) ) {
2178  return true;
2179  }
2180  }
2181 
2182  return false;
2183  }
2184 
2190  private function selectFieldsOrOptionsAggregate( $fields, $options ) {
2191  foreach ( (array)$options as $key => $value ) {
2192  if ( is_string( $key ) ) {
2193  if ( preg_match( '/^(?:GROUP BY|HAVING)$/i', $key ) ) {
2194  return true;
2195  }
2196  } elseif ( is_string( $value ) ) {
2197  if ( preg_match( '/^(?:DISTINCT|DISTINCTROW)$/i', $value ) ) {
2198  return true;
2199  }
2200  }
2201  }
2202 
2203  $regex = '/^(?:COUNT|MIN|MAX|SUM|GROUP_CONCAT|LISTAGG|ARRAY_AGG)\s*\\(/i';
2204  foreach ( (array)$fields as $field ) {
2205  if ( is_string( $field ) && preg_match( $regex, $field ) ) {
2206  return true;
2207  }
2208  }
2209 
2210  return false;
2211  }
2212 
2218  final protected function normalizeRowArray( array $rowOrRows ) {
2219  if ( !$rowOrRows ) {
2220  $rows = [];
2221  } elseif ( isset( $rowOrRows[0] ) ) {
2222  $rows = $rowOrRows;
2223  } else {
2224  $rows = [ $rowOrRows ];
2225  }
2226 
2227  foreach ( $rows as $row ) {
2228  if ( !is_array( $row ) ) {
2229  throw new DBUnexpectedError( $this, "Got non-array in row array" );
2230  } elseif ( !$row ) {
2231  throw new DBUnexpectedError( $this, "Got empty array in row array" );
2232  }
2233  }
2234 
2235  return $rows;
2236  }
2237 
2244  final protected function normalizeConditions( $conds, $fname ) {
2245  if ( $conds === null || $conds === false ) {
2246  $this->queryLogger->warning(
2247  __METHOD__
2248  . ' called from '
2249  . $fname
2250  . ' with incorrect parameters: $conds must be a string or an array'
2251  );
2252  return [];
2253  } elseif ( $conds === '' ) {
2254  return [];
2255  }
2256 
2257  return is_array( $conds ) ? $conds : [ $conds ];
2258  }
2259 
2269  final protected function normalizeUpsertParams( $uniqueKeys, &$rows ) {
2270  $rows = $this->normalizeRowArray( $rows );
2271  if ( !$rows ) {
2272  return null;
2273  }
2274  if ( !$uniqueKeys ) {
2275  // For backwards compatibility, allow insertion of rows with no applicable key
2276  $this->queryLogger->warning(
2277  "upsert/replace called with no unique key",
2278  [ 'exception' => new RuntimeException() ]
2279  );
2280  return null;
2281  }
2282  $identityKey = $this->normalizeUpsertKeys( $uniqueKeys );
2283  if ( $identityKey ) {
2284  $allDefaultKeyValues = $this->assertValidUpsertRowArray( $rows, $identityKey );
2285  if ( $allDefaultKeyValues ) {
2286  // For backwards compatibility, allow insertion of rows with all-NULL
2287  // values for the unique columns (e.g. for an AUTOINCREMENT column)
2288  $this->queryLogger->warning(
2289  "upsert/replace called with all-null values for unique key",
2290  [ 'exception' => new RuntimeException() ]
2291  );
2292  return null;
2293  }
2294  }
2295  return $identityKey;
2296  }
2297 
2304  private function normalizeUpsertKeys( $uniqueKeys ) {
2305  if ( is_string( $uniqueKeys ) ) {
2306  return [ $uniqueKeys ];
2307  } elseif ( !is_array( $uniqueKeys ) ) {
2308  throw new DBUnexpectedError( $this, 'Invalid unique key array' );
2309  } else {
2310  if ( count( $uniqueKeys ) !== 1 || !isset( $uniqueKeys[0] ) ) {
2311  throw new DBUnexpectedError( $this,
2312  "The unique key array should contain a single unique index" );
2313  }
2314 
2315  $uniqueKey = $uniqueKeys[0];
2316  if ( is_string( $uniqueKey ) ) {
2317  // Passing a list of strings for single-column unique keys is too
2318  // easily confused with passing the columns of composite unique key
2319  $this->queryLogger->warning( __METHOD__ .
2320  " called with deprecated parameter style: " .
2321  "the unique key array should be a string or array of string arrays",
2322  [ 'exception' => new RuntimeException() ] );
2323  return $uniqueKeys;
2324  } elseif ( is_array( $uniqueKey ) ) {
2325  return $uniqueKey;
2326  } else {
2327  throw new DBUnexpectedError( $this, 'Invalid unique key array entry' );
2328  }
2329  }
2330  }
2331 
2337  final protected function normalizeOptions( $options ) {
2338  if ( is_array( $options ) ) {
2339  return $options;
2340  } elseif ( is_string( $options ) ) {
2341  return ( $options === '' ) ? [] : [ $options ];
2342  } else {
2343  throw new DBUnexpectedError( $this, __METHOD__ . ': expected string or array' );
2344  }
2345  }
2346 
2353  final protected function assertValidUpsertRowArray( array $rows, array $identityKey ) {
2354  $numNulls = 0;
2355  foreach ( $rows as $row ) {
2356  foreach ( $identityKey as $column ) {
2357  $numNulls += ( isset( $row[$column] ) ? 0 : 1 );
2358  }
2359  }
2360 
2361  if (
2362  $numNulls &&
2363  $numNulls !== ( count( $rows ) * count( $identityKey ) )
2364  ) {
2365  throw new DBUnexpectedError(
2366  $this,
2367  "NULL/absent values for unique key (" . implode( ',', $identityKey ) . ")"
2368  );
2369  }
2370 
2371  return (bool)$numNulls;
2372  }
2373 
2380  final protected function assertValidUpsertSetArray(
2381  array $set,
2382  array $identityKey,
2383  array $rows
2384  ) {
2385  // Sloppy callers might construct the SET array using the ROW array, leaving redundant
2386  // column definitions for identity key columns. Detect this for backwards compatibility.
2387  $soleRow = ( count( $rows ) == 1 ) ? reset( $rows ) : null;
2388  // Disallow value changes for any columns in the identity key. This avoids additional
2389  // insertion order dependencies that are unwieldy and difficult to implement efficiently
2390  // in PostgreSQL.
2391  foreach ( $set as $k => $v ) {
2392  if ( is_string( $k ) ) {
2393  // Key is a column name and value is a literal (e.g. string, int, null, ...)
2394  if ( in_array( $k, $identityKey, true ) ) {
2395  if ( $soleRow && array_key_exists( $k, $soleRow ) && $soleRow[$k] === $v ) {
2396  $this->queryLogger->warning(
2397  __METHOD__ . " called with redundant assignment to column '$k'",
2398  [ 'exception' => new RuntimeException() ]
2399  );
2400  } else {
2401  throw new DBUnexpectedError(
2402  $this,
2403  "Cannot reassign column '$k' since it belongs to identity key"
2404  );
2405  }
2406  }
2407  } elseif ( preg_match( '/^([a-zA-Z0-9_]+)\s*=/', $v, $m ) ) {
2408  // Value is of the form "<unquoted alphanumeric column> = <SQL expression>"
2409  if ( in_array( $m[1], $identityKey, true ) ) {
2410  throw new DBUnexpectedError(
2411  $this,
2412  "Cannot reassign column '{$m[1]}' since it belongs to identity key"
2413  );
2414  }
2415  }
2416  }
2417  }
2418 
2425  final protected function isFlagInOptions( $option, array $options ) {
2426  foreach ( array_keys( $options, $option, true ) as $k ) {
2427  if ( is_int( $k ) ) {
2428  return true;
2429  }
2430  }
2431 
2432  return false;
2433  }
2434 
2439  final protected function extractSingleFieldFromList( $var ) {
2440  if ( is_array( $var ) ) {
2441  if ( !$var ) {
2442  $column = null;
2443  } elseif ( count( $var ) == 1 ) {
2444  $column = $var[0] ?? reset( $var );
2445  } else {
2446  throw new DBUnexpectedError( $this, __METHOD__ . ': got multiple columns' );
2447  }
2448  } else {
2449  $column = $var;
2450  }
2451 
2452  return $column;
2453  }
2454 
2455  public function lockForUpdate(
2456  $table, $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
2457  ) {
2458  if ( !$this->trxLevel() && !$this->getFlag( self::DBO_TRX ) ) {
2459  throw new DBUnexpectedError(
2460  $this,
2461  __METHOD__ . ': no transaction is active nor is DBO_TRX set'
2462  );
2463  }
2464 
2465  $options = (array)$options;
2466  $options[] = 'FOR UPDATE';
2467 
2468  return $this->selectRowCount( $table, '*', $conds, $fname, $options, $join_conds );
2469  }
2470 
2471  public function fieldExists( $table, $field, $fname = __METHOD__ ) {
2472  $info = $this->fieldInfo( $table, $field );
2473 
2474  return (bool)$info;
2475  }
2476 
2477  public function indexExists( $table, $index, $fname = __METHOD__ ) {
2478  if ( !$this->tableExists( $table, $fname ) ) {
2479  return null;
2480  }
2481 
2482  $info = $this->indexInfo( $table, $index, $fname );
2483  if ( $info === null ) {
2484  return null;
2485  } else {
2486  return $info !== false;
2487  }
2488  }
2489 
2490  abstract public function tableExists( $table, $fname = __METHOD__ );
2491 
2496  public function indexUnique( $table, $index, $fname = __METHOD__ ) {
2497  $indexInfo = $this->indexInfo( $table, $index, $fname );
2498 
2499  if ( !$indexInfo ) {
2500  return null;
2501  }
2502 
2503  return !$indexInfo[0]->Non_unique;
2504  }
2505 
2506  public function insert( $table, $rows, $fname = __METHOD__, $options = [] ) {
2507  $rows = $this->normalizeRowArray( $rows );
2508  if ( !$rows ) {
2509  return true;
2510  }
2511 
2512  $options = $this->normalizeOptions( $options );
2513  if ( $this->isFlagInOptions( 'IGNORE', $options ) ) {
2514  $this->doInsertNonConflicting( $table, $rows, $fname );
2515  } else {
2516  $this->doInsert( $table, $rows, $fname );
2517  }
2518 
2519  return true;
2520  }
2521 
2530  protected function doInsert( $table, array $rows, $fname ) {
2531  $encTable = $this->tableName( $table );
2532  list( $sqlColumns, $sqlTuples ) = $this->makeInsertLists( $rows );
2533 
2534  $sql = "INSERT INTO $encTable ($sqlColumns) VALUES $sqlTuples";
2535 
2536  $this->query( $sql, $fname, self::QUERY_CHANGE_ROWS );
2537  }
2538 
2547  protected function doInsertNonConflicting( $table, array $rows, $fname ) {
2548  $encTable = $this->tableName( $table );
2549  list( $sqlColumns, $sqlTuples ) = $this->makeInsertLists( $rows );
2550  list( $sqlVerb, $sqlOpts ) = $this->makeInsertNonConflictingVerbAndOptions();
2551 
2552  $sql = rtrim( "$sqlVerb $encTable ($sqlColumns) VALUES $sqlTuples $sqlOpts" );
2553 
2554  $this->query( $sql, $fname, self::QUERY_CHANGE_ROWS );
2555  }
2556 
2563  return [ 'INSERT IGNORE INTO', '' ];
2564  }
2565 
2576  protected function makeInsertLists( array $rows ) {
2577  $firstRow = $rows[0];
2578  if ( !is_array( $firstRow ) || !$firstRow ) {
2579  throw new DBUnexpectedError( $this, 'Got an empty row list or empty row' );
2580  }
2581  // List of columns that define the value tuple ordering
2582  $tupleColumns = array_keys( $firstRow );
2583 
2584  $valueTuples = [];
2585  foreach ( $rows as $row ) {
2586  $rowColumns = array_keys( $row );
2587  // VALUES(...) requires a uniform correspondence of (column => value)
2588  if ( $rowColumns !== $tupleColumns ) {
2589  throw new DBUnexpectedError(
2590  $this,
2591  'Got row columns (' . implode( ', ', $rowColumns ) . ') ' .
2592  'instead of expected (' . implode( ', ', $tupleColumns ) . ')'
2593  );
2594  }
2595  // Make the value tuple that defines this row
2596  $valueTuples[] = '(' . $this->makeList( $row, self::LIST_COMMA ) . ')';
2597  }
2598 
2599  return [
2600  $this->makeList( $tupleColumns, self::LIST_NAMES ),
2601  implode( ',', $valueTuples )
2602  ];
2603  }
2604 
2612  protected function makeUpdateOptionsArray( $options ) {
2613  $options = $this->normalizeOptions( $options );
2614 
2615  $opts = [];
2616 
2617  if ( in_array( 'IGNORE', $options ) ) {
2618  $opts[] = 'IGNORE';
2619  }
2620 
2621  return $opts;
2622  }
2623 
2631  protected function makeUpdateOptions( $options ) {
2632  $opts = $this->makeUpdateOptionsArray( $options );
2633 
2634  return implode( ' ', $opts );
2635  }
2636 
2637  public function update( $table, $set, $conds, $fname = __METHOD__, $options = [] ) {
2638  $this->assertConditionIsNotEmpty( $conds, __METHOD__, true );
2639  $table = $this->tableName( $table );
2640  $opts = $this->makeUpdateOptions( $options );
2641  $sql = "UPDATE $opts $table SET " . $this->makeList( $set, self::LIST_SET );
2642 
2643  if ( $conds && $conds !== IDatabase::ALL_ROWS ) {
2644  if ( is_array( $conds ) ) {
2645  $conds = $this->makeList( $conds, self::LIST_AND );
2646  }
2647  $sql .= ' WHERE ' . $conds;
2648  }
2649 
2650  $this->query( $sql, $fname, self::QUERY_CHANGE_ROWS );
2651 
2652  return true;
2653  }
2654 
2655  public function makeList( array $a, $mode = self::LIST_COMMA ) {
2656  $first = true;
2657  $list = '';
2658 
2659  foreach ( $a as $field => $value ) {
2660  if ( $first ) {
2661  $first = false;
2662  } else {
2663  if ( $mode == self::LIST_AND ) {
2664  $list .= ' AND ';
2665  } elseif ( $mode == self::LIST_OR ) {
2666  $list .= ' OR ';
2667  } else {
2668  $list .= ',';
2669  }
2670  }
2671 
2672  if ( ( $mode == self::LIST_AND || $mode == self::LIST_OR ) && is_numeric( $field ) ) {
2673  $list .= "($value)";
2674  } elseif ( $mode == self::LIST_SET && is_numeric( $field ) ) {
2675  $list .= "$value";
2676  } elseif (
2677  ( $mode == self::LIST_AND || $mode == self::LIST_OR ) && is_array( $value )
2678  ) {
2679  // Remove null from array to be handled separately if found
2680  $includeNull = false;
2681  foreach ( array_keys( $value, null, true ) as $nullKey ) {
2682  $includeNull = true;
2683  unset( $value[$nullKey] );
2684  }
2685  if ( count( $value ) == 0 && !$includeNull ) {
2686  throw new InvalidArgumentException(
2687  __METHOD__ . ": empty input for field $field" );
2688  } elseif ( count( $value ) == 0 ) {
2689  // only check if $field is null
2690  $list .= "$field IS NULL";
2691  } else {
2692  // IN clause contains at least one valid element
2693  if ( $includeNull ) {
2694  // Group subconditions to ensure correct precedence
2695  $list .= '(';
2696  }
2697  if ( count( $value ) == 1 ) {
2698  // Special-case single values, as IN isn't terribly efficient
2699  // Don't necessarily assume the single key is 0; we don't
2700  // enforce linear numeric ordering on other arrays here.
2701  $value = array_values( $value )[0];
2702  $list .= $field . " = " . $this->addQuotes( $value );
2703  } else {
2704  $list .= $field . " IN (" . $this->makeList( $value ) . ") ";
2705  }
2706  // if null present in array, append IS NULL
2707  if ( $includeNull ) {
2708  $list .= " OR $field IS NULL)";
2709  }
2710  }
2711  } elseif ( $value === null ) {
2712  if ( $mode == self::LIST_AND || $mode == self::LIST_OR ) {
2713  $list .= "$field IS ";
2714  } elseif ( $mode == self::LIST_SET ) {
2715  $list .= "$field = ";
2716  }
2717  $list .= 'NULL';
2718  } else {
2719  if (
2720  $mode == self::LIST_AND || $mode == self::LIST_OR || $mode == self::LIST_SET
2721  ) {
2722  $list .= "$field = ";
2723  }
2724  $list .= $mode == self::LIST_NAMES ? $value : $this->addQuotes( $value );
2725  }
2726  }
2727 
2728  return $list;
2729  }
2730 
2731  public function makeWhereFrom2d( $data, $baseKey, $subKey ) {
2732  $conds = [];
2733 
2734  foreach ( $data as $base => $sub ) {
2735  if ( count( $sub ) ) {
2736  $conds[] = $this->makeList(
2737  [ $baseKey => $base, $subKey => array_map( 'strval', array_keys( $sub ) ) ],
2739  );
2740  }
2741  }
2742 
2743  if ( $conds ) {
2744  return $this->makeList( $conds, self::LIST_OR );
2745  } else {
2746  // Nothing to search for...
2747  return false;
2748  }
2749  }
2750 
2751  public function factorConds( $condsArray ) {
2752  if ( count( $condsArray ) === 0 ) {
2753  throw new InvalidArgumentException(
2754  __METHOD__ . ": empty condition array" );
2755  }
2756  $condsByFieldSet = [];
2757  foreach ( $condsArray as $conds ) {
2758  if ( !count( $conds ) ) {
2759  throw new InvalidArgumentException(
2760  __METHOD__ . ": empty condition subarray" );
2761  }
2762  $fieldKey = implode( ',', array_keys( $conds ) );
2763  $condsByFieldSet[$fieldKey][] = $conds;
2764  }
2765  $result = '';
2766  foreach ( $condsByFieldSet as $conds ) {
2767  if ( $result !== '' ) {
2768  $result .= ' OR ';
2769  }
2770  $result .= $this->factorCondsWithCommonFields( $conds );
2771  }
2772  return $result;
2773  }
2774 
2782  private function factorCondsWithCommonFields( $condsArray ) {
2783  $first = $condsArray[array_key_first( $condsArray )];
2784  if ( count( $first ) === 1 ) {
2785  // IN clause
2786  $field = array_key_first( $first );
2787  $values = [];
2788  foreach ( $condsArray as $conds ) {
2789  $values[] = $conds[$field];
2790  }
2791  return $this->makeList( [ $field => $values ], self::LIST_AND );
2792  }
2793 
2794  $field1 = array_key_first( $first );
2795  $nullExpressions = [];
2796  $expressionsByField1 = [];
2797  foreach ( $condsArray as $conds ) {
2798  $value1 = $conds[$field1];
2799  unset( $conds[$field1] );
2800  if ( $value1 === null ) {
2801  $nullExpressions[] = $conds;
2802  } else {
2803  $expressionsByField1[$value1][] = $conds;
2804  }
2805 
2806  }
2807  $wrap = false;
2808  $result = '';
2809  foreach ( $expressionsByField1 as $value1 => $expressions ) {
2810  if ( $result !== '' ) {
2811  $result .= ' OR ';
2812  $wrap = true;
2813  }
2814  $factored = $this->factorCondsWithCommonFields( $expressions );
2815  $result .= "($field1 = " . $this->addQuotes( $value1 ) .
2816  " AND $factored)";
2817  }
2818  if ( count( $nullExpressions ) ) {
2819  $factored = $this->factorCondsWithCommonFields( $nullExpressions );
2820  if ( $result !== '' ) {
2821  $result .= ' OR ';
2822  $wrap = true;
2823  }
2824  $result .= "($field1 IS NULL AND $factored)";
2825  }
2826  if ( $wrap ) {
2827  return "($result)";
2828  } else {
2829  return $result;
2830  }
2831  }
2832 
2837  public function bitNot( $field ) {
2838  return "(~$field)";
2839  }
2840 
2845  public function bitAnd( $fieldLeft, $fieldRight ) {
2846  return "($fieldLeft & $fieldRight)";
2847  }
2848 
2853  public function bitOr( $fieldLeft, $fieldRight ) {
2854  return "($fieldLeft | $fieldRight)";
2855  }
2856 
2861  public function buildConcat( $stringList ) {
2862  return 'CONCAT(' . implode( ',', $stringList ) . ')';
2863  }
2864 
2869  public function buildGroupConcatField(
2870  $delim, $table, $field, $conds = '', $join_conds = []
2871  ) {
2872  $fld = "GROUP_CONCAT($field SEPARATOR " . $this->addQuotes( $delim ) . ')';
2873 
2874  return '(' . $this->selectSQLText( $table, $fld, $conds, null, [], $join_conds ) . ')';
2875  }
2876 
2881  public function buildGreatest( $fields, $values ) {
2882  return $this->buildSuperlative( 'GREATEST', $fields, $values );
2883  }
2884 
2889  public function buildLeast( $fields, $values ) {
2890  return $this->buildSuperlative( 'LEAST', $fields, $values );
2891  }
2892 
2909  protected function buildSuperlative( $sqlfunc, $fields, $values ) {
2910  $fields = is_array( $fields ) ? $fields : [ $fields ];
2911  $values = is_array( $values ) ? $values : [ $values ];
2912 
2913  $encValues = [];
2914  foreach ( $fields as $alias => $field ) {
2915  if ( is_int( $alias ) ) {
2916  $encValues[] = $this->addIdentifierQuotes( $field );
2917  } else {
2918  $encValues[] = $field; // expression
2919  }
2920  }
2921  foreach ( $values as $value ) {
2922  if ( is_int( $value ) || is_float( $value ) ) {
2923  $encValues[] = $value;
2924  } elseif ( is_string( $value ) ) {
2925  $encValues[] = $this->addQuotes( $value );
2926  } elseif ( $value === null ) {
2927  throw new DBUnexpectedError( $this, 'Null value in superlative' );
2928  } else {
2929  throw new DBUnexpectedError( $this, 'Unexpected value type in superlative' );
2930  }
2931  }
2932 
2933  return $sqlfunc . '(' . implode( ',', $encValues ) . ')';
2934  }
2935 
2940  public function buildSubstring( $input, $startPosition, $length = null ) {
2941  $this->assertBuildSubstringParams( $startPosition, $length );
2942  $functionBody = "$input FROM $startPosition";
2943  if ( $length !== null ) {
2944  $functionBody .= " FOR $length";
2945  }
2946  return 'SUBSTRING(' . $functionBody . ')';
2947  }
2948 
2961  protected function assertBuildSubstringParams( $startPosition, $length ) {
2962  if ( $startPosition === 0 ) {
2963  // The DBMSs we support use 1-based indexing here.
2964  throw new InvalidArgumentException( 'Use 1 as $startPosition for the beginning of the string' );
2965  }
2966  if ( !is_int( $startPosition ) || $startPosition < 0 ) {
2967  throw new InvalidArgumentException(
2968  '$startPosition must be a positive integer'
2969  );
2970  }
2971  if ( !( is_int( $length ) && $length >= 0 || $length === null ) ) {
2972  throw new InvalidArgumentException(
2973  '$length must be null or an integer greater than or equal to 0'
2974  );
2975  }
2976  }
2977 
2991  protected function assertConditionIsNotEmpty( $conds, string $fname, bool $deprecate ) {
2992  $isCondValid = ( is_string( $conds ) || is_array( $conds ) ) && $conds;
2993  if ( !$isCondValid ) {
2994  if ( $deprecate ) {
2995  wfDeprecated( $fname . ' called with empty $conds', '1.35', false, 3 );
2996  } else {
2997  throw new DBUnexpectedError( $this, $fname . ' called with empty conditions' );
2998  }
2999  }
3000  }
3001 
3006  public function buildStringCast( $field ) {
3007  // In theory this should work for any standards-compliant
3008  // SQL implementation, although it may not be the best way to do it.
3009  return "CAST( $field AS CHARACTER )";
3010  }
3011 
3016  public function buildIntegerCast( $field ) {
3017  return 'CAST( ' . $field . ' AS INTEGER )';
3018  }
3019 
3020  public function buildSelectSubquery(
3021  $table, $vars, $conds = '', $fname = __METHOD__,
3022  $options = [], $join_conds = []
3023  ) {
3024  return new Subquery(
3025  $this->selectSQLText( $table, $vars, $conds, $fname, $options, $join_conds )
3026  );
3027  }
3028 
3033  public function databasesAreIndependent() {
3034  return false;
3035  }
3036 
3037  final public function selectDB( $db ) {
3038  $this->selectDomain( new DatabaseDomain(
3039  $db,
3040  $this->currentDomain->getSchema(),
3041  $this->currentDomain->getTablePrefix()
3042  ) );
3043 
3044  return true;
3045  }
3046 
3047  final public function selectDomain( $domain ) {
3048  $cs = $this->commenceCriticalSection( __METHOD__ );
3049 
3050  try {
3051  $this->doSelectDomain( DatabaseDomain::newFromId( $domain ) );
3052  } catch ( DBError $e ) {
3053  $this->completeCriticalSection( __METHOD__, $cs );
3054  throw $e;
3055  }
3056 
3057  $this->completeCriticalSection( __METHOD__, $cs );
3058  }
3059 
3067  protected function doSelectDomain( DatabaseDomain $domain ) {
3068  $this->currentDomain = $domain;
3069  }
3070 
3071  public function getDBname() {
3072  return $this->currentDomain->getDatabase();
3073  }
3074 
3075  public function getServer() {
3076  return $this->connectionParams[self::CONN_HOST] ?? null;
3077  }
3078 
3079  public function getServerName() {
3080  return $this->serverName ?? $this->getServer();
3081  }
3082 
3087  public function tableName( $name, $format = 'quoted' ) {
3088  if ( $name instanceof Subquery ) {
3089  throw new DBUnexpectedError(
3090  $this,
3091  __METHOD__ . ': got Subquery instance when expecting a string'
3092  );
3093  }
3094 
3095  # Skip the entire process when we have a string quoted on both ends.
3096  # Note that we check the end so that we will still quote any use of
3097  # use of `database`.table. But won't break things if someone wants
3098  # to query a database table with a dot in the name.
3099  if ( $this->isQuotedIdentifier( $name ) ) {
3100  return $name;
3101  }
3102 
3103  # Lets test for any bits of text that should never show up in a table
3104  # name. Basically anything like JOIN or ON which are actually part of
3105  # SQL queries, but may end up inside of the table value to combine
3106  # sql. Such as how the API is doing.
3107  # Note that we use a whitespace test rather than a \b test to avoid
3108  # any remote case where a word like on may be inside of a table name
3109  # surrounded by symbols which may be considered word breaks.
3110  if ( preg_match( '/(^|\s)(DISTINCT|JOIN|ON|AS)(\s|$)/i', $name ) !== 0 ) {
3111  $this->queryLogger->warning(
3112  __METHOD__ . ": use of subqueries is not supported this way",
3113  [ 'exception' => new RuntimeException() ]
3114  );
3115 
3116  return $name;
3117  }
3118 
3119  # Split database and table into proper variables.
3120  list( $database, $schema, $prefix, $table ) = $this->qualifiedTableComponents( $name );
3121 
3122  # Quote $table and apply the prefix if not quoted.
3123  # $tableName might be empty if this is called from Database::replaceVars()
3124  $tableName = "{$prefix}{$table}";
3125  if ( $format === 'quoted'
3126  && !$this->isQuotedIdentifier( $tableName )
3127  && $tableName !== ''
3128  ) {
3129  $tableName = $this->addIdentifierQuotes( $tableName );
3130  }
3131 
3132  # Quote $schema and $database and merge them with the table name if needed
3133  $tableName = $this->prependDatabaseOrSchema( $schema, $tableName, $format );
3134  $tableName = $this->prependDatabaseOrSchema( $database, $tableName, $format );
3135 
3136  return $tableName;
3137  }
3138 
3145  protected function qualifiedTableComponents( $name ) {
3146  # We reverse the explode so that database.table and table both output the correct table.
3147  $dbDetails = explode( '.', $name, 3 );
3148  if ( count( $dbDetails ) == 3 ) {
3149  list( $database, $schema, $table ) = $dbDetails;
3150  # We don't want any prefix added in this case
3151  $prefix = '';
3152  } elseif ( count( $dbDetails ) == 2 ) {
3153  list( $database, $table ) = $dbDetails;
3154  # We don't want any prefix added in this case
3155  $prefix = '';
3156  # In dbs that support it, $database may actually be the schema
3157  # but that doesn't affect any of the functionality here
3158  $schema = '';
3159  } else {
3160  list( $table ) = $dbDetails;
3161  if ( isset( $this->tableAliases[$table] ) ) {
3162  $database = $this->tableAliases[$table]['dbname'];
3163  $schema = is_string( $this->tableAliases[$table]['schema'] )
3164  ? $this->tableAliases[$table]['schema']
3165  : $this->relationSchemaQualifier();
3166  $prefix = is_string( $this->tableAliases[$table]['prefix'] )
3167  ? $this->tableAliases[$table]['prefix']
3168  : $this->tablePrefix();
3169  } else {
3170  $database = '';
3171  $schema = $this->relationSchemaQualifier(); # Default schema
3172  $prefix = $this->tablePrefix(); # Default prefix
3173  }
3174  }
3175 
3176  return [ $database, $schema, $prefix, $table ];
3177  }
3178 
3185  private function prependDatabaseOrSchema( $namespace, $relation, $format ) {
3186  if ( $namespace !== null && $namespace !== '' ) {
3187  if ( $format === 'quoted' && !$this->isQuotedIdentifier( $namespace ) ) {
3188  $namespace = $this->addIdentifierQuotes( $namespace );
3189  }
3190  $relation = $namespace . '.' . $relation;
3191  }
3192 
3193  return $relation;
3194  }
3195 
3196  public function tableNames( ...$tables ) {
3197  $retVal = [];
3198 
3199  foreach ( $tables as $name ) {
3200  $retVal[$name] = $this->tableName( $name );
3201  }
3202 
3203  return $retVal;
3204  }
3205 
3206  public function tableNamesN( ...$tables ) {
3207  $retVal = [];
3208 
3209  foreach ( $tables as $name ) {
3210  $retVal[] = $this->tableName( $name );
3211  }
3212 
3213  return $retVal;
3214  }
3215 
3227  protected function tableNameWithAlias( $table, $alias = false ) {
3228  if ( is_string( $table ) ) {
3229  $quotedTable = $this->tableName( $table );
3230  } elseif ( $table instanceof Subquery ) {
3231  $quotedTable = (string)$table;
3232  } else {
3233  throw new InvalidArgumentException( "Table must be a string or Subquery" );
3234  }
3235 
3236  if ( $alias === false || $alias === $table ) {
3237  if ( $table instanceof Subquery ) {
3238  throw new InvalidArgumentException( "Subquery table missing alias" );
3239  }
3240 
3241  return $quotedTable;
3242  } else {
3243  return $quotedTable . ' ' . $this->addIdentifierQuotes( $alias );
3244  }
3245  }
3246 
3256  protected function fieldNameWithAlias( $name, $alias = false ) {
3257  if ( !$alias || (string)$alias === (string)$name ) {
3258  return $name;
3259  } else {
3260  return $name . ' AS ' . $this->addIdentifierQuotes( $alias ); // PostgreSQL needs AS
3261  }
3262  }
3263 
3270  protected function fieldNamesWithAlias( $fields ) {
3271  $retval = [];
3272  foreach ( $fields as $alias => $field ) {
3273  if ( is_numeric( $alias ) ) {
3274  $alias = $field;
3275  }
3276  $retval[] = $this->fieldNameWithAlias( $field, $alias );
3277  }
3278 
3279  return $retval;
3280  }
3281 
3293  $tables,
3294  $use_index = [],
3295  $ignore_index = [],
3296  $join_conds = []
3297  ) {
3298  $ret = [];
3299  $retJOIN = [];
3300  $use_index = (array)$use_index;
3301  $ignore_index = (array)$ignore_index;
3302  $join_conds = (array)$join_conds;
3303 
3304  foreach ( $tables as $alias => $table ) {
3305  if ( !is_string( $alias ) ) {
3306  // No alias? Set it equal to the table name
3307  $alias = $table;
3308  }
3309 
3310  if ( is_array( $table ) ) {
3311  // A parenthesized group
3312  if ( count( $table ) > 1 ) {
3313  $joinedTable = '(' .
3315  $table, $use_index, $ignore_index, $join_conds ) . ')';
3316  } else {
3317  // Degenerate case
3318  $innerTable = reset( $table );
3319  $innerAlias = key( $table );
3320  $joinedTable = $this->tableNameWithAlias(
3321  $innerTable,
3322  is_string( $innerAlias ) ? $innerAlias : $innerTable
3323  );
3324  }
3325  } else {
3326  $joinedTable = $this->tableNameWithAlias( $table, $alias );
3327  }
3328 
3329  // Is there a JOIN clause for this table?
3330  if ( isset( $join_conds[$alias] ) ) {
3331  Assert::parameterType( 'array', $join_conds[$alias], "join_conds[$alias]" );
3332  list( $joinType, $conds ) = $join_conds[$alias];
3333  $tableClause = $this->normalizeJoinType( $joinType );
3334  $tableClause .= ' ' . $joinedTable;
3335  if ( isset( $use_index[$alias] ) ) { // has USE INDEX?
3336  $use = $this->useIndexClause( implode( ',', (array)$use_index[$alias] ) );
3337  if ( $use != '' ) {
3338  $tableClause .= ' ' . $use;
3339  }
3340  }
3341  if ( isset( $ignore_index[$alias] ) ) { // has IGNORE INDEX?
3342  $ignore = $this->ignoreIndexClause(
3343  implode( ',', (array)$ignore_index[$alias] ) );
3344  if ( $ignore != '' ) {
3345  $tableClause .= ' ' . $ignore;
3346  }
3347  }
3348  $on = $this->makeList( (array)$conds, self::LIST_AND );
3349  if ( $on != '' ) {
3350  $tableClause .= ' ON (' . $on . ')';
3351  }
3352 
3353  $retJOIN[] = $tableClause;
3354  } elseif ( isset( $use_index[$alias] ) ) {
3355  // Is there an INDEX clause for this table?
3356  $tableClause = $joinedTable;
3357  $tableClause .= ' ' . $this->useIndexClause(
3358  implode( ',', (array)$use_index[$alias] )
3359  );
3360 
3361  $ret[] = $tableClause;
3362  } elseif ( isset( $ignore_index[$alias] ) ) {
3363  // Is there an INDEX clause for this table?
3364  $tableClause = $joinedTable;
3365  $tableClause .= ' ' . $this->ignoreIndexClause(
3366  implode( ',', (array)$ignore_index[$alias] )
3367  );
3368 
3369  $ret[] = $tableClause;
3370  } else {
3371  $tableClause = $joinedTable;
3372 
3373  $ret[] = $tableClause;
3374  }
3375  }
3376 
3377  // We can't separate explicit JOIN clauses with ',', use ' ' for those
3378  $implicitJoins = implode( ',', $ret );
3379  $explicitJoins = implode( ' ', $retJOIN );
3380 
3381  // Compile our final table clause
3382  return implode( ' ', [ $implicitJoins, $explicitJoins ] );
3383  }
3384 
3393  protected function normalizeJoinType( string $joinType ) {
3394  switch ( strtoupper( $joinType ) ) {
3395  case 'JOIN':
3396  case 'INNER JOIN':
3397  return 'JOIN';
3398 
3399  case 'LEFT JOIN':
3400  return 'LEFT JOIN';
3401 
3402  case 'STRAIGHT_JOIN':
3403  case 'STRAIGHT JOIN':
3404  // MySQL only
3405  return 'JOIN';
3406 
3407  default:
3408  return $joinType;
3409  }
3410  }
3411 
3418  protected function indexName( $index ) {
3419  return $this->indexAliases[$index] ?? $index;
3420  }
3421 
3426  public function addQuotes( $s ) {
3427  if ( $s instanceof Blob ) {
3428  $s = $s->fetch();
3429  }
3430  if ( $s === null ) {
3431  return 'NULL';
3432  } elseif ( is_bool( $s ) ) {
3433  return (string)(int)$s;
3434  } elseif ( is_int( $s ) ) {
3435  return (string)$s;
3436  } else {
3437  return "'" . $this->strencode( $s ) . "'";
3438  }
3439  }
3440 
3445  public function addIdentifierQuotes( $s ) {
3446  return '"' . str_replace( '"', '""', $s ) . '"';
3447  }
3448 
3459  public function isQuotedIdentifier( $name ) {
3460  return $name[0] == '"' && substr( $name, -1, 1 ) == '"';
3461  }
3462 
3469  protected function escapeLikeInternal( $s, $escapeChar = '`' ) {
3470  return str_replace(
3471  [ $escapeChar, '%', '_' ],
3472  [ "{$escapeChar}{$escapeChar}", "{$escapeChar}%", "{$escapeChar}_" ],
3473  $s
3474  );
3475  }
3476 
3481  public function buildLike( $param, ...$params ) {
3482  if ( is_array( $param ) ) {
3483  $params = $param;
3484  } else {
3485  $params = func_get_args();
3486  }
3487 
3488  $s = '';
3489 
3490  // We use ` instead of \ as the default LIKE escape character, since addQuotes()
3491  // may escape backslashes, creating problems of double escaping. The `
3492  // character has good cross-DBMS compatibility, avoiding special operators
3493  // in MS SQL like ^ and %
3494  $escapeChar = '`';
3495 
3496  foreach ( $params as $value ) {
3497  if ( $value instanceof LikeMatch ) {
3498  $s .= $value->toString();
3499  } else {
3500  $s .= $this->escapeLikeInternal( $value, $escapeChar );
3501  }
3502  }
3503 
3504  return ' LIKE ' .
3505  $this->addQuotes( $s ) . ' ESCAPE ' . $this->addQuotes( $escapeChar ) . ' ';
3506  }
3507 
3508  public function anyChar() {
3509  return new LikeMatch( '_' );
3510  }
3511 
3512  public function anyString() {
3513  return new LikeMatch( '%' );
3514  }
3515 
3516  public function nextSequenceValue( $seqName ) {
3517  return null;
3518  }
3519 
3533  public function useIndexClause( $index ) {
3534  return '';
3535  }
3536 
3546  public function ignoreIndexClause( $index ) {
3547  return '';
3548  }
3549 
3550  public function replace( $table, $uniqueKeys, $rows, $fname = __METHOD__ ) {
3551  $identityKey = $this->normalizeUpsertParams( $uniqueKeys, $rows );
3552  if ( !$rows ) {
3553  return;
3554  }
3555  if ( $identityKey ) {
3556  $this->doReplace( $table, $identityKey, $rows, $fname );
3557  } else {
3558  $this->doInsert( $table, $rows, $fname );
3559  }
3560  }
3561 
3571  protected function doReplace( $table, array $identityKey, array $rows, $fname ) {
3572  $affectedRowCount = 0;
3573  $this->startAtomic( $fname, self::ATOMIC_CANCELABLE );
3574  try {
3575  foreach ( $rows as $row ) {
3576  // Delete any conflicting rows (including ones inserted from $rows)
3577  $sqlCondition = $this->makeKeyCollisionCondition( [ $row ], $identityKey );
3578  $this->delete( $table, [ $sqlCondition ], $fname );
3579  $affectedRowCount += $this->affectedRows();
3580  // Now insert the row
3581  $this->insert( $table, $row, $fname );
3582  $affectedRowCount += $this->affectedRows();
3583  }
3584  $this->endAtomic( $fname );
3585  } catch ( DBError $e ) {
3586  $this->cancelAtomic( $fname );
3587  throw $e;
3588  }
3589  $this->affectedRowCount = $affectedRowCount;
3590  }
3591 
3599  private function makeKeyCollisionCondition( array $rows, array $uniqueKey ) {
3600  if ( !$rows ) {
3601  throw new DBUnexpectedError( $this, "Empty row array" );
3602  } elseif ( !$uniqueKey ) {
3603  throw new DBUnexpectedError( $this, "Empty unique key array" );
3604  }
3605 
3606  if ( count( $uniqueKey ) == 1 ) {
3607  // Use a simple IN(...) clause
3608  $column = reset( $uniqueKey );
3609  $values = array_column( $rows, $column );
3610  if ( count( $values ) !== count( $rows ) ) {
3611  throw new DBUnexpectedError( $this, "Missing values for unique key ($column)" );
3612  }
3613 
3614  return $this->makeList( [ $column => $values ], self::LIST_AND );
3615  }
3616 
3617  $nullByUniqueKeyColumn = array_fill_keys( $uniqueKey, null );
3618 
3619  $orConds = [];
3620  foreach ( $rows as $row ) {
3621  $rowKeyMap = array_intersect_key( $row, $nullByUniqueKeyColumn );
3622  if ( count( $rowKeyMap ) != count( $uniqueKey ) ) {
3623  throw new DBUnexpectedError(
3624  $this,
3625  "Missing values for unique key (" . implode( ',', $uniqueKey ) . ")"
3626  );
3627  }
3628  $orConds[] = $this->makeList( $rowKeyMap, self::LIST_AND );
3629  }
3630 
3631  return count( $orConds ) > 1
3632  ? $this->makeList( $orConds, self::LIST_OR )
3633  : $orConds[0];
3634  }
3635 
3636  public function upsert( $table, array $rows, $uniqueKeys, array $set, $fname = __METHOD__ ) {
3637  $identityKey = $this->normalizeUpsertParams( $uniqueKeys, $rows );
3638  if ( !$rows ) {
3639  return true;
3640  }
3641  if ( $identityKey ) {
3642  $this->assertValidUpsertSetArray( $set, $identityKey, $rows );
3643  $this->doUpsert( $table, $rows, $identityKey, $set, $fname );
3644  } else {
3645  $this->doInsert( $table, $rows, $fname );
3646  }
3647 
3648  return true;
3649  }
3650 
3661  protected function doUpsert(
3662  string $table,
3663  array $rows,
3664  array $identityKey,
3665  array $set,
3666  string $fname
3667  ) {
3668  $affectedRowCount = 0;
3669  $this->startAtomic( $fname, self::ATOMIC_CANCELABLE );
3670  try {
3671  foreach ( $rows as $row ) {
3672  // Update any existing conflicting rows (including ones inserted from $rows)
3673  $sqlConditions = $this->makeKeyCollisionCondition( [ $row ], $identityKey );
3674  $this->update( $table, $set, [ $sqlConditions ], $fname );
3675  $rowsUpdated = $this->affectedRows();
3676  $affectedRowCount += $rowsUpdated;
3677  if ( $rowsUpdated <= 0 ) {
3678  // Now insert the row if there are no conflicts
3679  $this->insert( $table, $row, $fname );
3680  $affectedRowCount += $this->affectedRows();
3681  }
3682  }
3683  $this->endAtomic( $fname );
3684  } catch ( DBError $e ) {
3685  $this->cancelAtomic( $fname );
3686  throw $e;
3687  }
3688  $this->affectedRowCount = $affectedRowCount;
3689  }
3690 
3695  public function deleteJoin(
3696  $delTable,
3697  $joinTable,
3698  $delVar,
3699  $joinVar,
3700  $conds,
3701  $fname = __METHOD__
3702  ) {
3703  if ( !$conds ) {
3704  throw new DBUnexpectedError( $this, __METHOD__ . ' called with empty $conds' );
3705  }
3706 
3707  $delTable = $this->tableName( $delTable );
3708  $joinTable = $this->tableName( $joinTable );
3709  $sql = "DELETE FROM $delTable WHERE $delVar IN (SELECT $joinVar FROM $joinTable ";
3710  if ( $conds != '*' ) {
3711  $sql .= 'WHERE ' . $this->makeList( $conds, self::LIST_AND );
3712  }
3713  $sql .= ')';
3714 
3715  $this->query( $sql, $fname, self::QUERY_CHANGE_ROWS );
3716  }
3717 
3722  public function textFieldSize( $table, $field ) {
3723  $table = $this->tableName( $table );
3724  $res = $this->query(
3725  "SHOW COLUMNS FROM $table LIKE \"$field\"",
3726  __METHOD__,
3727  self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE
3728  );
3729  $row = $this->fetchObject( $res );
3730 
3731  $m = [];
3732 
3733  if ( preg_match( '/\‍((.*)\‍)/', $row->Type, $m ) ) {
3734  $size = $m[1];
3735  } else {
3736  $size = -1;
3737  }
3738 
3739  return $size;
3740  }
3741 
3742  public function delete( $table, $conds, $fname = __METHOD__ ) {
3743  $this->assertConditionIsNotEmpty( $conds, __METHOD__, false );
3744 
3745  $table = $this->tableName( $table );
3746  $sql = "DELETE FROM $table";
3747 
3748  if ( $conds !== IDatabase::ALL_ROWS ) {
3749  if ( is_array( $conds ) ) {
3750  $conds = $this->makeList( $conds, self::LIST_AND );
3751  }
3752  $sql .= ' WHERE ' . $conds;
3753  }
3754 
3755  $this->query( $sql, $fname, self::QUERY_CHANGE_ROWS );
3756 
3757  return true;
3758  }
3759 
3760  final public function insertSelect(
3761  $destTable,
3762  $srcTable,
3763  $varMap,
3764  $conds,
3765  $fname = __METHOD__,
3766  $insertOptions = [],
3767  $selectOptions = [],
3768  $selectJoinConds = []
3769  ) {
3770  static $hints = [ 'NO_AUTO_COLUMNS' ];
3771 
3772  $insertOptions = $this->normalizeOptions( $insertOptions );
3773  $selectOptions = $this->normalizeOptions( $selectOptions );
3774 
3775  if ( $this->cliMode && $this->isInsertSelectSafe( $insertOptions, $selectOptions ) ) {
3776  // For massive migrations with downtime, we don't want to select everything
3777  // into memory and OOM, so do all this native on the server side if possible.
3778  $this->doInsertSelectNative(
3779  $destTable,
3780  $srcTable,
3781  $varMap,
3782  $conds,
3783  $fname,
3784  array_diff( $insertOptions, $hints ),
3785  $selectOptions,
3786  $selectJoinConds
3787  );
3788  } else {
3789  $this->doInsertSelectGeneric(
3790  $destTable,
3791  $srcTable,
3792  $varMap,
3793  $conds,
3794  $fname,
3795  array_diff( $insertOptions, $hints ),
3796  $selectOptions,
3797  $selectJoinConds
3798  );
3799  }
3800 
3801  return true;
3802  }
3803 
3811  protected function isInsertSelectSafe( array $insertOptions, array $selectOptions ) {
3812  return true;
3813  }
3814 
3829  protected function doInsertSelectGeneric(
3830  $destTable,
3831  $srcTable,
3832  array $varMap,
3833  $conds,
3834  $fname,
3835  array $insertOptions,
3836  array $selectOptions,
3837  $selectJoinConds
3838  ) {
3839  // For web requests, do a locking SELECT and then INSERT. This puts the SELECT burden
3840  // on only the primary DB (without needing row-based-replication). It also makes it easy to
3841  // know how big the INSERT is going to be.
3842  $fields = [];
3843  foreach ( $varMap as $dstColumn => $sourceColumnOrSql ) {
3844  $fields[] = $this->fieldNameWithAlias( $sourceColumnOrSql, $dstColumn );
3845  }
3846  $res = $this->select(
3847  $srcTable,
3848  implode( ',', $fields ),
3849  $conds,
3850  $fname,
3851  array_merge( $selectOptions, [ 'FOR UPDATE' ] ),
3852  $selectJoinConds
3853  );
3854  if ( !$res ) {
3855  return;
3856  }
3857 
3858  $affectedRowCount = 0;
3859  $this->startAtomic( $fname, self::ATOMIC_CANCELABLE );
3860  try {
3861  $rows = [];
3862  foreach ( $res as $row ) {
3863  $rows[] = (array)$row;
3864  }
3865  // Avoid inserts that are too huge
3866  $rowBatches = array_chunk( $rows, $this->nonNativeInsertSelectBatchSize );
3867  foreach ( $rowBatches as $rows ) {
3868  $this->insert( $destTable, $rows, $fname, $insertOptions );
3869  $affectedRowCount += $this->affectedRows();
3870  }
3871  } catch ( DBError $e ) {
3872  $this->cancelAtomic( $fname );
3873  throw $e;
3874  }
3875  $this->endAtomic( $fname );
3876  $this->affectedRowCount = $affectedRowCount;
3877  }
3878 
3894  protected function doInsertSelectNative(
3895  $destTable,
3896  $srcTable,
3897  array $varMap,
3898  $conds,
3899  $fname,
3900  array $insertOptions,
3901  array $selectOptions,
3902  $selectJoinConds
3903  ) {
3904  list( $sqlVerb, $sqlOpts ) = $this->isFlagInOptions( 'IGNORE', $insertOptions )
3906  : [ 'INSERT INTO', '' ];
3907  $encDstTable = $this->tableName( $destTable );
3908  $sqlDstColumns = implode( ',', array_keys( $varMap ) );
3909  $selectSql = $this->selectSQLText(
3910  $srcTable,
3911  array_values( $varMap ),
3912  $conds,
3913  $fname,
3914  $selectOptions,
3915  $selectJoinConds
3916  );
3917 
3918  $sql = rtrim( "$sqlVerb $encDstTable ($sqlDstColumns) $selectSql $sqlOpts" );
3919 
3920  $this->query( $sql, $fname, self::QUERY_CHANGE_ROWS );
3921  }
3922 
3927  public function limitResult( $sql, $limit, $offset = false ) {
3928  if ( !is_numeric( $limit ) ) {
3929  throw new DBUnexpectedError(
3930  $this,
3931  "Invalid non-numeric limit passed to " . __METHOD__
3932  );
3933  }
3934  // This version works in MySQL and SQLite. It will very likely need to be
3935  // overridden for most other RDBMS subclasses.
3936  return "$sql LIMIT "
3937  . ( ( is_numeric( $offset ) && $offset != 0 ) ? "{$offset}," : "" )
3938  . "{$limit} ";
3939  }
3940 
3945  public function unionSupportsOrderAndLimit() {
3946  return true; // True for almost every DB supported
3947  }
3948 
3953  public function unionQueries( $sqls, $all ) {
3954  $glue = $all ? ') UNION ALL (' : ') UNION (';
3955 
3956  return '(' . implode( $glue, $sqls ) . ')';
3957  }
3958 
3960  $table,
3961  $vars,
3962  array $permute_conds,
3963  $extra_conds = '',
3964  $fname = __METHOD__,
3965  $options = [],
3966  $join_conds = []
3967  ) {
3968  // First, build the Cartesian product of $permute_conds
3969  $conds = [ [] ];
3970  foreach ( $permute_conds as $field => $values ) {
3971  if ( !$values ) {
3972  // Skip empty $values
3973  continue;
3974  }
3975  $values = array_unique( $values );
3976  $newConds = [];
3977  foreach ( $conds as $cond ) {
3978  foreach ( $values as $value ) {
3979  $cond[$field] = $value;
3980  $newConds[] = $cond; // Arrays are by-value, not by-reference, so this works
3981  }
3982  }
3983  $conds = $newConds;
3984  }
3985 
3986  $extra_conds = $extra_conds === '' ? [] : (array)$extra_conds;
3987 
3988  // If there's just one condition and no subordering, hand off to
3989  // selectSQLText directly.
3990  if ( count( $conds ) === 1 &&
3991  ( !isset( $options['INNER ORDER BY'] ) || !$this->unionSupportsOrderAndLimit() )
3992  ) {
3993  return $this->selectSQLText(
3994  $table, $vars, $conds[0] + $extra_conds, $fname, $options, $join_conds
3995  );
3996  }
3997 
3998  // Otherwise, we need to pull out the order and limit to apply after
3999  // the union. Then build the SQL queries for each set of conditions in
4000  // $conds. Then union them together (using UNION ALL, because the
4001  // product *should* already be distinct).
4002  $orderBy = $this->makeOrderBy( $options );
4003  $limit = $options['LIMIT'] ?? null;
4004  $offset = $options['OFFSET'] ?? false;
4005  $all = empty( $options['NOTALL'] ) && !in_array( 'NOTALL', $options );
4006  if ( !$this->unionSupportsOrderAndLimit() ) {
4007  unset( $options['ORDER BY'], $options['LIMIT'], $options['OFFSET'] );
4008  } else {
4009  if ( array_key_exists( 'INNER ORDER BY', $options ) ) {
4010  $options['ORDER BY'] = $options['INNER ORDER BY'];
4011  }
4012  if ( $limit !== null && is_numeric( $offset ) && $offset != 0 ) {
4013  // We need to increase the limit by the offset rather than
4014  // using the offset directly, otherwise it'll skip incorrectly
4015  // in the subqueries.
4016  $options['LIMIT'] = $limit + $offset;
4017  unset( $options['OFFSET'] );
4018  }
4019  }
4020 
4021  $sqls = [];
4022  foreach ( $conds as $cond ) {
4023  $sqls[] = $this->selectSQLText(
4024  $table, $vars, $cond + $extra_conds, $fname, $options, $join_conds
4025  );
4026  }
4027  $sql = $this->unionQueries( $sqls, $all ) . $orderBy;
4028  if ( $limit !== null ) {
4029  $sql = $this->limitResult( $sql, $limit, $offset );
4030  }
4031 
4032  return $sql;
4033  }
4034 
4039  public function conditional( $cond, $caseTrueExpression, $caseFalseExpression ) {
4040  if ( is_array( $cond ) ) {
4041  $cond = $this->makeList( $cond, self::LIST_AND );
4042  }
4043 
4044  return "(CASE WHEN $cond THEN $caseTrueExpression ELSE $caseFalseExpression END)";
4045  }
4046 
4051  public function strreplace( $orig, $old, $new ) {
4052  return "REPLACE({$orig}, {$old}, {$new})";
4053  }
4054 
4059  public function wasDeadlock() {
4060  return false;
4061  }
4062 
4067  public function wasLockTimeout() {
4068  return false;
4069  }
4070 
4075  public function wasConnectionLoss() {
4076  return $this->isConnectionError( $this->lastErrno() );
4077  }
4078 
4083  public function wasReadOnlyError() {
4084  return false;
4085  }
4086 
4087  public function wasErrorReissuable() {
4088  return (
4089  $this->wasDeadlock() ||
4090  $this->wasLockTimeout() ||
4091  $this->wasConnectionLoss()
4092  );
4093  }
4094 
4102  protected function isConnectionError( $errno ) {
4103  return false;
4104  }
4105 
4113  protected function wasKnownStatementRollbackError() {
4114  return false; // don't know; it could have caused a transaction rollback
4115  }
4116 
4121  public function deadlockLoop( ...$args ) {
4122  $function = array_shift( $args );
4123  $tries = self::DEADLOCK_TRIES;
4124 
4125  $this->begin( __METHOD__ );
4126 
4127  $retVal = null;
4129  $e = null;
4130  do {
4131  try {
4132  $retVal = $function( ...$args );
4133  break;
4134  } catch ( DBQueryError $e ) {
4135  if ( $this->wasDeadlock() ) {
4136  // Retry after a randomized delay
4137  usleep( mt_rand( self::DEADLOCK_DELAY_MIN, self::DEADLOCK_DELAY_MAX ) );
4138  } else {
4139  // Throw the error back up
4140  throw $e;
4141  }
4142  }
4143  } while ( --$tries > 0 );
4144 
4145  if ( $tries <= 0 ) {
4146  // Too many deadlocks; give up
4147  $this->rollback( __METHOD__ );
4148  throw $e;
4149  } else {
4150  $this->commit( __METHOD__ );
4151 
4152  return $retVal;
4153  }
4154  }
4155 
4161  public function primaryPosWait( DBPrimaryPos $pos, $timeout ) {
4162  # Real waits are implemented in the subclass.
4163  return 0;
4164  }
4165 
4170  public function getReplicaPos() {
4171  # Stub
4172  return false;
4173  }
4174 
4179  public function getPrimaryPos() {
4180  # Stub
4181  return false;
4182  }
4183 
4188  public function serverIsReadOnly() {
4189  return false;
4190  }
4191 
4192  final public function onTransactionResolution( callable $callback, $fname = __METHOD__ ) {
4193  if ( !$this->trxLevel() ) {
4194  throw new DBUnexpectedError( $this, "No transaction is active" );
4195  }
4196  $this->trxEndCallbacks[] = [ $callback, $fname, $this->currentAtomicSectionId() ];
4197  }
4198 
4199  final public function onTransactionCommitOrIdle( callable $callback, $fname = __METHOD__ ) {
4200  if ( !$this->trxLevel() && $this->getTransactionRoundId() ) {
4201  // This DB handle is set to participate in LoadBalancer transaction rounds and
4202  // an explicit transaction round is active. Start an implicit transaction on this
4203  // DB handle (setting trxAutomatic) similar to how query() does in such situations.
4204  $this->begin( __METHOD__, self::TRANSACTION_INTERNAL );
4205  }
4206 
4207  $this->trxPostCommitOrIdleCallbacks[] = [
4208  $callback,
4209  $fname,
4210  $this->currentAtomicSectionId()
4211  ];
4212 
4213  if ( !$this->trxLevel() ) {
4214  $dbErrors = [];
4215  $this->runOnTransactionIdleCallbacks( self::TRIGGER_IDLE, $dbErrors );
4216  if ( $dbErrors ) {
4217  throw $dbErrors[0];
4218  }
4219  }
4220  }
4221 
4222  final public function onTransactionPreCommitOrIdle( callable $callback, $fname = __METHOD__ ) {
4223  if ( !$this->trxLevel() && $this->getTransactionRoundId() ) {
4224  // This DB handle is set to participate in LoadBalancer transaction rounds and
4225  // an explicit transaction round is active. Start an implicit transaction on this
4226  // DB handle (setting trxAutomatic) similar to how query() does in such situations.
4227  $this->begin( __METHOD__, self::TRANSACTION_INTERNAL );
4228  }
4229 
4230  if ( $this->trxLevel() ) {
4231  $this->trxPreCommitOrIdleCallbacks[] = [
4232  $callback,
4233  $fname,
4234  $this->currentAtomicSectionId()
4235  ];
4236  } else {
4237  // No transaction is active nor will start implicitly, so make one for this callback
4238  $this->startAtomic( __METHOD__, self::ATOMIC_CANCELABLE );
4239  try {
4240  $callback( $this );
4241  } catch ( Throwable $e ) {
4242  // Avoid confusing error reporting during critical section errors
4243  if ( !$this->csmError ) {
4244  $this->cancelAtomic( __METHOD__ );
4245  }
4246  throw $e;
4247  }
4248  $this->endAtomic( __METHOD__ );
4249  }
4250  }
4251 
4252  final public function onAtomicSectionCancel( callable $callback, $fname = __METHOD__ ) {
4253  if ( !$this->trxLevel() || !$this->trxAtomicLevels ) {
4254  throw new DBUnexpectedError( $this, "No atomic section is open (got $fname)" );
4255  }
4256  $this->trxSectionCancelCallbacks[] = [ $callback, $fname, $this->currentAtomicSectionId() ];
4257  }
4258 
4262  private function currentAtomicSectionId() {
4263  if ( $this->trxLevel() && $this->trxAtomicLevels ) {
4264  $levelInfo = end( $this->trxAtomicLevels );
4265 
4266  return $levelInfo[1];
4267  }
4268 
4269  return null;
4270  }
4271 
4281  ) {
4282  foreach ( $this->trxPreCommitOrIdleCallbacks as $key => $info ) {
4283  if ( $info[2] === $old ) {
4284  $this->trxPreCommitOrIdleCallbacks[$key][2] = $new;
4285  }
4286  }
4287  foreach ( $this->trxPostCommitOrIdleCallbacks as $key => $info ) {
4288  if ( $info[2] === $old ) {
4289  $this->trxPostCommitOrIdleCallbacks[$key][2] = $new;
4290  }
4291  }
4292  foreach ( $this->trxEndCallbacks as $key => $info ) {
4293  if ( $info[2] === $old ) {
4294  $this->trxEndCallbacks[$key][2] = $new;
4295  }
4296  }
4297  foreach ( $this->trxSectionCancelCallbacks as $key => $info ) {
4298  if ( $info[2] === $old ) {
4299  $this->trxSectionCancelCallbacks[$key][2] = $new;
4300  }
4301  }
4302  }
4303 
4323  private function modifyCallbacksForCancel(
4324  array $sectionIds,
4325  AtomicSectionIdentifier $newSectionId = null
4326  ) {
4327  // Cancel the "on commit" callbacks owned by this savepoint
4328  $this->trxPostCommitOrIdleCallbacks = array_filter(
4329  $this->trxPostCommitOrIdleCallbacks,
4330  static function ( $entry ) use ( $sectionIds ) {
4331  return !in_array( $entry[2], $sectionIds, true );
4332  }
4333  );
4334  $this->trxPreCommitOrIdleCallbacks = array_filter(
4335  $this->trxPreCommitOrIdleCallbacks,
4336  static function ( $entry ) use ( $sectionIds ) {
4337  return !in_array( $entry[2], $sectionIds, true );
4338  }
4339  );
4340  // Make "on resolution" callbacks owned by this savepoint to perceive a rollback
4341  foreach ( $this->trxEndCallbacks as $key => $entry ) {
4342  if ( in_array( $entry[2], $sectionIds, true ) ) {
4343  $callback = $entry[0];
4344  $this->trxEndCallbacks[$key][0] = function () use ( $callback ) {
4345  return $callback( self::TRIGGER_ROLLBACK, $this );
4346  };
4347  // This "on resolution" callback no longer belongs to a section.
4348  $this->trxEndCallbacks[$key][2] = null;
4349  }
4350  }
4351  // Hoist callback ownership for section cancel callbacks to the new top section
4352  foreach ( $this->trxSectionCancelCallbacks as $key => $entry ) {
4353  if ( in_array( $entry[2], $sectionIds, true ) ) {
4354  $this->trxSectionCancelCallbacks[$key][2] = $newSectionId;
4355  }
4356  }
4357  }
4358 
4359  final public function setTransactionListener( $name, callable $callback = null ) {
4360  if ( $callback ) {
4361  $this->trxRecurringCallbacks[$name] = $callback;
4362  } else {
4363  unset( $this->trxRecurringCallbacks[$name] );
4364  }
4365  }
4366 
4375  final public function setTrxEndCallbackSuppression( $suppress ) {
4376  $this->trxEndCallbacksSuppressed = $suppress;
4377  }
4378 
4391  public function runOnTransactionIdleCallbacks( $trigger, array &$errors = [] ) {
4392  if ( $this->trxLevel() ) {
4393  throw new DBUnexpectedError( $this, __METHOD__ . ': a transaction is still open' );
4394  }
4395 
4396  if ( $this->trxEndCallbacksSuppressed ) {
4397  // Execution deferred by LoadBalancer for explicit execution later
4398  return 0;
4399  }
4400 
4401  $cs = $this->commenceCriticalSection( __METHOD__ );
4402 
4403  $count = 0;
4404  $autoTrx = $this->getFlag( self::DBO_TRX ); // automatic begin() enabled?
4405  // Drain the queues of transaction "idle" and "end" callbacks until they are empty
4406  do {
4407  $callbackEntries = array_merge(
4408  $this->trxPostCommitOrIdleCallbacks,
4409  $this->trxEndCallbacks,
4410  ( $trigger === self::TRIGGER_ROLLBACK )
4411  ? $this->trxSectionCancelCallbacks
4412  : [] // just consume them
4413  );
4414  $this->trxPostCommitOrIdleCallbacks = []; // consumed (and recursion guard)
4415  $this->trxEndCallbacks = []; // consumed (recursion guard)
4416  $this->trxSectionCancelCallbacks = []; // consumed (recursion guard)
4417 
4418  $count += count( $callbackEntries );
4419  foreach ( $callbackEntries as $entry ) {
4420  $this->clearFlag( self::DBO_TRX ); // make each query its own transaction
4421  try {
4422  $entry[0]( $trigger, $this );
4423  } catch ( DBError $ex ) {
4424  call_user_func( $this->errorLogger, $ex );
4425  $errors[] = $ex;
4426  // Some callbacks may use startAtomic/endAtomic, so make sure
4427  // their transactions are ended so other callbacks don't fail
4428  if ( $this->trxLevel() ) {
4429  $this->rollback( __METHOD__, self::FLUSHING_INTERNAL );
4430  }
4431  } finally {
4432  if ( $autoTrx ) {
4433  $this->setFlag( self::DBO_TRX ); // restore automatic begin()
4434  } else {
4435  $this->clearFlag( self::DBO_TRX ); // restore auto-commit
4436  }
4437  }
4438  }
4439  // @phan-suppress-next-line PhanImpossibleConditionInLoop
4440  } while ( count( $this->trxPostCommitOrIdleCallbacks ) );
4441 
4442  $this->completeCriticalSection( __METHOD__, $cs );
4443 
4444  return $count;
4445  }
4446 
4457  $count = 0;
4458 
4459  // Drain the queues of transaction "precommit" callbacks until it is empty
4460  do {
4461  $callbackEntries = $this->trxPreCommitOrIdleCallbacks;
4462  $this->trxPreCommitOrIdleCallbacks = []; // consumed (and recursion guard)
4463  $count += count( $callbackEntries );
4464  foreach ( $callbackEntries as $entry ) {
4465  try {
4466  // @phan-suppress-next-line PhanUndeclaredInvokeInCallable
4467  $entry[0]( $this );
4468  } catch ( Throwable $trxError ) {
4469  $this->setTransactionError( $trxError );
4470  throw $trxError;
4471  }
4472  }
4473  // @phan-suppress-next-line PhanImpossibleConditionInLoop
4474  } while ( $this->trxPreCommitOrIdleCallbacks );
4475 
4476  return $count;
4477  }
4478 
4486  private function runOnAtomicSectionCancelCallbacks( $trigger, array $sectionIds ) {
4487  // Drain the queue of matching "atomic section cancel" callbacks until there are none
4488  $unrelatedCallbackEntries = [];
4489  do {
4490  $callbackEntries = $this->trxSectionCancelCallbacks;
4491  $this->trxSectionCancelCallbacks = []; // consumed (recursion guard)
4492  foreach ( $callbackEntries as $entry ) {
4493  if ( in_array( $entry[2], $sectionIds, true ) ) {
4494  try {
4495  // @phan-suppress-next-line PhanUndeclaredInvokeInCallable
4496  $entry[0]( $trigger, $this );
4497  } catch ( Throwable $trxError ) {
4498  $this->setTransactionError( $trxError );
4499  throw $trxError;
4500  }
4501  } else {
4502  $unrelatedCallbackEntries[] = $entry;
4503  }
4504  }
4505  // @phan-suppress-next-line PhanImpossibleConditionInLoop
4506  } while ( $this->trxSectionCancelCallbacks );
4507 
4508  $this->trxSectionCancelCallbacks = $unrelatedCallbackEntries;
4509  }
4510 
4521  public function runTransactionListenerCallbacks( $trigger, array &$errors = [] ) {
4522  if ( $this->trxEndCallbacksSuppressed ) {
4523  // Execution deferred by LoadBalancer for explicit execution later
4524  return;
4525  }
4526 
4527  // These callbacks should only be registered in setup, thus no iteration is needed
4528  foreach ( $this->trxRecurringCallbacks as $callback ) {
4529  try {
4530  $callback( $trigger, $this );
4531  } catch ( DBError $ex ) {
4532  ( $this->errorLogger )( $ex );
4533  $errors[] = $ex;
4534  }
4535  }
4536  }
4537 
4545  $dbErrors = [];
4546  $this->runOnTransactionIdleCallbacks( self::TRIGGER_COMMIT, $dbErrors );
4547  $this->runTransactionListenerCallbacks( self::TRIGGER_COMMIT, $dbErrors );
4548  $this->affectedRowCount = 0; // for the sake of consistency
4549  if ( $dbErrors ) {
4550  throw $dbErrors[0];
4551  }
4552  }
4553 
4562  $this->runOnTransactionIdleCallbacks( self::TRIGGER_ROLLBACK );
4563  $this->runTransactionListenerCallbacks( self::TRIGGER_ROLLBACK );
4564  $this->affectedRowCount = 0; // for the sake of consistency
4565  }
4566 
4578  protected function doSavepoint( $identifier, $fname ) {
4579  $sql = 'SAVEPOINT ' . $this->addIdentifierQuotes( $identifier );
4580  $this->query( $sql, $fname, self::QUERY_CHANGE_TRX );
4581  }
4582 
4594  protected function doReleaseSavepoint( $identifier, $fname ) {
4595  $sql = 'RELEASE SAVEPOINT ' . $this->addIdentifierQuotes( $identifier );
4596  $this->query( $sql, $fname, self::QUERY_CHANGE_TRX );
4597  }
4598 
4610  protected function doRollbackToSavepoint( $identifier, $fname ) {
4611  $sql = 'ROLLBACK TO SAVEPOINT ' . $this->addIdentifierQuotes( $identifier );
4612  $this->query( $sql, $fname, self::QUERY_CHANGE_TRX );
4613  }
4614 
4619  private function nextSavepointId( $fname ) {
4620  $savepointId = self::SAVEPOINT_PREFIX . ++$this->trxAtomicCounter;
4621  if ( strlen( $savepointId ) > 30 ) {
4622  // 30 == Oracle's identifier length limit (pre 12c)
4623  // With a 22 character prefix, that puts the highest number at 99999999.
4624  throw new DBUnexpectedError(
4625  $this,
4626  'There have been an excessively large number of atomic sections in a transaction'
4627  . " started by $this->trxFname (at $fname)"
4628  );
4629  }
4630 
4631  return $savepointId;
4632  }
4633 
4634  final public function startAtomic(
4635  $fname = __METHOD__,
4636  $cancelable = self::ATOMIC_NOT_CANCELABLE
4637  ) {
4638  $cs = $this->commenceCriticalSection( __METHOD__ );
4639 
4640  if ( $this->trxLevel() ) {
4641  // This atomic section is only one part of a larger transaction
4642  $sectionOwnsTrx = false;
4643  } else {
4644  // Start an implicit transaction (sets trxAutomatic)
4645  try {
4646  $this->begin( $fname, self::TRANSACTION_INTERNAL );
4647  } catch ( DBError $e ) {
4648  $this->completeCriticalSection( __METHOD__, $cs );
4649  throw $e;
4650  }
4651  if ( $this->getFlag( self::DBO_TRX ) ) {
4652  // This DB handle participates in LoadBalancer transaction rounds; all atomic
4653  // sections should be buffered into one transaction (e.g. to keep web requests
4654  // transactional). Note that an implicit transaction round is considered to be
4655  // active when no there is no explicit transaction round.
4656  $sectionOwnsTrx = false;
4657  } else {
4658  // This DB handle does not participate in LoadBalancer transaction rounds;
4659  // each topmost atomic section will use its own transaction.
4660  $sectionOwnsTrx = true;
4661  }
4662  $this->trxAutomaticAtomic = $sectionOwnsTrx;
4663  }
4664 
4665  if ( $cancelable === self::ATOMIC_CANCELABLE ) {
4666  if ( $sectionOwnsTrx ) {
4667  // This atomic section is synonymous with the whole transaction; just
4668  // use full COMMIT/ROLLBACK in endAtomic()/cancelAtomic(), respectively
4669  $savepointId = self::NOT_APPLICABLE;
4670  } else {
4671  // This atomic section is only part of the whole transaction; use a SAVEPOINT
4672  // query so that its changes can be cancelled without losing the rest of the
4673  // transaction (e.g. changes from other sections or from outside of sections)
4674  try {
4675  $savepointId = $this->nextSavepointId( $fname );
4676  $this->doSavepoint( $savepointId, $fname );
4677  } catch ( DBError $e ) {
4678  $this->completeCriticalSection( __METHOD__, $cs, $e );
4679  throw $e;
4680  }
4681  }
4682  } else {
4683  $savepointId = null;
4684  }
4685 
4686  $sectionId = new AtomicSectionIdentifier;
4687  $this->trxAtomicLevels[] = [ $fname, $sectionId, $savepointId ];
4688  $this->queryLogger->debug( 'startAtomic: entering level ' .
4689  ( count( $this->trxAtomicLevels ) - 1 ) . " ($fname)" );
4690 
4691  $this->completeCriticalSection( __METHOD__, $cs );
4692 
4693  return $sectionId;
4694  }
4695 
4696  final public function endAtomic( $fname = __METHOD__ ) {
4697  if ( !$this->trxLevel() || !$this->trxAtomicLevels ) {
4698  throw new DBUnexpectedError( $this, "No atomic section is open (got $fname)" );
4699  }
4700 
4701  // Check if the current section matches $fname
4702  $pos = count( $this->trxAtomicLevels ) - 1;
4703  list( $savedFname, $sectionId, $savepointId ) = $this->trxAtomicLevels[$pos];
4704  $this->queryLogger->debug( "endAtomic: leaving level $pos ($fname)" );
4705 
4706  if ( $savedFname !== $fname ) {
4707  throw new DBUnexpectedError(
4708  $this,
4709  "Invalid atomic section ended (got $fname but expected $savedFname)"
4710  );
4711  }
4712 
4713  $runPostCommitCallbacks = false;
4714 
4715  $cs = $this->commenceCriticalSection( __METHOD__ );
4716 
4717  // Remove the last section (no need to re-index the array)
4718  array_pop( $this->trxAtomicLevels );
4719 
4720  try {
4721  if ( !$this->trxAtomicLevels && $this->trxAutomaticAtomic ) {
4722  $this->commit( $fname, self::FLUSHING_INTERNAL );
4723  $runPostCommitCallbacks = true;
4724  } elseif ( $savepointId !== null && $savepointId !== self::NOT_APPLICABLE ) {
4725  $this->doReleaseSavepoint( $savepointId, $fname );
4726  }
4727  } catch ( DBError $e ) {
4728  $this->completeCriticalSection( __METHOD__, $cs, $e );
4729  throw $e;
4730  }
4731 
4732  // Hoist callback ownership for callbacks in the section that just ended;
4733  // all callbacks should have an owner that is present in trxAtomicLevels.
4734  $currentSectionId = $this->currentAtomicSectionId();
4735  if ( $currentSectionId ) {
4736  $this->reassignCallbacksForSection( $sectionId, $currentSectionId );
4737  }
4738 
4739  $this->completeCriticalSection( __METHOD__, $cs );
4740 
4741  if ( $runPostCommitCallbacks ) {
4743  }
4744  }
4745 
4746  final public function cancelAtomic(
4747  $fname = __METHOD__,
4748  AtomicSectionIdentifier $sectionId = null
4749  ) {
4750  if ( !$this->trxLevel() || !$this->trxAtomicLevels ) {
4751  throw new DBUnexpectedError( $this, "No atomic section is open (got $fname)" );
4752  }
4753 
4754  if ( $sectionId !== null ) {
4755  // Find the (last) section with the given $sectionId
4756  $pos = -1;
4757  foreach ( $this->trxAtomicLevels as $i => list( $asFname, $asId, $spId ) ) {
4758  if ( $asId === $sectionId ) {
4759  $pos = $i;
4760  }
4761  }
4762  if ( $pos < 0 ) {
4763  throw new DBUnexpectedError( $this, "Atomic section not found (for $fname)" );
4764  }
4765  } else {
4766  $pos = null;
4767  }
4768 
4769  $cs = $this->commenceCriticalSection( __METHOD__ );
4770 
4771  $excisedIds = [];
4772  $excisedFnames = [];
4773  $newTopSection = $this->currentAtomicSectionId();
4774  if ( $pos !== null ) {
4775  // Remove all descendant sections and re-index the array
4776  $len = count( $this->trxAtomicLevels );
4777  for ( $i = $pos + 1; $i < $len; ++$i ) {
4778  $excisedFnames[] = $this->trxAtomicLevels[$i][0];
4779  $excisedIds[] = $this->trxAtomicLevels[$i][1];
4780  }
4781  $this->trxAtomicLevels = array_slice( $this->trxAtomicLevels, 0, $pos + 1 );
4782  $newTopSection = $this->currentAtomicSectionId();
4783  }
4784 
4785  $runPostRollbackCallbacks = false;
4786  try {
4787  // Check if the current section matches $fname
4788  $pos = count( $this->trxAtomicLevels ) - 1;
4789  list( $savedFname, $savedSectionId, $savepointId ) = $this->trxAtomicLevels[$pos];
4790 
4791  if ( $excisedFnames ) {
4792  $this->queryLogger->debug( "cancelAtomic: canceling level $pos ($savedFname) " .
4793  "and descendants " . implode( ', ', $excisedFnames ) );
4794  } else {
4795  $this->queryLogger->debug( "cancelAtomic: canceling level $pos ($savedFname)" );
4796  }
4797 
4798  if ( $savedFname !== $fname ) {
4799  $e = new DBUnexpectedError(
4800  $this,
4801  "Invalid atomic section ended (got $fname but expected $savedFname)"
4802  );
4803  $this->completeCriticalSection( __METHOD__, $cs, $e );
4804  throw $e;
4805  }
4806 
4807  // Remove the last section (no need to re-index the array)
4808  array_pop( $this->trxAtomicLevels );
4809  $excisedIds[] = $savedSectionId;
4810  $newTopSection = $this->currentAtomicSectionId();
4811 
4812  if ( $savepointId !== null ) {
4813  // Rollback the transaction changes proposed within this atomic section
4814  if ( $savepointId === self::NOT_APPLICABLE ) {
4815  // Atomic section started the transaction; rollback the whole transaction
4816  // and trigger cancellation callbacks for all active atomic sections
4817  $this->rollback( $fname, self::FLUSHING_INTERNAL );
4818  $runPostRollbackCallbacks = true;
4819  } else {
4820  // Atomic section nested within the transaction; rollback the transaction
4821  // to the state prior to this section and trigger its cancellation callbacks
4822  $this->doRollbackToSavepoint( $savepointId, $fname );
4823  $this->trxStatus = self::STATUS_TRX_OK; // no exception; recovered
4824  $this->trxStatusIgnoredCause = null;
4825  $this->runOnAtomicSectionCancelCallbacks( self::TRIGGER_CANCEL, $excisedIds );
4826  }
4827  } elseif ( $this->trxStatus > self::STATUS_TRX_ERROR ) {
4828  // Put the transaction into an error state if it's not already in one
4829  $trxError = new DBUnexpectedError(
4830  $this,
4831  "Uncancelable atomic section canceled (got $fname)"
4832  );
4833  $this->setTransactionError( $trxError );
4834  }
4835  } finally {
4836  // Fix up callbacks owned by the sections that were just cancelled.
4837  // All callbacks should have an owner that is present in trxAtomicLevels.
4838  $this->modifyCallbacksForCancel( $excisedIds, $newTopSection );
4839  }
4840 
4841  $this->affectedRowCount = 0; // for the sake of consistency
4842 
4843  $this->completeCriticalSection( __METHOD__, $cs );
4844 
4845  if ( $runPostRollbackCallbacks ) {
4847  }
4848  }
4849 
4850  final public function doAtomicSection(
4851  $fname,
4852  callable $callback,
4853  $cancelable = self::ATOMIC_NOT_CANCELABLE
4854  ) {
4855  $sectionId = $this->startAtomic( $fname, $cancelable );
4856  try {
4857  $res = $callback( $this, $fname );
4858  } catch ( Throwable $e ) {
4859  // Avoid confusing error reporting during critical section errors
4860  if ( !$this->csmError ) {
4861  $this->cancelAtomic( $fname, $sectionId );
4862  }
4863 
4864  throw $e;
4865  }
4866  $this->endAtomic( $fname );
4867 
4868  return $res;
4869  }
4870 
4871  final public function begin( $fname = __METHOD__, $mode = self::TRANSACTION_EXPLICIT ) {
4872  static $modes = [ self::TRANSACTION_EXPLICIT, self::TRANSACTION_INTERNAL ];
4873  if ( !in_array( $mode, $modes, true ) ) {
4874  throw new DBUnexpectedError( $this, "$fname: invalid mode parameter '$mode'" );
4875  }
4876 
4877  // Protect against mismatched atomic section, transaction nesting, and snapshot loss
4878  if ( $this->trxLevel() ) {
4879  if ( $this->trxAtomicLevels ) {
4880  $levels = $this->flatAtomicSectionList();
4881  $msg = "$fname: got explicit BEGIN while atomic section(s) $levels are open";
4882  throw new DBUnexpectedError( $this, $msg );
4883  } elseif ( !$this->trxAutomatic ) {
4884  $msg = "$fname: explicit transaction already active (from {$this->trxFname})";
4885  throw new DBUnexpectedError( $this, $msg );
4886  } else {
4887  $msg = "$fname: implicit transaction already active (from {$this->trxFname})";
4888  throw new DBUnexpectedError( $this, $msg );
4889  }
4890  } elseif ( $this->getFlag( self::DBO_TRX ) && $mode !== self::TRANSACTION_INTERNAL ) {
4891  $msg = "$fname: implicit transaction expected (DBO_TRX set)";
4892  throw new DBUnexpectedError( $this, $msg );
4893  }
4894 
4895  $this->assertHasConnectionHandle();
4896 
4897  $cs = $this->commenceCriticalSection( __METHOD__ );
4898  try {
4899  $this->doBegin( $fname );
4900  } catch ( DBError $e ) {
4901  $this->completeCriticalSection( __METHOD__, $cs );
4902  throw $e;
4903  }
4904  static $nextTrxId;
4905  $nextTrxId = ( $nextTrxId !== null ? $nextTrxId++ : mt_rand() ) % 0xffff;
4906  $this->trxId = sprintf( '%06x', mt_rand( 0, 0xffffff ) ) . sprintf( '%04x', $nextTrxId );
4907  $this->trxStatus = self::STATUS_TRX_OK;
4908  $this->trxStatusIgnoredCause = null;
4909  $this->trxAtomicCounter = 0;
4910  $this->trxTimestamp = microtime( true );
4911  $this->trxFname = $fname;
4912  $this->trxDoneWrites = false;
4913  $this->trxAutomaticAtomic = false;
4914  $this->trxAtomicLevels = [];
4915  $this->trxWriteDuration = 0.0;
4916  $this->trxWriteQueryCount = 0;
4917  $this->trxWriteAffectedRows = 0;
4918  $this->trxWriteAdjDuration = 0.0;
4919  $this->trxWriteAdjQueryCount = 0;
4920  $this->trxWriteCallers = [];
4921  // With REPEATABLE-READ isolation, the first SELECT establishes the read snapshot,
4922  // so get the replication lag estimate before any transaction SELECT queries come in.
4923  // This way, the lag estimate reflects what will actually be read. Also, if heartbeat
4924  // tables are used, this avoids counting snapshot lag as part of replication lag.
4925  $this->trxReplicaLagStatus = null; // clear cached value first
4926  $this->trxReplicaLagStatus = $this->getApproximateLagStatus();
4927  // T147697: make explicitTrxActive() return true until begin() finishes. This way,
4928  // no caller triggered by getApproximateLagStatus() will think its OK to muck around
4929  // with the transaction just because startAtomic() has not yet finished updating the
4930  // tracking fields (e.g. trxAtomicLevels).
4931  $this->trxAutomatic = ( $mode === self::TRANSACTION_INTERNAL );
4932  $this->completeCriticalSection( __METHOD__, $cs );
4933  }
4934 
4943  protected function doBegin( $fname ) {
4944  $this->query( 'BEGIN', $fname, self::QUERY_CHANGE_TRX );
4945  }
4946 
4947  final public function commit( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) {
4948  static $modes = [ self::FLUSHING_ONE, self::FLUSHING_ALL_PEERS, self::FLUSHING_INTERNAL ];
4949  if ( !in_array( $flush, $modes, true ) ) {
4950  throw new DBUnexpectedError( $this, "$fname: invalid flush parameter '$flush'" );
4951  }
4952 
4953  if ( $this->trxLevel() && $this->trxAtomicLevels ) {
4954  // There are still atomic sections open; this cannot be ignored
4955  $levels = $this->flatAtomicSectionList();
4956  throw new DBUnexpectedError(
4957  $this,
4958  "$fname: got COMMIT while atomic sections $levels are still open"
4959  );
4960  }
4961 
4962  if ( $flush === self::FLUSHING_INTERNAL || $flush === self::FLUSHING_ALL_PEERS ) {
4963  if ( !$this->trxLevel() ) {
4964  return; // nothing to do
4965  } elseif ( !$this->trxAutomatic ) {
4966  throw new DBUnexpectedError(
4967  $this,
4968  "$fname: flushing an explicit transaction, getting out of sync"
4969  );
4970  }
4971  } elseif ( !$this->trxLevel() ) {
4972  $this->queryLogger->error(
4973  "$fname: no transaction to commit, something got out of sync",
4974  [ 'exception' => new RuntimeException() ]
4975  );
4976 
4977  return; // nothing to do
4978  } elseif ( $this->trxAutomatic ) {
4979  throw new DBUnexpectedError(
4980  $this,
4981  "$fname: expected mass commit of all peer transactions (DBO_TRX set)"
4982  );
4983  }
4984 
4985  $this->assertHasConnectionHandle();
4986 
4988  $writeTime = $this->pendingWriteQueryDuration( self::ESTIMATE_DB_APPLY );
4989 
4990  $cs = $this->commenceCriticalSection( __METHOD__ );
4991  try {
4992  $this->doCommit( $fname );
4993  } catch ( DBError $e ) {
4994  $this->completeCriticalSection( __METHOD__, $cs );
4995  throw $e;
4996  }
4997  $oldTrxId = $this->consumeTrxId();
4998  $this->trxStatus = self::STATUS_TRX_NONE;
4999  if ( $this->trxDoneWrites ) {
5000  $this->lastWriteTime = microtime( true );
5001  $this->trxProfiler->transactionWritingOut(
5002  $this->getServerName(),
5003  $this->getDomainID(),
5004  $oldTrxId,
5005  $writeTime,
5006  $this->trxWriteAffectedRows
5007  );
5008  }
5009  // With FLUSHING_ALL_PEERS, callbacks will run when requested by a dedicated phase
5010  // within LoadBalancer. With FLUSHING_INTERNAL, callbacks will run when requested by
5011  // the Database caller during a safe point. This avoids isolation and recursion issues.
5012  if ( $flush === self::FLUSHING_ONE ) {
5014  }
5015  $this->completeCriticalSection( __METHOD__, $cs );
5016  }
5017 
5026  protected function doCommit( $fname ) {
5027  if ( $this->trxLevel() ) {
5028  $this->query( 'COMMIT', $fname, self::QUERY_CHANGE_TRX );
5029  }
5030  }
5031 
5032  final public function rollback( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) {
5033  if (
5034  $flush !== self::FLUSHING_INTERNAL &&
5035  $flush !== self::FLUSHING_ALL_PEERS &&
5036  $this->getFlag( self::DBO_TRX )
5037  ) {
5038  throw new DBUnexpectedError(
5039  $this,
5040  "$fname: Expected mass rollback of all peer transactions (DBO_TRX set)"
5041  );
5042  }
5043 
5044  if ( !$this->trxLevel() ) {
5045  // Clear any commit-dependant callbacks left over from transaction rounds
5046  $this->trxPostCommitOrIdleCallbacks = [];
5047  $this->trxPreCommitOrIdleCallbacks = [];
5048 
5049  return;
5050  }
5051 
5052  $this->assertHasConnectionHandle();
5053 
5054  $cs = $this->commenceCriticalSection( __METHOD__ );
5055  $this->doRollback( $fname );
5056  $oldTrxId = $this->consumeTrxId();
5057  $this->trxStatus = self::STATUS_TRX_NONE;
5058  $this->trxAtomicLevels = [];
5059  // Clear callbacks that depend on transaction or transaction round commit
5060  $this->trxPostCommitOrIdleCallbacks = [];
5061  $this->trxPreCommitOrIdleCallbacks = [];
5062  // Estimate the RTT via a query now that trxStatus is OK
5063  $writeTime = $this->pingAndCalculateLastTrxApplyTime();
5064  if ( $this->trxDoneWrites ) {
5065  $this->trxProfiler->transactionWritingOut(
5066  $this->getServerName(),
5067  $this->getDomainID(),
5068  $oldTrxId,
5069  $writeTime,
5070  $this->trxWriteAffectedRows
5071  );
5072  }
5073  // With FLUSHING_ALL_PEERS, callbacks will run when requested by a dedicated phase
5074  // within LoadBalancer. With FLUSHING_INTERNAL, callbacks will run when requested by
5075  // the Database caller during a safe point. This avoids isolation and recursion issues.
5076  if ( $flush === self::FLUSHING_ONE ) {
5078  }
5079  $this->completeCriticalSection( __METHOD__, $cs );
5080  }
5081 
5090  protected function doRollback( $fname ) {
5091  if ( $this->trxLevel() ) {
5092  # Disconnects cause rollback anyway, so ignore those errors
5093  $this->query( 'ROLLBACK', $fname, self::QUERY_SILENCE_ERRORS | self::QUERY_CHANGE_TRX );
5094  }
5095  }
5096 
5097  public function flushSnapshot( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) {
5098  if ( $this->explicitTrxActive() ) {
5099  // Committing this transaction would break callers that assume it is still open
5100  throw new DBUnexpectedError(
5101  $this,
5102  "$fname: Cannot flush snapshot; " .
5103  "explicit transaction '{$this->trxFname}' is still open"
5104  );
5105  } elseif ( $this->writesOrCallbacksPending() ) {
5106  // This only flushes transactions to clear snapshots, not to write data
5107  $fnames = implode( ', ', $this->pendingWriteAndCallbackCallers() );
5108  throw new DBUnexpectedError(
5109  $this,
5110  "$fname: Cannot flush snapshot; " .
5111  "writes from transaction {$this->trxFname} are still pending ($fnames)"
5112  );
5113  } elseif (
5114  $this->trxLevel() &&
5115  $this->getTransactionRoundId() &&
5116  $flush !== self::FLUSHING_INTERNAL &&
5117  $flush !== self::FLUSHING_ALL_PEERS
5118  ) {
5119  $this->queryLogger->warning(
5120  "$fname: Expected mass snapshot flush of all peer transactions " .
5121  "in the explicit transactions round '{$this->getTransactionRoundId()}'",
5122  [ 'exception' => new RuntimeException() ]
5123  );
5124  }
5125 
5126  $this->commit( $fname, self::FLUSHING_INTERNAL );
5127  }
5128 
5129  public function explicitTrxActive() {
5130  return $this->trxLevel() && ( $this->trxAtomicLevels || !$this->trxAutomatic );
5131  }
5132 
5137  public function duplicateTableStructure(
5138  $oldName,
5139  $newName,
5140  $temporary = false,
5141  $fname = __METHOD__
5142  ) {
5143  throw new RuntimeException( __METHOD__ . ' is not implemented in descendant class' );
5144  }
5145 
5150  public function listTables( $prefix = null, $fname = __METHOD__ ) {
5151  throw new RuntimeException( __METHOD__ . ' is not implemented in descendant class' );
5152  }
5153 
5158  public function listViews( $prefix = null, $fname = __METHOD__ ) {
5159  throw new RuntimeException( __METHOD__ . ' is not implemented in descendant class' );
5160  }
5161 
5166  public function timestamp( $ts = 0 ) {
5167  $t = new ConvertibleTimestamp( $ts );
5168  // Let errors bubble up to avoid putting garbage in the DB
5169  return $t->getTimestamp( TS_MW );
5170  }
5171 
5172  public function timestampOrNull( $ts = null ) {
5173  if ( $ts === null ) {
5174  return null;
5175  } else {
5176  return $this->timestamp( $ts );
5177  }
5178  }
5179 
5180  public function affectedRows() {
5181  return $this->affectedRowCount ?? $this->fetchAffectedRowCount();
5182  }
5183 
5187  abstract protected function fetchAffectedRowCount();
5188 
5189  public function ping( &$rtt = null ) {
5190  // Avoid hitting the server if it was hit recently
5191  if ( $this->isOpen() && ( microtime( true ) - $this->lastPing ) < self::PING_TTL ) {
5192  if ( !func_num_args() || $this->lastRoundTripEstimate > 0 ) {
5194  return true; // don't care about $rtt
5195  }
5196  }
5197 
5198  // This will reconnect if possible or return false if not
5199  $flags = self::QUERY_IGNORE_DBO_TRX | self::QUERY_SILENCE_ERRORS | self::QUERY_CHANGE_NONE;
5200  $ok = ( $this->query( self::PING_QUERY, __METHOD__, $flags ) !== false );
5201  if ( $ok ) {
5203  }
5204 
5205  return $ok;
5206  }
5207 
5214  protected function replaceLostConnection( $fname ) {
5215  $this->closeConnection();
5216  $this->conn = null;
5217 
5218  $this->handleSessionLossPreconnect();
5219 
5220  try {
5221  $this->open(
5222  $this->connectionParams[self::CONN_HOST],
5223  $this->connectionParams[self::CONN_USER],
5224  $this->connectionParams[self::CONN_PASSWORD],
5225  $this->currentDomain->getDatabase(),
5226  $this->currentDomain->getSchema(),
5227  $this->tablePrefix()
5228  );
5229  $this->lastPing = microtime( true );
5230  $ok = true;
5231 
5232  $this->connLogger->warning(
5233  $fname . ': lost connection to {db_server}; reconnected',
5234  $this->getLogContext( [ 'exception' => new RuntimeException() ] )
5235  );
5236  } catch ( DBConnectionError $e ) {
5237  $ok = false;
5238 
5239  $this->connLogger->error(
5240  $fname . ': lost connection to {db_server} permanently',
5241  $this->getLogContext( [ 'exception' => new RuntimeException() ] )
5242  );
5243  }
5244 
5246 
5247  return $ok;
5248  }
5249 
5250  public function getSessionLagStatus() {
5251  return $this->getRecordedTransactionLagStatus() ?: $this->getApproximateLagStatus();
5252  }
5253 
5267  final protected function getRecordedTransactionLagStatus() {
5268  return $this->trxLevel() ? $this->trxReplicaLagStatus : null;
5269  }
5270 
5280  protected function getApproximateLagStatus() {
5281  if ( $this->topologyRole === self::ROLE_STREAMING_REPLICA ) {
5282  // Avoid exceptions as this is used internally in critical sections
5283  try {
5284  $lag = $this->getLag();
5285  } catch ( DBError $e ) {
5286  $lag = false;
5287  }
5288  } else {
5289  $lag = 0;
5290  }
5291 
5292  return [ 'lag' => $lag, 'since' => microtime( true ) ];
5293  }
5294 
5317  public static function getCacheSetOptions( ?IDatabase ...$dbs ) {
5318  $res = [ 'lag' => 0, 'since' => INF, 'pending' => false ];
5319 
5320  foreach ( func_get_args() as $db ) {
5321  if ( $db instanceof IDatabase ) {
5322  $status = $db->getSessionLagStatus();
5323 
5324  if ( $status['lag'] === false ) {
5325  $res['lag'] = false;
5326  } elseif ( $res['lag'] !== false ) {
5327  $res['lag'] = max( $res['lag'], $status['lag'] );
5328  }
5329  $res['since'] = min( $res['since'], $status['since'] );
5330  $res['pending'] = $res['pending'] ?: $db->writesPending();
5331  }
5332  }
5333 
5334  return $res;
5335  }
5336 
5337  public function getLag() {
5338  if ( $this->topologyRole === self::ROLE_STREAMING_MASTER ) {
5339  return 0; // this is the primary DB
5340  } elseif ( $this->topologyRole === self::ROLE_STATIC_CLONE ) {
5341  return 0; // static dataset
5342  }
5343 
5344  return $this->doGetLag();
5345  }
5346 
5358  protected function doGetLag() {
5359  return 0;
5360  }
5361 
5366  public function encodeBlob( $b ) {
5367  return $b;
5368  }
5369 
5374  public function decodeBlob( $b ) {
5375  if ( $b instanceof Blob ) {
5376  $b = $b->fetch();
5377  }
5378  return $b;
5379  }
5380 
5385  public function setSessionOptions( array $options ) {
5386  }
5387 
5388  public function sourceFile(
5389  $filename,
5390  callable $lineCallback = null,
5391  callable $resultCallback = null,
5392  $fname = false,
5393  callable $inputCallback = null
5394  ) {
5395  AtEase::suppressWarnings();
5396  $fp = fopen( $filename, 'r' );
5397  AtEase::restoreWarnings();
5398 
5399  if ( $fp === false ) {
5400  throw new RuntimeException( "Could not open \"{$filename}\"" );
5401  }
5402 
5403  if ( !$fname ) {
5404  $fname = __METHOD__ . "( $filename )";
5405  }
5406 
5407  try {
5408  $error = $this->sourceStream(
5409  $fp,
5410  $lineCallback,
5411  $resultCallback,
5412  $fname,
5413  $inputCallback
5414  );
5415  } finally {
5416  fclose( $fp );
5417  }
5418 
5419  return $error;
5420  }
5421 
5422  public function setSchemaVars( $vars ) {
5423  $this->schemaVars = is_array( $vars ) ? $vars : null;
5424  }
5425 
5426  public function sourceStream(
5427  $fp,
5428  callable $lineCallback = null,
5429  callable $resultCallback = null,
5430  $fname = __METHOD__,
5431  callable $inputCallback = null
5432  ) {
5433  $delimiterReset = new ScopedCallback(
5434  function ( $delimiter ) {
5435  $this->delimiter = $delimiter;
5436  },
5437  [ $this->delimiter ]
5438  );
5439  $cmd = '';
5440 
5441  while ( !feof( $fp ) ) {
5442  if ( $lineCallback ) {
5443  call_user_func( $lineCallback );
5444  }
5445 
5446  $line = trim( fgets( $fp ) );
5447 
5448  if ( $line == '' ) {
5449  continue;
5450  }
5451 
5452  if ( $line[0] == '-' && $line[1] == '-' ) {
5453  continue;
5454  }
5455 
5456  if ( $cmd != '' ) {
5457  $cmd .= ' ';
5458  }
5459 
5460  $done = $this->streamStatementEnd( $cmd, $line );
5461 
5462  $cmd .= "$line\n";
5463 
5464  if ( $done || feof( $fp ) ) {
5465  $cmd = $this->replaceVars( $cmd );
5466 
5467  if ( $inputCallback ) {
5468  $callbackResult = $inputCallback( $cmd );
5469 
5470  if ( is_string( $callbackResult ) || !$callbackResult ) {
5471  $cmd = $callbackResult;
5472  }
5473  }
5474 
5475  if ( $cmd ) {
5476  $res = $this->query( $cmd, $fname );
5477 
5478  if ( $resultCallback ) {
5479  $resultCallback( $res, $this );
5480  }
5481 
5482  if ( $res === false ) {
5483  $err = $this->lastError();
5484 
5485  return "Query \"{$cmd}\" failed with error code \"$err\".\n";
5486  }
5487  }
5488  $cmd = '';
5489  }
5490  }
5491 
5492  ScopedCallback::consume( $delimiterReset );
5493  return true;
5494  }
5495 
5504  public function streamStatementEnd( &$sql, &$newLine ) {
5505  if ( $this->delimiter ) {
5506  $prev = $newLine;
5507  $newLine = preg_replace(
5508  '/' . preg_quote( $this->delimiter, '/' ) . '$/',
5509  '',
5510  $newLine
5511  );
5512  if ( $newLine != $prev ) {
5513  return true;
5514  }
5515  }
5516 
5517  return false;
5518  }
5519 
5541  protected function replaceVars( $ins ) {
5542  $vars = $this->getSchemaVars();
5543  return preg_replace_callback(
5544  '!
5545  /\* (\$wgDBprefix|[_i]) \*/ (\w*) | # 1-2. tableName, indexName
5546  \'\{\$ (\w+) }\' | # 3. addQuotes
5547  `\{\$ (\w+) }` | # 4. addIdentifierQuotes
5548  /\*\$ (\w+) \*/ # 5. leave unencoded
5549  !x',
5550  function ( $m ) use ( $vars ) {
5551  // Note: Because of <https://bugs.php.net/bug.php?id=51881>,
5552  // check for both nonexistent keys *and* the empty string.
5553  if ( isset( $m[1] ) && $m[1] !== '' ) {
5554  if ( $m[1] === 'i' ) {
5555  return $this->indexName( $m[2] );
5556  } else {
5557  return $this->tableName( $m[2] );
5558  }
5559  } elseif ( isset( $m[3] ) && $m[3] !== '' && array_key_exists( $m[3], $vars ) ) {
5560  return $this->addQuotes( $vars[$m[3]] );
5561  } elseif ( isset( $m[4] ) && $m[4] !== '' && array_key_exists( $m[4], $vars ) ) {
5562  return $this->addIdentifierQuotes( $vars[$m[4]] );
5563  } elseif ( isset( $m[5] ) && $m[5] !== '' && array_key_exists( $m[5], $vars ) ) {
5564  return $vars[$m[5]];
5565  } else {
5566  return $m[0];
5567  }
5568  },
5569  $ins
5570  );
5571  }
5572 
5579  protected function getSchemaVars() {
5580  return $this->schemaVars ?? $this->getDefaultSchemaVars();
5581  }
5582 
5592  protected function getDefaultSchemaVars() {
5593  return [];
5594  }
5595 
5599  public function lockIsFree( $lockName, $method ) {
5600  // RDBMs methods for checking named locks may or may not count this thread itself.
5601  // In MySQL, IS_FREE_LOCK() returns 0 if the thread already has the lock. This is
5602  // the behavior chosen by the interface for this method.
5603  if ( isset( $this->sessionNamedLocks[$lockName] ) ) {
5604  $lockIsFree = false;
5605  } else {
5606  $lockIsFree = $this->doLockIsFree( $lockName, $method );
5607  }
5608 
5609  return $lockIsFree;
5610  }
5611 
5621  protected function doLockIsFree( string $lockName, string $method ) {
5622  return true; // not implemented
5623  }
5624 
5628  public function lock( $lockName, $method, $timeout = 5, $flags = 0 ) {
5629  $lockTsUnix = $this->doLock( $lockName, $method, $timeout );
5630  if ( $lockTsUnix !== null ) {
5631  $locked = true;
5632  $this->sessionNamedLocks[$lockName] = $lockTsUnix;
5633  } else {
5634  $locked = false;
5635  $this->queryLogger->info( __METHOD__ . " failed to acquire lock '{lockname}'",
5636  [ 'lockname' => $lockName ] );
5637  }
5638 
5639  if ( $this->fieldHasBit( $flags, self::LOCK_TIMESTAMP ) ) {
5640  return $lockTsUnix;
5641  } else {
5642  return $locked;
5643  }
5644  }
5645 
5656  protected function doLock( string $lockName, string $method, int $timeout ) {
5657  return microtime( true ); // not implemented
5658  }
5659 
5663  public function unlock( $lockName, $method ) {
5664  $released = $this->doUnlock( $lockName, $method );
5665  if ( $released ) {
5666  unset( $this->sessionNamedLocks[$lockName] );
5667  } else {
5668  $this->queryLogger->warning( __METHOD__ . " failed to release lock '$lockName'\n" );
5669  }
5670 
5671  return $released;
5672  }
5673 
5683  protected function doUnlock( string $lockName, string $method ) {
5684  return true; // not implemented
5685  }
5686 
5687  public function getScopedLockAndFlush( $lockKey, $fname, $timeout ) {
5688  if ( $this->writesOrCallbacksPending() ) {
5689  // This only flushes transactions to clear snapshots, not to write data
5690  $fnames = implode( ', ', $this->pendingWriteAndCallbackCallers() );
5691  throw new DBUnexpectedError(
5692  $this,
5693  "$fname: Cannot flush pre-lock snapshot; " .
5694  "writes from transaction {$this->trxFname} are still pending ($fnames)"
5695  );
5696  }
5697 
5698  if ( !$this->lock( $lockKey, $fname, $timeout ) ) {
5699  return null;
5700  }
5701 
5702  $unlocker = new ScopedCallback( function () use ( $lockKey, $fname ) {
5703  if ( $this->trxLevel() ) {
5704  // There is a good chance an exception was thrown, causing any early return
5705  // from the caller. Let any error handler get a chance to issue rollback().
5706  // If there isn't one, let the error bubble up and trigger server-side rollback.
5707  $this->onTransactionResolution(
5708  function () use ( $lockKey, $fname ) {
5709  $this->unlock( $lockKey, $fname );
5710  },
5711  $fname
5712  );
5713  } else {
5714  $this->unlock( $lockKey, $fname );
5715  }
5716  } );
5717 
5718  $this->commit( $fname, self::FLUSHING_INTERNAL );
5719 
5720  return $unlocker;
5721  }
5722 
5727  public function namedLocksEnqueue() {
5728  return false;
5729  }
5730 
5732  return true;
5733  }
5734 
5735  final public function lockTables( array $read, array $write, $method ) {
5736  if ( $this->writesOrCallbacksPending() ) {
5737  throw new DBUnexpectedError( $this, "Transaction writes or callbacks still pending" );
5738  }
5739 
5740  if ( $this->tableLocksHaveTransactionScope() ) {
5741  $this->startAtomic( $method );
5742  }
5743 
5744  return $this->doLockTables( $read, $write, $method );
5745  }
5746 
5756  protected function doLockTables( array $read, array $write, $method ) {
5757  return true;
5758  }
5759 
5760  final public function unlockTables( $method ) {
5761  if ( $this->tableLocksHaveTransactionScope() ) {
5762  $this->endAtomic( $method );
5763 
5764  return true; // locks released on COMMIT/ROLLBACK
5765  }
5766 
5767  return $this->doUnlockTables( $method );
5768  }
5769 
5777  protected function doUnlockTables( $method ) {
5778  return true;
5779  }
5780 
5781  public function dropTable( $table, $fname = __METHOD__ ) {
5782  if ( !$this->tableExists( $table, $fname ) ) {
5783  return false;
5784  }
5785 
5786  $this->doDropTable( $table, $fname );
5787 
5788  return true;
5789  }
5790 
5797  protected function doDropTable( $table, $fname ) {
5798  // https://mariadb.com/kb/en/drop-table/
5799  // https://dev.mysql.com/doc/refman/8.0/en/drop-table.html
5800  // https://www.postgresql.org/docs/9.2/sql-truncate.html
5801  $sql = "DROP TABLE " . $this->tableName( $table ) . " CASCADE";
5802  $this->query( $sql, $fname, self::QUERY_CHANGE_SCHEMA );
5803  }
5804 
5805  public function truncate( $tables, $fname = __METHOD__ ) {
5806  $tables = is_array( $tables ) ? $tables : [ $tables ];
5807 
5808  $tablesTruncate = [];
5809  foreach ( $tables as $table ) {
5810  // Skip TEMPORARY tables with no writes nor sequence updates detected.
5811  // This mostly is an optimization for integration testing.
5812  if ( !$this->isPristineTemporaryTable( $table ) ) {
5813  $tablesTruncate[] = $table;
5814  }
5815  }
5816 
5817  if ( $tablesTruncate ) {
5818  $this->doTruncate( $tablesTruncate, $fname );
5819  }
5820  }
5821 
5828  protected function doTruncate( array $tables, $fname ) {
5829  foreach ( $tables as $table ) {
5830  $sql = "TRUNCATE TABLE " . $this->tableName( $table );
5831  $this->query( $sql, $fname, self::QUERY_CHANGE_SCHEMA );
5832  }
5833  }
5834 
5839  public function getInfinity() {
5840  return 'infinity';
5841  }
5842 
5843  public function encodeExpiry( $expiry ) {
5844  return ( $expiry == '' || $expiry == 'infinity' || $expiry == $this->getInfinity() )
5845  ? $this->getInfinity()
5846  : $this->timestamp( $expiry );
5847  }
5848 
5849  public function decodeExpiry( $expiry, $format = TS_MW ) {
5850  if ( $expiry == '' || $expiry == 'infinity' || $expiry == $this->getInfinity() ) {
5851  return 'infinity';
5852  }
5853 
5854  return ConvertibleTimestamp::convert( $format, $expiry );
5855  }
5856 
5861  public function setBigSelects( $value = true ) {
5862  // no-op
5863  }
5864 
5865  public function isReadOnly() {
5866  return ( $this->getReadOnlyReason() !== false );
5867  }
5868 
5872  protected function getReadOnlyReason() {
5873  if ( $this->topologyRole === self::ROLE_STREAMING_REPLICA ) {
5874  return [ 'Server is configured as a read-only replica database.', 'role' ];
5875  } elseif ( $this->topologyRole === self::ROLE_STATIC_CLONE ) {
5876  return [ 'Server is configured as a read-only static clone database.', 'role' ];
5877  }
5878 
5879  $reason = $this->getLBInfo( self::LB_READ_ONLY_REASON );
5880  if ( is_string( $reason ) ) {
5881  return [ $reason, 'lb' ];
5882  }
5883 
5884  return false;
5885  }
5886 
5891  public function setTableAliases( array $aliases ) {
5892  $this->tableAliases = $aliases;
5893  }
5894 
5899  public function setIndexAliases( array $aliases ) {
5900  $this->indexAliases = $aliases;
5901  }
5902 
5909  final protected function fieldHasBit( int $flags, int $bit ) {
5910  return ( ( $flags & $bit ) === $bit );
5911  }
5912 
5925  protected function getBindingHandle() {
5926  if ( !$this->conn ) {
5927  throw new DBUnexpectedError(
5928  $this,
5929  'DB connection was already closed or the connection dropped'
5930  );
5931  }
5932 
5933  return $this->conn;
5934  }
5935 
5941  private function setTransactionError( Throwable $trxError ) {
5942  if ( $this->trxStatus > self::STATUS_TRX_ERROR ) {
5943  $this->trxStatus = self::STATUS_TRX_ERROR;
5944  $this->trxStatusCause = $trxError;
5945  }
5946  }
5947 
5988  protected function commenceCriticalSection( string $fname ) {
5989  if ( $this->csmError ) {
5990  throw new DBUnexpectedError(
5991  $this,
5992  "Cannot execute $fname critical section while session state is out of sync.\n\n" .
5993  $this->csmError->getMessage() . "\n" .
5994  $this->csmError->getTraceAsString()
5995  );
5996  }
5997 
5998  if ( $this->csmId ) {
5999  $csm = null; // fold into the outer critical section
6000  } elseif ( $this->csProvider ) {
6001  $csm = $this->csProvider->scopedEnter(
6002  $fname,
6003  null, // emergency limit (default)
6004  null, // emergency callback (default)
6005  function () use ( $fname ) {
6006  // Mark a critical section as having been aborted by an error
6007  $e = new RuntimeException( "A critical section from {$fname} has failed" );
6008  $this->csmError = $e;
6009  $this->csmId = null;
6010  }
6011  );
6012  $this->csmId = $csm->getId();
6013  $this->csmFname = $fname;
6014  } else {
6015  $csm = null; // not supported
6016  }
6017 
6018  return $csm;
6019  }
6020 
6031  protected function completeCriticalSection(
6032  string $fname,
6033  ?CriticalSectionScope $csm,
6034  Throwable $trxError = null
6035  ) {
6036  if ( $csm !== null ) {
6037  if ( $this->csmId === null ) {
6038  throw new LogicException( "$fname critical section is not active" );
6039  } elseif ( $csm->getId() !== $this->csmId ) {
6040  throw new LogicException(
6041  "$fname critical section is not the active ({$this->csmFname}) one"
6042  );
6043  }
6044 
6045  $csm->exit();
6046  $this->csmId = null;
6047  }
6048 
6049  if ( $trxError ) {
6050  $this->setTransactionError( $trxError );
6051  }
6052  }
6053 
6054  public function __toString() {
6055  // spl_object_id is PHP >= 7.2
6056  $id = function_exists( 'spl_object_id' )
6057  ? spl_object_id( $this )
6058  : spl_object_hash( $this );
6059 
6060  $description = $this->getType() . ' object #' . $id;
6061  if ( is_resource( $this->conn ) ) {
6062  $description .= ' (' . (string)$this->conn . ')'; // "resource id #<ID>"
6063  } elseif ( is_object( $this->conn ) ) {
6064  // spl_object_id is PHP >= 7.2
6065  $handleId = function_exists( 'spl_object_id' )
6066  ? spl_object_id( $this->conn )
6067  : spl_object_hash( $this->conn );
6068  $description .= " (handle id #$handleId)";
6069  }
6070 
6071  return $description;
6072  }
6073 
6078  public function __clone() {
6079  $this->connLogger->warning(
6080  "Cloning " . static::class . " is not recommended; forking connection",
6081  [ 'exception' => new RuntimeException() ]
6082  );
6083 
6084  if ( $this->isOpen() ) {
6085  // Open a new connection resource without messing with the old one
6086  $this->conn = null;
6087  $this->trxEndCallbacks = []; // don't copy
6088  $this->trxSectionCancelCallbacks = []; // don't copy
6089  $this->handleSessionLossPreconnect(); // no trx or locks anymore
6090  $this->open(
6091  $this->connectionParams[self::CONN_HOST],
6092  $this->connectionParams[self::CONN_USER],
6093  $this->connectionParams[self::CONN_PASSWORD],
6094  $this->currentDomain->getDatabase(),
6095  $this->currentDomain->getSchema(),
6096  $this->tablePrefix()
6097  );
6098  $this->lastPing = microtime( true );
6099  }
6100  }
6101 
6108  public function __sleep() {
6109  throw new RuntimeException( 'Database serialization may cause problems, since ' .
6110  'the connection is not restored on wakeup' );
6111  }
6112 
6116  public function __destruct() {
6117  if ( $this->trxLevel() && $this->trxDoneWrites ) {
6118  trigger_error( "Uncommitted DB writes (transaction from {$this->trxFname})" );
6119  }
6120 
6121  $danglingWriters = $this->pendingWriteAndCallbackCallers();
6122  if ( $danglingWriters ) {
6123  $fnames = implode( ', ', $danglingWriters );
6124  trigger_error( "DB transaction writes or callbacks still pending ($fnames)" );
6125  }
6126 
6127  if ( $this->conn ) {
6128  // Avoid connection leaks. Normally, resources close at script completion.
6129  // The connection might already be closed in PHP by now, so suppress warnings.
6130  AtEase::suppressWarnings();
6131  $this->closeConnection();
6132  AtEase::restoreWarnings();
6133  $this->conn = null;
6134  }
6135  }
6136 }
6137 
6141 class_alias( Database::class, 'DatabaseBase' );
6142 
6146 class_alias( Database::class, 'Database' );
Wikimedia\Rdbms\Database\CONN_INITIAL_TABLE_PREFIX
const CONN_INITIAL_TABLE_PREFIX
Table prefix to use on initial connection.
Definition: Database.php:277
Wikimedia\Rdbms\Database\implicitOrderby
implicitOrderby()
Returns true if this database does an implicit order by when the column has an index For example: SEL...
Definition: Database.php:694
LIST_OR
const LIST_OR
Definition: Defines.php:46
Wikimedia\Rdbms\Database\$schemaVars
array null $schemaVars
Current variables use for schema element placeholders.
Definition: Database.php:116
Wikimedia\Rdbms\Database\tablePrefix
tablePrefix( $prefix=null)
Get/set the table prefix.
Definition: Database.php:610
Wikimedia\Rdbms\Database\$sessionNamedLocks
array< string, float > $sessionNamedLocks
Map of (name => UNIX timestamp) for locks obtained via lock()
Definition: Database.php:124
Wikimedia\Rdbms\Database\$serverName
string null $serverName
Readable name or host/IP of the database server.
Definition: Database.php:89
Wikimedia\Rdbms\Database\getLastPHPError
getLastPHPError()
Definition: Database.php:925
Wikimedia\Rdbms\Database\consumeTrxId
consumeTrxId()
Reset the application-side transaction ID and return the old one.
Definition: Database.php:1727
Wikimedia\Rdbms\Database\makeKeyCollisionCondition
makeKeyCollisionCondition(array $rows, array $uniqueKey)
Build an SQL condition to find rows with matching key values to those in $rows.
Definition: Database.php:3599
Wikimedia\Rdbms\Database\setSessionOptions
setSessionOptions(array $options)
Override database's default behavior.$options include: 'connTimeout' : Set the connection timeout val...
Definition: Database.php:5385
Wikimedia\Rdbms\Database
Relational database abstraction object.
Definition: Database.php:52
Wikimedia\Rdbms\Database\limitResult
limitResult( $sql, $limit, $offset=false)
Construct a LIMIT query with optional offset.The SQL should be adjusted so that only the first $limit...
Definition: Database.php:3927
Wikimedia\Rdbms\Database\$trxDoneWrites
bool $trxDoneWrites
Whether possible write queries were done in the last transaction started.
Definition: Database.php:145
Wikimedia\Rdbms\Database\completeCriticalSection
completeCriticalSection(string $fname, ?CriticalSectionScope $csm, Throwable $trxError=null)
Demark the completion of a critical section of session/transaction state changes.
Definition: Database.php:6031
Wikimedia\Rdbms\Database\$trxEndCallbacksSuppressed
bool $trxEndCallbacksSuppressed
Whether to suppress triggering of transaction end callbacks.
Definition: Database.php:180
Wikimedia\Rdbms\Database\makeUpdateOptionsArray
makeUpdateOptionsArray( $options)
Make UPDATE options array for Database::makeUpdateOptions.
Definition: Database.php:2612
Wikimedia\Rdbms\Database\replaceLostConnection
replaceLostConnection( $fname)
Close any existing (dead) database connection and open a new connection.
Definition: Database.php:5214
Wikimedia\Rdbms\Database\$trxWriteAdjQueryCount
int $trxWriteAdjQueryCount
Number of write queries counted in trxWriteAdjDuration.
Definition: Database.php:165
Wikimedia\Rdbms\Database\getBindingHandle
getBindingHandle()
Get the underlying binding connection handle.
Definition: Database.php:5925
LIST_NAMES
const LIST_NAMES
Definition: Defines.php:45
Wikimedia\Rdbms\Database\$lastPhpError
string bool $lastPhpError
Definition: Database.php:192
Wikimedia\Rdbms\Database\canRecoverFromDisconnect
canRecoverFromDisconnect( $sql, $priorWritesPending)
Determine whether it is safe to retry queries after a database connection is lost.
Definition: Database.php:1629
Wikimedia\Rdbms\Database\doInsert
doInsert( $table, array $rows, $fname)
Definition: Database.php:2530
Wikimedia\Rdbms\Database\buildGroupConcatField
buildGroupConcatField( $delim, $table, $field, $conds='', $join_conds=[])
Build a GROUP_CONCAT or equivalent statement for a query.This is useful for combining a field for sev...
Definition: Database.php:2869
Wikimedia\Rdbms\Database\doInitConnection
doInitConnection()
Actually connect to the database over the wire (or to local files)
Definition: Database.php:357
Wikimedia\Rdbms\Database\isQuotedIdentifier
isQuotedIdentifier( $name)
Returns if the given identifier looks quoted or not according to the database convention for quoting ...
Definition: Database.php:3459
Wikimedia\Rdbms\IDatabase\getServerVersion
getServerVersion()
A string describing the current software version, like from mysql_get_server_info()
Wikimedia\Rdbms\Database\upsert
upsert( $table, array $rows, $uniqueKeys, array $set, $fname=__METHOD__)
Upsert the given row(s) into a table.
Definition: Database.php:3636
Wikimedia\Rdbms\Database\fieldExists
fieldExists( $table, $field, $fname=__METHOD__)
Determines whether a field exists in a table.
Definition: Database.php:2471
Wikimedia\Rdbms\Database\deadlockLoop
deadlockLoop(... $args)
Perform a deadlock-prone transaction.This function invokes a callback function to perform a set of wr...
Definition: Database.php:4121
Wikimedia\Rdbms\Database\bitOr
bitOr( $fieldLeft, $fieldRight)
string
Definition: Database.php:2853
Wikimedia\Rdbms\Database\update
update( $table, $set, $conds, $fname=__METHOD__, $options=[])
Update all rows in a table that match a given condition.
Definition: Database.php:2637
Wikimedia\Rdbms\Database\selectRowCount
selectRowCount( $tables, $var=' *', $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Get the number of rows in dataset.
Definition: Database.php:2141
Wikimedia\Rdbms\Database\ignoreIndexClause
ignoreIndexClause( $index)
IGNORE INDEX clause.
Definition: Database.php:3546
Wikimedia\Rdbms\Database\$sessionDirtyTempTables
array $sessionDirtyTempTables
Map of (table name => 1) for current TEMPORARY tables.
Definition: Database.php:128
Wikimedia\Rdbms\Database\getTopologyRootPrimary
getTopologyRootPrimary()
Get the readable name of the sole root primary DB server for the replication topology.
Definition: Database.php:590
Wikimedia\Rdbms\Database\trxStatus
trxStatus()
Definition: Database.php:606
Wikimedia\Rdbms\Database\fieldHasBit
fieldHasBit(int $flags, int $bit)
Definition: Database.php:5909
Wikimedia\Rdbms\Database\listTables
listTables( $prefix=null, $fname=__METHOD__)
List all tables on the database.Only show tables with this prefix, e.g. mw_ Calling function name arr...
Definition: Database.php:5150
Wikimedia\Rdbms\Database\indexUnique
indexUnique( $table, $index, $fname=__METHOD__)
Determines if a given index is unique.Calling function namebool
Definition: Database.php:2496
HashBagOStuff
Simple store for keeping values in an associative array for the current process.
Definition: HashBagOStuff.php:32
Wikimedia\Rdbms\Database\updateTrxWriteQueryTime
updateTrxWriteQueryTime( $sql, $runtime, $affected)
Update the estimated run-time of a query, not counting large row lock times.
Definition: Database.php:1554
Wikimedia\Rdbms\Database\makeWhereFrom2d
makeWhereFrom2d( $data, $baseKey, $subKey)
Build a partial where clause from a 2-d array such as used for LinkBatch.
Definition: Database.php:2731
Wikimedia\Rdbms\Database\$queryLogger
LoggerInterface $queryLogger
Definition: Database.php:60
Wikimedia\Rdbms\DatabaseDomain\newFromId
static newFromId( $domain)
Definition: DatabaseDomain.php:77
Wikimedia\Rdbms\Database\encodeBlob
encodeBlob( $b)
Some DBMSs have a special format for inserting into blob fields, they don't allow simple quoted strin...
Definition: Database.php:5366
Wikimedia\Rdbms\Database\tableNamesN
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:3206
Wikimedia\Rdbms\Database\getDomainID
getDomainID()
Return the currently selected domain ID.
Definition: Database.php:855
Wikimedia\Rdbms\Database\getClass
static getClass( $dbType, $driver=null)
Definition: Database.php:510
Wikimedia\Rdbms\Database\pingAndCalculateLastTrxApplyTime
pingAndCalculateLastTrxApplyTime()
Definition: Database.php:753
Wikimedia\Rdbms\Database\$topologyRole
string $topologyRole
Replication topology role of the server; one of the class ROLE_* constants.
Definition: Database.php:95
Wikimedia\Rdbms\Database\doReplace
doReplace( $table, array $identityKey, array $rows, $fname)
Definition: Database.php:3571
Wikimedia\Rdbms\Database\assertHasConnectionHandle
assertHasConnectionHandle()
Make sure there is an open connection handle (alive or not)
Definition: Database.php:1044
Wikimedia\Rdbms\Database\onTransactionPreCommitOrIdle
onTransactionPreCommitOrIdle(callable $callback, $fname=__METHOD__)
Run a callback before the current transaction commits or now if there is none.
Definition: Database.php:4222
Wikimedia\Rdbms\Database\tableLocksHaveTransactionScope
tableLocksHaveTransactionScope()
Checks if table locks acquired by lockTables() are transaction-bound in their scope.
Definition: Database.php:5731
Wikimedia\Rdbms\Database\wasErrorReissuable
wasErrorReissuable()
Determines if the last query error was due to something outside of the query itself.
Definition: Database.php:4087
Wikimedia\Rdbms\Database\CONN_USER
const CONN_USER
Database server username to use on all connections.
Definition: Database.php:269
Wikimedia\Rdbms\Database\deleteJoin
deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds, $fname=__METHOD__)
DELETE where the condition is a join.MySQL overrides this to use a multi-table DELETE syntax,...
Definition: Database.php:3695
Wikimedia\Rdbms\Database\$trxPostCommitOrIdleCallbacks
array[] $trxPostCommitOrIdleCallbacks
List of (callable, method name, atomic section id)
Definition: Database.php:167
Wikimedia\Rdbms\Database\$csmFname
string null $csmFname
Last critical section caller name.
Definition: Database.php:199
Wikimedia\Rdbms\Database\CONN_INITIAL_DB
const CONN_INITIAL_DB
Database name to use on initial connection.
Definition: Database.php:273
Wikimedia\Rdbms\Database\setIndexAliases
setIndexAliases(array $aliases)
Convert certain index names to alternative names before querying the DB.Note that this applies to ind...
Definition: Database.php:5899
Wikimedia\Rdbms\Database\decodeBlob
decodeBlob( $b)
Some DBMSs return a special placeholder object representing blob fields in result objects....
Definition: Database.php:5374
Wikimedia\Rdbms\Database\unionConditionPermutations
unionConditionPermutations( $table, $vars, array $permute_conds, $extra_conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Construct a UNION query for permutations of conditions.
Definition: Database.php:3959
Wikimedia\Rdbms\Database\factory
static factory( $type, $params=[], $connect=self::NEW_CONNECTED)
Construct a Database subclass instance given a database type and parameters.
Definition: Database.php:436
Wikimedia\Rdbms\Database\selectDomain
selectDomain( $domain)
Set the current domain (database, schema, and table prefix)
Definition: Database.php:3047
Wikimedia\Rdbms\Database\isConnectionError
isConnectionError( $errno)
Do not use this method outside of Database/DBError classes.
Definition: Database.php:4102
Wikimedia\Rdbms\Database\buildIntegerCast
buildIntegerCast( $field)
Field or column to cast string 1.31
Definition: Database.php:3016
LIST_AND
const LIST_AND
Definition: Defines.php:43
Wikimedia\Rdbms\Database\prependDatabaseOrSchema
prependDatabaseOrSchema( $namespace, $relation, $format)
Definition: Database.php:3185
Wikimedia\Rdbms\Database\$delimiter
string $delimiter
Current SQL query delimiter.
Definition: Database.php:110
Wikimedia\Rdbms\Database\lock
lock( $lockName, $method, $timeout=5, $flags=0)
Acquire a named lock.Named locks are not related to transactionsName of lock to acquire Name of the c...
Definition: Database.php:5628
Wikimedia\Rdbms\Database\__destruct
__destruct()
Run a few simple checks and close dangling connections.
Definition: Database.php:6116
Wikimedia\Rdbms\Database\endAtomic
endAtomic( $fname=__METHOD__)
Ends an atomic section of SQL statements.
Definition: Database.php:4696
Wikimedia\Rdbms\Database\indexName
indexName( $index)
Allows for index remapping in queries where this is not consistent across DBMS.
Definition: Database.php:3418
Wikimedia\Rdbms\Database\executeQuery
executeQuery( $sql, $fname, $flags)
Execute a query, retrying it if there is a recoverable connection loss.
Definition: Database.php:1329
Wikimedia\Rdbms\IDatabase\lastError
lastError()
Get a description of the last error.
DBO_DEBUG
const DBO_DEBUG
Definition: defines.php:9
Wikimedia\Rdbms\Database\setBigSelects
setBigSelects( $value=true)
Allow or deny "big selects" for this session only.This is done by setting the sql_big_selects session...
Definition: Database.php:5861
Wikimedia\Rdbms\Database\doDropTable
doDropTable( $table, $fname)
Definition: Database.php:5797
Wikimedia\Rdbms\DBReadOnlyRoleError
Exception class for attempted DB write access to a DBConnRef with the DB_REPLICA role.
Definition: DBReadOnlyRoleError.php:30
Wikimedia\Rdbms\DBTransactionStateError
Definition: DBTransactionStateError.php:28
Wikimedia\Rdbms
Definition: ChronologyProtector.php:24
Wikimedia\Rdbms\Database\timestampOrNull
timestampOrNull( $ts=null)
Convert a timestamp in one of the formats accepted by ConvertibleTimestamp to the format used for ins...
Definition: Database.php:5172
Wikimedia\Rdbms\Database\decodeExpiry
decodeExpiry( $expiry, $format=TS_MW)
Decode an expiry time into a DBMS independent format.
Definition: Database.php:5849
Wikimedia\Rdbms\Database\$trxAutomaticAtomic
bool $trxAutomaticAtomic
Whether the current transaction was started implicitly by startAtomic()
Definition: Database.php:153
Wikimedia\Rdbms\Database\initConnection
initConnection()
Initialize the connection to the database over the wire (or to local files)
Definition: Database.php:343
Wikimedia\Rdbms\Database\normalizeConditions
normalizeConditions( $conds, $fname)
Definition: Database.php:2244
Wikimedia\Rdbms\Database\anyString
anyString()
Returns a token for buildLike() that denotes a '' to be used in a LIKE query.
Definition: Database.php:3512
Wikimedia\Rdbms\Database\$server
string null $server
Server that this instance is currently connected to.
Definition: Database.php:83
Wikimedia\Rdbms\Database\unionSupportsOrderAndLimit
unionSupportsOrderAndLimit()
Determine if the RDBMS supports ORDER BY and LIMIT for separate subqueries within UNION....
Definition: Database.php:3945
Wikimedia\Rdbms\Database\factorConds
factorConds( $condsArray)
Given an array of condition arrays representing an OR list of AND lists, for example:
Definition: Database.php:2751
Wikimedia\Rdbms\Database\isInsertSelectSafe
isInsertSelectSafe(array $insertOptions, array $selectOptions)
Definition: Database.php:3811
LIST_SET
const LIST_SET
Definition: Defines.php:44
Wikimedia\Rdbms\Database\fieldNameWithAlias
fieldNameWithAlias( $name, $alias=false)
Get an aliased field name e.g.
Definition: Database.php:3256
Wikimedia\Rdbms\Database\assertIsWritableMaster
assertIsWritableMaster()
Definition: Database.php:1072
Wikimedia\Rdbms\Database\normalizeOptions
normalizeOptions( $options)
Definition: Database.php:2337
Wikimedia\Rdbms\Database\getDefaultSchemaVars
getDefaultSchemaVars()
Get schema variables to use if none have been set via setSchemaVars().
Definition: Database.php:5592
BagOStuff
Class representing a cache/ephemeral data store.
Definition: BagOStuff.php:86
Wikimedia\Rdbms\Database\primaryPosWait
primaryPosWait(DBPrimaryPos $pos, $timeout)
Wait for the replica DB to catch up to a given primary DB position.Note that this does not start any ...
Definition: Database.php:4161
Wikimedia\Rdbms\GeneralizedSql
Lazy-loaded wrapper for simplification and scrubbing of SQL queries for profiling.
Definition: GeneralizedSql.php:30
Wikimedia\Rdbms\Database\extractSingleFieldFromList
extractSingleFieldFromList( $var)
Definition: Database.php:2439
Wikimedia\Rdbms\Database\duplicateTableStructure
duplicateTableStructure( $oldName, $newName, $temporary=false, $fname=__METHOD__)
Creates a new table with structure copied from existing table.Note that unlike most database abstract...
Definition: Database.php:5137
Wikimedia\Rdbms\Database\$trxSectionCancelCallbacks
array[] $trxSectionCancelCallbacks
List of (callable, method name, atomic section id)
Definition: Database.php:176
Wikimedia\Rdbms\Database\doTruncate
doTruncate(array $tables, $fname)
Definition: Database.php:5828
Wikimedia\Rdbms\Database\onTransactionCommitOrIdle
onTransactionCommitOrIdle(callable $callback, $fname=__METHOD__)
Run a callback when the current transaction commits or now if there is none.
Definition: Database.php:4199
Wikimedia\Rdbms\Database\registerTempWrites
registerTempWrites( $ret, array $changes)
Definition: Database.php:1252
Wikimedia\Rdbms\Database\namedLocksEnqueue
namedLocksEnqueue()
Check to see if a named lock used by lock() use blocking queues.bool 1.26
Definition: Database.php:5727
Wikimedia\Rdbms\Database\buildSubstring
buildSubstring( $input, $startPosition, $length=null)
Definition: Database.php:2940
Wikimedia\Rdbms\Database\tableNamesWithIndexClauseOrJOIN
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:3292
Wikimedia\Rdbms\Database\getReplicaPos
getReplicaPos()
Get the replication position of this replica DB.DBPrimaryPos|bool False if this is not a replica DB I...
Definition: Database.php:4170
Wikimedia\Rdbms\Database\getSchemaVars
getSchemaVars()
Get schema variables.
Definition: Database.php:5579
Wikimedia\Rdbms\Database\setLogger
setLogger(LoggerInterface $logger)
Set the PSR-3 logger interface to use for query logging.
Definition: Database.php:574
Wikimedia\Rdbms\Database\__clone
__clone()
Make sure that copies do not share the same client binding handle.
Definition: Database.php:6078
$res
$res
Definition: testCompression.php:57
Wikimedia\Rdbms\Database\cancelAtomic
cancelAtomic( $fname=__METHOD__, AtomicSectionIdentifier $sectionId=null)
Cancel an atomic section of SQL statements.
Definition: Database.php:4746
$base
$base
Definition: generateLocalAutoload.php:11
Wikimedia\Rdbms\Database\getFlag
getFlag( $flag)
Returns a boolean whether the flag $flag is set for this connection.
Definition: Database.php:851
Wikimedia\Rdbms\Database\doInsertSelectGeneric
doInsertSelectGeneric( $destTable, $srcTable, array $varMap, $conds, $fname, array $insertOptions, array $selectOptions, $selectJoinConds)
Implementation of insertSelect() based on select() and insert()
Definition: Database.php:3829
Wikimedia\Rdbms\Database\$trxAtomicLevels
array $trxAtomicLevels
List of (name, unique ID, savepoint ID) for each active atomic section level.
Definition: Database.php:151
Wikimedia\Rdbms\DBError
Database error base class.
Definition: DBError.php:32
LIST_COMMA
const LIST_COMMA
Definition: Defines.php:42
Wikimedia\Rdbms\Database\handleSessionLossPostconnect
handleSessionLossPostconnect()
Clean things up after session (and thus transaction) loss after reconnect.
Definition: Database.php:1714
Wikimedia\Rdbms\Database\isPristineTemporaryTable
isPristineTemporaryTable( $table)
Check if the table is both a TEMPORARY table and has not yet received CRUD operations.
Definition: Database.php:1283
Wikimedia\Rdbms\Database\$connectionVariables
string[] int[] float[] $connectionVariables
SQL variables values to use for all new connections.
Definition: Database.php:101
Wikimedia\Rdbms\Database\$lastQuery
string $lastQuery
The last SQL query attempted.
Definition: Database.php:188
Wikimedia\Rdbms\Database\$trxStatusIgnoredCause
array null $trxStatusIgnoredCause
Error details of the last statement-only rollback.
Definition: Database.php:137
DBO_TRX
const DBO_TRX
Definition: defines.php:12
Wikimedia\Rdbms\Database\textFieldSize
textFieldSize( $table, $field)
Returns the size of a text field, or -1 for "unlimited".int
Definition: Database.php:3722
Wikimedia\Rdbms\Database\$affectedRowCount
int null $affectedRowCount
Rows affected by the last query to query() or its CRUD wrappers.
Definition: Database.php:183
Wikimedia\Rdbms\Database\buildConcat
buildConcat( $stringList)
Build a concatenation list to feed into a SQL query.Raw SQL expression list; caller is responsible fo...
Definition: Database.php:2861
Wikimedia\Rdbms\Database\bitNot
bitNot( $field)
string
Definition: Database.php:2837
Wikimedia\Rdbms\Database\nextSavepointId
nextSavepointId( $fname)
Definition: Database.php:4619
Wikimedia\Rdbms\Database\$agent
string $agent
Agent name for query profiling.
Definition: Database.php:93
Wikimedia\Rdbms\IDatabase
Basic database interface for live and lazy-loaded relation database handles.
Definition: IDatabase.php:38
Wikimedia\Rdbms\Database\__sleep
__sleep()
Called by serialize.
Definition: Database.php:6108
DBO_NOBUFFER
const DBO_NOBUFFER
Definition: defines.php:10
Wikimedia\Rdbms\Database\assertValidUpsertSetArray
assertValidUpsertSetArray(array $set, array $identityKey, array $rows)
Definition: Database.php:2380
Wikimedia\Rdbms\Database\getTopologyRole
getTopologyRole()
Get the replication topology role of this server.
Definition: Database.php:586
Wikimedia\Rdbms\Database\doBegin
doBegin( $fname)
Issues the BEGIN command to the database server.
Definition: Database.php:4943
Wikimedia\Rdbms\Database\isWriteQuery
isWriteQuery( $sql, $flags)
Determine whether a query writes to the DB.
Definition: Database.php:1129
Wikimedia\Rdbms\DBPrimaryPos
An object representing a primary or replica DB position in a replicated setup.
Definition: DBPrimaryPos.php:15
Wikimedia\Rdbms\Database\isFlagInOptions
isFlagInOptions( $option, array $options)
Definition: Database.php:2425
Wikimedia\Rdbms\Database\clearFlag
clearFlag( $flag, $remember=self::REMEMBER_NOTHING)
Clear a flag for this connection.
Definition: Database.php:823
Wikimedia\Rdbms\Database\getQueryExceptionAndLog
getQueryExceptionAndLog( $error, $errno, $sql, $fname)
Definition: Database.php:1775
Wikimedia\Rdbms\Database\begin
begin( $fname=__METHOD__, $mode=self::TRANSACTION_EXPLICIT)
Begin a transaction.
Definition: Database.php:4871
Wikimedia\Rdbms\Database\doHandleSessionLossPreconnect
doHandleSessionLossPreconnect()
Reset any additional subclass trx* and session* fields @stable to override.
Definition: Database.php:1707
Wikimedia\Rdbms\Database\$lastWriteTime
float bool $lastWriteTime
UNIX timestamp of last write query.
Definition: Database.php:190
Wikimedia\Rdbms\Database\doQuery
doQuery( $sql)
Run a query and return a DBMS-dependent wrapper or boolean.
Wikimedia\Rdbms\Database\fetchObject
fetchObject(IResultWrapper $res)
Fetch the next row from the given result object, in object form.
Definition: Database.php:859
Wikimedia\Rdbms\Database\close
close( $fname=__METHOD__, $owner=null)
Close the database connection.
Definition: Database.php:965
Wikimedia\Rdbms\Database\replaceVars
replaceVars( $ins)
Database-independent variable replacement.
Definition: Database.php:5541
Wikimedia\Rdbms\Database\handleSessionLossPreconnect
handleSessionLossPreconnect()
Clean things up after session (and thus transaction) loss before reconnect.
Definition: Database.php:1675
Wikimedia\Rdbms\Database\doInsertNonConflicting
doInsertNonConflicting( $table, array $rows, $fname)
Definition: Database.php:2547
Wikimedia\Rdbms\Database\$trxStatus
int $trxStatus
Transaction status.
Definition: Database.php:133
Wikimedia\Rdbms\Database\runOnTransactionPreCommitCallbacks
runOnTransactionPreCommitCallbacks()
Consume and run any "on transaction pre-commit" callbacks.
Definition: Database.php:4456
Wikimedia\Rdbms\Database\wasLockTimeout
wasLockTimeout()
Determines if the last failure was due to a lock timeout.Note that during a lock wait timeout,...
Definition: Database.php:4067
Wikimedia\Rdbms\Database\$currentDomain
DatabaseDomain $currentDomain
Definition: Database.php:73
Wikimedia\Rdbms\Database\getLag
getLag()
Get the amount of replication lag for this database server.
Definition: Database.php:5337
Wikimedia\Rdbms\Database\$sessionTempTables
array $sessionTempTables
Map of (table name => 1) for current TEMPORARY tables.
Definition: Database.php:126
Wikimedia\Rdbms\Database\buildSelectSubquery
buildSelectSubquery( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Equivalent to IDatabase::selectSQLText() except wraps the result in Subquery.
Definition: Database.php:3020
Wikimedia\Rdbms\Database\getCacheSetOptions
static getCacheSetOptions(?IDatabase ... $dbs)
Merge the result of getSessionLagStatus() for several DBs using the most pessimistic values to estima...
Definition: Database.php:5317
Wikimedia\Rdbms\Database\assertBuildSubstringParams
assertBuildSubstringParams( $startPosition, $length)
Check type and bounds for parameters to self::buildSubstring()
Definition: Database.php:2961
Wikimedia\Rdbms\Database\isReadOnly
isReadOnly()
Definition: Database.php:5865
Wikimedia\Rdbms\Database\buildStringCast
buildStringCast( $field)
Field or column to cast string 1.28
Definition: Database.php:3006
Wikimedia\Rdbms\Database\$lazyMasterHandle
IDatabase null $lazyMasterHandle
Lazy handle to the primary DB this server replicates from.
Definition: Database.php:80
Wikimedia\Rdbms\Database\unlockTables
unlockTables( $method)
Unlock all tables locked via lockTables()
Definition: Database.php:5760
Wikimedia\Rdbms\Database\getSessionLagStatus
getSessionLagStatus()
Get the replica DB lag when the current transaction started or a general lag estimate if not transact...
Definition: Database.php:5250
Wikimedia\Rdbms\Database\$trxWriteDuration
float $trxWriteDuration
Seconds spent in write queries for the current transaction.
Definition: Database.php:157
wfDeprecated
wfDeprecated( $function, $version=false, $component=false, $callerOffset=2)
Logs a warning that a deprecated feature was used.
Definition: GlobalFunctions.php:997
Wikimedia\Rdbms\Database\doRollbackToSavepoint
doRollbackToSavepoint( $identifier, $fname)
Rollback to a savepoint.
Definition: Database.php:4610
Wikimedia\Rdbms\Database\dropTable
dropTable( $table, $fname=__METHOD__)
Delete a table.
Definition: Database.php:5781
Wikimedia\Rdbms\Database\$csmId
int null $csmId
Current critical section numeric ID.
Definition: Database.php:197
Wikimedia\Rdbms\Database\getTempTableWrites
getTempTableWrites( $sql, $pseudoPermanent)
Definition: Database.php:1196
Wikimedia\Rdbms\Database\doInsertSelectNative
doInsertSelectNative( $destTable, $srcTable, array $varMap, $conds, $fname, array $insertOptions, array $selectOptions, $selectJoinConds)
Native server-side implementation of insertSelect() for situations where we don't want to select ever...
Definition: Database.php:3894
Wikimedia\Rdbms\Database\startAtomic
startAtomic( $fname=__METHOD__, $cancelable=self::ATOMIC_NOT_CANCELABLE)
Begin an atomic section of SQL statements.
Definition: Database.php:4634
Wikimedia\Rdbms\DBQueryTimeoutError
Error thrown when a query times out.
Definition: DBQueryTimeoutError.php:30
Wikimedia\Rdbms\Database\selectOptionsIncludeLocking
selectOptionsIncludeLocking( $options)
Definition: Database.php:2174
Wikimedia\Rdbms\IResultWrapper
Result wrapper for grabbing data queried from an IDatabase object.
Definition: IResultWrapper.php:26
Wikimedia\Rdbms\Database\getTransactionRoundId
getTransactionRoundId()
Definition: Database.php:723
Wikimedia\Rdbms\Database\trxLevel
trxLevel()
Gets the current transaction level.
Definition: Database.php:594
Wikimedia\Rdbms\Database\setFlag
setFlag( $flag, $remember=self::REMEMBER_NOTHING)
Set a flag for this connection.
Definition: Database.php:808
Wikimedia\Rdbms\Database\rollback
rollback( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
Rollback a transaction previously started using begin()
Definition: Database.php:5032
Wikimedia\Rdbms\Database\assertQueryIsCurrentlyAllowed
assertQueryIsCurrentlyAllowed( $sql, $fname)
Error out if the DB is not in a valid state for a query via query()
Definition: Database.php:1584
Wikimedia\Rdbms\Database\setTransactionListener
setTransactionListener( $name, callable $callback=null)
Run a callback after each time any transaction commits or rolls back.
Definition: Database.php:4359
Wikimedia\Rdbms\Database\getPrimaryPos
getPrimaryPos()
Get the position of this primary DB.DBPrimaryPos|bool False if this is not a primary DB If an error o...
Definition: Database.php:4179
Wikimedia\Rdbms\Database\escapeLikeInternal
escapeLikeInternal( $s, $escapeChar='`')
Definition: Database.php:3469
Wikimedia\Rdbms\Database\$tableAliases
array[] $tableAliases
Current map of (table => (dbname, schema, prefix) map)
Definition: Database.php:112
Wikimedia\Rdbms\Database\reportQueryError
reportQueryError( $error, $errno, $sql, $fname, $ignore=false)
Report a query error.
Definition: Database.php:1760
Wikimedia\Rdbms\Database\$cliMode
bool $cliMode
Whether this PHP instance is for a CLI script.
Definition: Database.php:91
Wikimedia\Rdbms\Database\numRows
numRows( $res)
Get the number of rows in a query result.
Definition: Database.php:867
Wikimedia\Rdbms\Database\isTransactableQuery
isTransactableQuery( $sql)
Determine whether a SQL statement is sensitive to isolation level.
Definition: Database.php:1180
Wikimedia\Rdbms\Database\lockForUpdate
lockForUpdate( $table, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Lock all rows meeting the given conditions/options FOR UPDATE.
Definition: Database.php:2455
Wikimedia\Rdbms\Database\indexExists
indexExists( $table, $index, $fname=__METHOD__)
Determines whether an index exists.
Definition: Database.php:2477
Wikimedia\Rdbms\Database\writesOrCallbacksPending
writesOrCallbacksPending()
Whether there is a transaction open with either possible write queries or unresolved pre-commit/commi...
Definition: Database.php:710
Wikimedia\Rdbms\Database\sourceStream
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:5426
Wikimedia\Rdbms\Database\selectSQLText
selectSQLText( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Take the same arguments as IDatabase::select() and return the SQL it would use.This can be useful for...
Definition: Database.php:2015
Wikimedia\Rdbms\SelectQueryBuilder
Definition: SelectQueryBuilder.php:11
Wikimedia\Rdbms\Database\makeInsertLists
makeInsertLists(array $rows)
Make SQL lists of columns, row tuples for INSERT/VALUES expressions.
Definition: Database.php:2576
$args
if( $line===false) $args
Definition: mcc.php:124
Wikimedia\Rdbms\Database\$trxWriteCallers
string[] $trxWriteCallers
Write query callers of the current transaction.
Definition: Database.php:155
Wikimedia\Rdbms\Database\$lastPing
float $lastPing
UNIX timestamp.
Definition: Database.php:186
Wikimedia\Rdbms\Database\bitAnd
bitAnd( $fieldLeft, $fieldRight)
string
Definition: Database.php:2845
Wikimedia\Rdbms\Database\buildLike
buildLike( $param,... $params)
LIKE statement wrapper.This takes a variable-length argument list with parts of pattern to match cont...
Definition: Database.php:3481
Wikimedia\Rdbms\Database\$trxProfiler
TransactionProfiler $trxProfiler
Definition: Database.php:70
Wikimedia\Rdbms\Database\selectDB
selectDB( $db)
Change the current database.
Definition: Database.php:3037
Wikimedia\Rdbms\Database\wasQueryTimeout
wasQueryTimeout( $error, $errno)
Checks whether the cause of the error is detected to be a timeout.
Definition: Database.php:1745
Wikimedia\Rdbms\Database\closeConnection
closeConnection()
Closes underlying database connection.
Wikimedia\Rdbms\Database\lastDoneWrites
lastDoneWrites()
Get the last time the connection may have been used for a write query.
Definition: Database.php:702
Wikimedia\Rdbms\Database\wasReadOnlyError
wasReadOnlyError()
Determines if the last failure was due to the database being read-only.bool
Definition: Database.php:4083
Wikimedia\Rdbms\Database\doUnlock
doUnlock(string $lockName, string $method)
Definition: Database.php:5683
Wikimedia\Rdbms\Database\beginIfImplied
beginIfImplied( $sql, $fname)
Start an implicit transaction if DBO_TRX is enabled and no transaction is active.
Definition: Database.php:1531
Wikimedia\Rdbms\Database\$csmError
DBUnexpectedError null $csmError
Last unresolved critical section error.
Definition: Database.php:201
Wikimedia\Rdbms\Database\getQueryException
getQueryException( $error, $errno, $sql, $fname)
Definition: Database.php:1799
Wikimedia\Rdbms\Database\runTransactionListenerCallbacks
runTransactionListenerCallbacks( $trigger, array &$errors=[])
Actually run any "transaction listener" callbacks.
Definition: Database.php:4521
Wikimedia\Rdbms\Database\getServerInfo
getServerInfo()
Get a human-readable string describing the current software version.
Definition: Database.php:578
Wikimedia\Rdbms\Database\commit
commit( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
Commits a transaction previously started using begin()
Definition: Database.php:4947
Wikimedia\Rdbms\Database\buildLeast
buildLeast( $fields, $values)
Build a LEAST function statement comparing columns/values.Integer and float values in $values will no...
Definition: Database.php:2889
Wikimedia\Rdbms\Database\restoreFlags
restoreFlags( $state=self::RESTORE_PRIOR)
Restore the flags to their prior state before the last setFlag/clearFlag call.
Definition: Database.php:838
Wikimedia\Rdbms\Database\CONN_INITIAL_SCHEMA
const CONN_INITIAL_SCHEMA
Schema name to use on initial connection.
Definition: Database.php:275
Wikimedia\Rdbms\Database\connectionErrorLogger
connectionErrorLogger( $errno, $errstr)
Error handler for logging errors during database connection.
Definition: Database.php:944
Wikimedia\Rdbms\Database\setLBInfo
setLBInfo( $nameOrArray, $value=null)
Set the entire array or a particular key of the managing load balancer info array.
Definition: Database.php:666
Wikimedia\Rdbms\Database\getScopedLockAndFlush
getScopedLockAndFlush( $lockKey, $fname, $timeout)
Acquire a named lock, flush any transaction, and return an RAII style unlocker object.
Definition: Database.php:5687
Wikimedia\Rdbms\Database\fieldNamesWithAlias
fieldNamesWithAlias( $fields)
Gets an array of aliased field names.
Definition: Database.php:3270
Wikimedia\Rdbms\Database\getLBInfo
getLBInfo( $name=null)
Get properties passed down from the server info array of the load balancer.
Definition: Database.php:654
Wikimedia\Rdbms\DBReadOnlyError
Definition: DBReadOnlyError.php:28
Wikimedia\Rdbms\Database\$trxWriteAffectedRows
int $trxWriteAffectedRows
Number of rows affected by write queries for the current transaction.
Definition: Database.php:161
Wikimedia\Rdbms\Database\$trxWriteAdjDuration
float $trxWriteAdjDuration
Like trxWriteQueryCount but excludes lock-bound, easy to replicate, queries.
Definition: Database.php:163
Wikimedia\Rdbms\Database\insertSelect
insertSelect( $destTable, $srcTable, $varMap, $conds, $fname=__METHOD__, $insertOptions=[], $selectOptions=[], $selectJoinConds=[])
INSERT SELECT wrapper.
Definition: Database.php:3760
Wikimedia\Rdbms\Database\normalizeRowArray
normalizeRowArray(array $rowOrRows)
Definition: Database.php:2218
Wikimedia\Rdbms\Database\$csProvider
CriticalSectionProvider null $csProvider
Definition: Database.php:56
Wikimedia\Rdbms\Database\selectRow
selectRow( $table, $vars, $conds, $fname=__METHOD__, $options=[], $join_conds=[])
Wrapper to IDatabase::select() that only fetches one row (via LIMIT)
Definition: Database.php:2102
Wikimedia\Rdbms\DBQueryError
Definition: DBQueryError.php:29
Wikimedia\Rdbms\Database\useIndexClause
useIndexClause( $index)
USE INDEX clause.
Definition: Database.php:3533
Wikimedia\Rdbms\Database\makeUpdateOptions
makeUpdateOptions( $options)
Make UPDATE options for the Database::update function.
Definition: Database.php:2631
Wikimedia\Rdbms\Database\getReadOnlyReason
getReadOnlyReason()
Definition: Database.php:5872
Wikimedia\Rdbms\Database\buildSuperlative
buildSuperlative( $sqlfunc, $fields, $values)
Build a superlative function statement comparing columns/values.
Definition: Database.php:2909
Wikimedia\Rdbms\DBQueryDisconnectedError
Definition: DBQueryDisconnectedError.php:29
Wikimedia\Rdbms\Database\$priorFlags
int[] $priorFlags
Prior flags member variable values.
Definition: Database.php:121
Wikimedia\Rdbms\Database\doGetLag
doGetLag()
Get the amount of replication lag for this database server.
Definition: Database.php:5358
Wikimedia\Rdbms\Database\normalizeJoinType
normalizeJoinType(string $joinType)
Validate and normalize a join type.
Definition: Database.php:3393
Wikimedia\Rdbms\Database\installErrorHandler
installErrorHandler()
Set a custom error handler for logging errors during database connection.
Definition: Database.php:902
Wikimedia\Rdbms\Database\restoreErrorHandler
restoreErrorHandler()
Restore the previous error handler and return the last PHP error for this DB.
Definition: Database.php:913
Wikimedia\Rdbms\Database\assertIsWritablePrimary
assertIsWritablePrimary()
Make sure that this server is not marked as a replica nor read-only.
Definition: Database.php:1056
Wikimedia\Rdbms\Database\wasKnownStatementRollbackError
wasKnownStatementRollbackError()
Definition: Database.php:4113
Wikimedia\Rdbms\Database\pendingWriteAndCallbackCallers
pendingWriteAndCallbackCallers()
List the methods that have write queries or callbacks for the current transaction.
Definition: Database.php:779
Wikimedia\Rdbms\Database\$htmlErrors
string bool null $htmlErrors
Stashed value of html_errors INI setting.
Definition: Database.php:119
Wikimedia\Rdbms\Database\tableExists
tableExists( $table, $fname=__METHOD__)
Query whether a given table exists.
Wikimedia\Rdbms\Database\pendingWriteCallers
pendingWriteCallers()
Get the list of method names that did write queries for this transaction.
Definition: Database.php:767
$s
foreach( $mmfl['setupFiles'] as $fileName) if( $queue) if(empty( $mmfl['quiet'])) $s
Definition: mergeMessageFileList.php:206
Wikimedia\Rdbms\Database\$trxEndCallbacks
array[] $trxEndCallbacks
List of (callable, method name, atomic section id)
Definition: Database.php:174
Wikimedia\Rdbms\Database\tableNames
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:3196
Wikimedia\Rdbms\Database\conditional
conditional( $cond, $caseTrueExpression, $caseFalseExpression)
Returns an SQL expression for a simple conditional.This doesn't need to be overridden unless CASE isn...
Definition: Database.php:4039
Wikimedia\Rdbms\Database\__toString
__toString()
Get a debugging string that mentions the database type, the ID of this instance, and the ID of any un...
Definition: Database.php:6054
Wikimedia\Rdbms\Database\$lastRoundTripEstimate
float $lastRoundTripEstimate
Query round trip time estimate.
Definition: Database.php:194
Wikimedia\Rdbms\Database\getLogContext
getLogContext(array $extras=[])
Create a log context to pass to PSR-3 logger functions.
Definition: Database.php:954
Wikimedia\Rdbms\Database\$connectionParams
array< string, mixed > $connectionParams
Connection parameters used by initConnection() and open()
Definition: Database.php:99
DBO_DDLMODE
const DBO_DDLMODE
Definition: defines.php:16
Wikimedia\Rdbms\Database\$trxAutomatic
bool $trxAutomatic
Whether the current transaction was started implicitly due to DBO_TRX.
Definition: Database.php:147
Wikimedia\Rdbms\Database\flushSnapshot
flushSnapshot( $fname=__METHOD__, $flush=self::FLUSHING_ONE)
Commit any transaction but error out if writes or callbacks are pending.
Definition: Database.php:5097
Wikimedia\Rdbms\Database\$trxStatusCause
Throwable null $trxStatusCause
The last error that caused the status to become STATUS_TRX_ERROR.
Definition: Database.php:135
Wikimedia\Rdbms\Database\fetchRow
fetchRow(IResultWrapper $res)
Fetch the next row from the given result object, in associative array form.
Definition: Database.php:863
Wikimedia\Rdbms\Database\runTransactionPostCommitCallbacks
runTransactionPostCommitCallbacks()
Handle "on transaction idle/resolution" and "transaction listener" callbacks post-COMMIT.
Definition: Database.php:4544
Wikimedia\Rdbms\Database\$trxPreCommitOrIdleCallbacks
array[] $trxPreCommitOrIdleCallbacks
List of (callable, method name, atomic section id)
Definition: Database.php:169
Wikimedia\Rdbms\Database\$trxWriteQueryCount
int $trxWriteQueryCount
Number of write queries for the current transaction.
Definition: Database.php:159
Wikimedia\Rdbms\AtomicSectionIdentifier
Class used for token representing identifiers for atomic sections from IDatabase instances.
Definition: AtomicSectionIdentifier.php:26
Wikimedia\Rdbms\Database\doReleaseSavepoint
doReleaseSavepoint( $identifier, $fname)
Release a savepoint.
Definition: Database.php:4594
Wikimedia\Rdbms\Database\executeQueryAttempt
executeQueryAttempt( $sql, $commentedSql, $isPermWrite, $fname, $flags)
Wrapper for doQuery() that handles DBO_TRX, profiling, logging, affected row count tracking,...
Definition: Database.php:1429
$line
$line
Definition: mcc.php:119
Wikimedia\Rdbms\Database\currentAtomicSectionId
currentAtomicSectionId()
Definition: Database.php:4262
Wikimedia\Rdbms\Database\modifyCallbacksForCancel
modifyCallbacksForCancel(array $sectionIds, AtomicSectionIdentifier $newSectionId=null)
Update callbacks that were owned by cancelled atomic sections.
Definition: Database.php:4323
Wikimedia\Rdbms\Database\setTrxEndCallbackSuppression
setTrxEndCallbackSuppression( $suppress)
Whether to disable running of post-COMMIT/ROLLBACK callbacks.
Definition: Database.php:4375
Wikimedia\Rdbms\Database\query
query( $sql, $fname=__METHOD__, $flags=self::QUERY_NORMAL)
Run an SQL query and return the result.
Definition: Database.php:1292
Wikimedia\Rdbms\Database\pendingWriteQueryDuration
pendingWriteQueryDuration( $type=self::ESTIMATE_TOTAL)
Get the time spend running write queries for this transaction.
Definition: Database.php:735
Wikimedia\Rdbms\Database\$indexAliases
string[] $indexAliases
Current map of (index alias => index)
Definition: Database.php:114
Wikimedia\Rdbms\Database\normalizeUpsertParams
normalizeUpsertParams( $uniqueKeys, &$rows)
Validate and normalize parameters to upsert() or replace()
Definition: Database.php:2269
Wikimedia\Rdbms\LikeMatch
Used by Database::buildLike() to represent characters that have special meaning in SQL LIKE clauses a...
Definition: LikeMatch.php:10
Wikimedia\Rdbms\Database\tableName
tableName( $name, $format='quoted')
Format a table name ready for use in constructing an SQL query.This does two important things: it quo...
Definition: Database.php:3087
Wikimedia\Rdbms\Database\setTransactionError
setTransactionError(Throwable $trxError)
Mark the transaction as requiring rollback (STATUS_TRX_ERROR) due to an error.
Definition: Database.php:5941
Wikimedia\Rdbms\Database\doAtomicSection
doAtomicSection( $fname, callable $callback, $cancelable=self::ATOMIC_NOT_CANCELABLE)
Perform an atomic section of reversible SQL statements from a callback.
Definition: Database.php:4850
Wikimedia\Rdbms\Database\$trxReplicaLagStatus
array null $trxReplicaLagStatus
Replication lag estimate at the time of BEGIN for the last transaction.
Definition: Database.php:141
Wikimedia\Rdbms\Database\replace
replace( $table, $uniqueKeys, $rows, $fname=__METHOD__)
Insert row(s) into a table, deleting all conflicting rows beforehand.
Definition: Database.php:3550
Wikimedia\Rdbms\Database\getRecordedTransactionLagStatus
getRecordedTransactionLagStatus()
Get the replica DB lag when the current transaction started.
Definition: Database.php:5267
Wikimedia\Rdbms\Database\strencode
strencode( $s)
Wrapper for addslashes()
Wikimedia\Rdbms\Database\CONN_PASSWORD
const CONN_PASSWORD
Database server password to use on all connections.
Definition: Database.php:271
Wikimedia\Rdbms\Database\$user
string null $user
User that this instance is currently connected under the name of.
Definition: Database.php:85
Wikimedia\Rdbms\Database\doLockIsFree
doLockIsFree(string $lockName, string $method)
Definition: Database.php:5621
Wikimedia\Rdbms\Database\getServer
getServer()
Get the hostname or IP address of the server.
Definition: Database.php:3075
Wikimedia\Rdbms\DBUnexpectedError
Definition: DBUnexpectedError.php:29
Wikimedia\Rdbms\Database\doLockTables
doLockTables(array $read, array $write, $method)
Helper function for lockTables() that handles the actual table locking.
Definition: Database.php:5756
Wikimedia\Rdbms\Database\doUnlockTables
doUnlockTables( $method)
Helper function for unlockTables() that handles the actual table unlocking.
Definition: Database.php:5777
Wikimedia\Rdbms\Database\timestamp
timestamp( $ts=0)
Convert a timestamp in one of the formats accepted by ConvertibleTimestamp to the format used for ins...
Definition: Database.php:5166
Wikimedia\Rdbms\Database\selectField
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:1835
Wikimedia\Rdbms\Database\anyChar
anyChar()
Returns a token for buildLike() that denotes a '_' to be used in a LIKE query.
Definition: Database.php:3508
Wikimedia\Rdbms\Database\unlock
unlock( $lockName, $method)
Release a lock.Named locks are not related to transactionsName of lock to release Name of the calling...
Definition: Database.php:5663
Wikimedia\Rdbms\Database\getTopologyBasedServerId
getTopologyBasedServerId()
Get a non-recycled ID that uniquely identifies this server within the replication topology.
Definition: Database.php:582
Wikimedia\Rdbms\Database\$profiler
callable null $profiler
Definition: Database.php:68
Wikimedia\Rdbms\Database\addIdentifierQuotes
addIdentifierQuotes( $s)
Escape a SQL identifier (e.g.table, column, database) for use in a SQL queryDepending on the database...
Definition: Database.php:3445
Wikimedia\Rdbms\Database\getLazyMasterHandle
getLazyMasterHandle()
Get a handle to the primary DB server of the cluster to which this server belongs.
Definition: Database.php:686
Wikimedia\Rdbms\Database\estimateRowCount
estimateRowCount( $tables, $var=' *', $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Estimate the number of rows in dataset.MySQL allows you to estimate the number of rows that would be ...
Definition: Database.php:2124
Wikimedia\Rdbms\Database\truncate
truncate( $tables, $fname=__METHOD__)
Delete all data in a table(s) and reset any sequences owned by that table(s)
Definition: Database.php:5805
Wikimedia\Rdbms\Database\commenceCriticalSection
commenceCriticalSection(string $fname)
Demark the start of a critical section of session/transaction state changes.
Definition: Database.php:5988
Wikimedia\Rdbms\Database\dbSchema
dbSchema( $schema=null)
Get/set the db schema.
Definition: Database.php:624
Wikimedia\Rdbms\Database\$trxRecurringCallbacks
callable[] $trxRecurringCallbacks
Map of (name => callable)
Definition: Database.php:178
Wikimedia\Rdbms\Database\getQueryVerb
getQueryVerb( $sql)
Definition: Database.php:1162
Wikimedia\Rdbms\Database\unionQueries
unionQueries( $sqls, $all)
Construct a UNION query.This is used for providing overload point for other DB abstractions not compa...
Definition: Database.php:3953
Wikimedia\Rdbms\Database\freeResult
freeResult(IResultWrapper $res)
Free a result object returned by query() or select()
Definition: Database.php:875
Wikimedia\Rdbms\Database\reassignCallbacksForSection
reassignCallbacksForSection(AtomicSectionIdentifier $old, AtomicSectionIdentifier $new)
Hoist callback ownership for callbacks in a section to a parent section.
Definition: Database.php:4278
Wikimedia\Rdbms\Database\insert
insert( $table, $rows, $fname=__METHOD__, $options=[])
Insert the given row(s) into a table.
Definition: Database.php:2506
Wikimedia\Rdbms\IDatabase\lastErrno
lastErrno()
Get the last error number.
Wikimedia\Rdbms\Database\relationSchemaQualifier
relationSchemaQualifier()
Definition: Database.php:650
Wikimedia\Rdbms\Database\makeInsertNonConflictingVerbAndOptions
makeInsertNonConflictingVerbAndOptions()
Definition: Database.php:2562
Wikimedia\Rdbms\Database\newExceptionAfterConnectError
newExceptionAfterConnectError( $error)
Definition: Database.php:1813
Wikimedia\Rdbms\Database\lockTables
lockTables(array $read, array $write, $method)
Lock specific tables.
Definition: Database.php:5735
Wikimedia\Rdbms\Database\$trxAtomicCounter
int $trxAtomicCounter
Counter for atomic savepoint identifiers (reset with each transaction)
Definition: Database.php:149
Wikimedia\Rdbms\Database\encodeExpiry
encodeExpiry( $expiry)
Encode an expiry time into the DBMS dependent format.
Definition: Database.php:5843
Wikimedia\Rdbms\Database\$srvCache
BagOStuff $srvCache
APC cache.
Definition: Database.php:54
Wikimedia\Rdbms\Database\buildGreatest
buildGreatest( $fields, $values)
Build a GREATEST function statement comparing columns/values.Integer and float values in $values will...
Definition: Database.php:2881
Wikimedia\Rdbms\Database\doSavepoint
doSavepoint( $identifier, $fname)
Create a savepoint.
Definition: Database.php:4578
Wikimedia\Rdbms\Database\setSchemaVars
setSchemaVars( $vars)
Set schema variables to be used when streaming commands from SQL files or stdin.
Definition: Database.php:5422
Wikimedia\Rdbms\Database\__construct
__construct(array $params)
Definition: Database.php:284
Wikimedia\Rdbms\Database\trxTimestamp
trxTimestamp()
Get the UNIX timestamp of the time that the transaction was established.
Definition: Database.php:598
Wikimedia\Rdbms\Database\$trxTimestamp
float null $trxTimestamp
UNIX timestamp at the time of BEGIN for the last transaction.
Definition: Database.php:139
Wikimedia\Rdbms\Database\makeGroupByWithHaving
makeGroupByWithHaving( $options)
Returns an optional GROUP BY with an optional HAVING.
Definition: Database.php:1965
Wikimedia\Rdbms\Database\tableNameWithAlias
tableNameWithAlias( $table, $alias=false)
Get an aliased table name.
Definition: Database.php:3227
Wikimedia\Rdbms\Database\getAttributes
static getAttributes()
Definition: Database.php:563
Wikimedia\Rdbms\Database\writesPending
writesPending()
Definition: Database.php:706
Wikimedia\Rdbms\Database\normalizeUpsertKeys
normalizeUpsertKeys( $uniqueKeys)
Definition: Database.php:2304
Wikimedia\Rdbms\Database\assertValidUpsertRowArray
assertValidUpsertRowArray(array $rows, array $identityKey)
Definition: Database.php:2353
Wikimedia\Rdbms\Database\selectFieldsOrOptionsAggregate
selectFieldsOrOptionsAggregate( $fields, $options)
Definition: Database.php:2190
Wikimedia\Rdbms\Database\factorCondsWithCommonFields
factorCondsWithCommonFields( $condsArray)
Same as factorConds() but with each element in the array having the same set of array keys.
Definition: Database.php:2782
Wikimedia\Rdbms\Database\lockIsFree
lockIsFree( $lockName, $method)
Check to see if a named lock is not locked by any thread (non-blocking)Name of lock to poll Name of m...
Definition: Database.php:5599
Wikimedia\Rdbms\Database\ping
ping(&$rtt=null)
Ping the server and try to reconnect if it there is no connection.
Definition: Database.php:5189
Wikimedia\Rdbms\Database\$nonNativeInsertSelectBatchSize
int $nonNativeInsertSelectBatchSize
Row batch size to use for emulated INSERT SELECT queries.
Definition: Database.php:103
Wikimedia\Rdbms\Database\onAtomicSectionCancel
onAtomicSectionCancel(callable $callback, $fname=__METHOD__)
Run a callback when the atomic section is cancelled.
Definition: Database.php:4252
Wikimedia\Rdbms\DBConnectionError
Definition: DBConnectionError.php:27
Wikimedia\Rdbms\Database\setTableAliases
setTableAliases(array $aliases)
Make certain table names use their own database, schema, and table prefix when passed into SQL querie...
Definition: Database.php:5891
Wikimedia\Rdbms\Database\getServerName
getServerName()
Get the readable name for the server.
Definition: Database.php:3079
Wikimedia\Rdbms\Database\onTransactionResolution
onTransactionResolution(callable $callback, $fname=__METHOD__)
Run a callback when the current transaction commits or rolls back.
Definition: Database.php:4192
Wikimedia\Rdbms\IDatabase\getType
getType()
Get the RDBMS type of the server (e.g.
Wikimedia\Rdbms\Database\explicitTrxActive
explicitTrxActive()
Check whether there is a transaction open at the specific request of a caller.
Definition: Database.php:5129
Wikimedia\Rdbms\Database\isOpen
isOpen()
Definition: Database.php:804
Wikimedia\Rdbms\Database\doCommit
doCommit( $fname)
Issues the COMMIT command to the database server.
Definition: Database.php:5026
$source
$source
Definition: mwdoc-filter.php:34
Wikimedia\Rdbms\IMaintainableDatabase\fieldInfo
fieldInfo( $table, $field)
Get information about a field Returns false if the field doesn't exist.
Wikimedia\Rdbms\Database\$topologyRootMaster
string null $topologyRootMaster
Host (or address) of the root primary server for the replication topology.
Definition: Database.php:97
Wikimedia\Rdbms\Database\runOnTransactionIdleCallbacks
runOnTransactionIdleCallbacks( $trigger, array &$errors=[])
Consume and run any "on transaction idle/resolution" callbacks.
Definition: Database.php:4391
Wikimedia\Rdbms\Database\makeOrderBy
makeOrderBy( $options)
Returns an optional ORDER BY.
Definition: Database.php:1991
Wikimedia\Rdbms\Database\$flags
int $flags
Current bit field of class DBO_* constants.
Definition: Database.php:106
Wikimedia\Rdbms\Database\serverIsReadOnly
serverIsReadOnly()
bool Whether the DB is marked as read-only server-side If an error occurs, {query} 1....
Definition: Database.php:4188
Wikimedia\Rdbms\Database\$trxFname
string null $trxFname
Name of the function that start the last transaction.
Definition: Database.php:143
Wikimedia\Rdbms\Database\makeSelectOptions
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:1894
Wikimedia\Rdbms\Database\select
select( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Execute a SELECT query constructed using the various parameters provided.
Definition: Database.php:2003
Wikimedia\Rdbms\Database\attributesFromType
static attributesFromType( $dbType, $driver=null)
Definition: Database.php:492
Wikimedia\Rdbms\Database\lastQuery
lastQuery()
Get the last query that sent on account of IDatabase::query()
Definition: Database.php:698
Wikimedia\Rdbms\Database\wasConnectionLoss
wasConnectionLoss()
Determines if the last query error was due to a dropped connection.Note that during a connection loss...
Definition: Database.php:4075
Wikimedia\Rdbms\Database\wasDeadlock
wasDeadlock()
Determines if the last failure was due to a deadlock.Note that during a deadlock, the prior transacti...
Definition: Database.php:4059
$t
$t
Definition: testCompression.php:74
Wikimedia\Rdbms\Database\doSelectDomain
doSelectDomain(DatabaseDomain $domain)
Definition: Database.php:3067
Wikimedia\Rdbms\Database\$connLogger
LoggerInterface $connLogger
Definition: Database.php:58
Wikimedia\Rdbms\Database\addQuotes
addQuotes( $s)
Escape and quote a raw value string for use in a SQL query.string
Definition: Database.php:3426
Wikimedia\Rdbms\Database\$replLogger
LoggerInterface $replLogger
Definition: Database.php:62
Wikimedia\Rdbms\Database\$password
string null $password
Password used to establish the current connection.
Definition: Database.php:87
Wikimedia\Rdbms\Database\assertConditionIsNotEmpty
assertConditionIsNotEmpty( $conds, string $fname, bool $deprecate)
Check type and bounds conditions parameters for update.
Definition: Database.php:2991
Wikimedia\Rdbms\Database\getApproximateLagStatus
getApproximateLagStatus()
Get a replica DB lag estimate for this server at the start of a transaction.
Definition: Database.php:5280
Wikimedia\Rdbms\Database\qualifiedTableComponents
qualifiedTableComponents( $name)
Get the table components needed for a query given the currently selected database.
Definition: Database.php:3145
Wikimedia\Rdbms\Database\$trxId
string $trxId
Application-side ID of the active transaction or an empty string otherwise.
Definition: Database.php:131
Wikimedia\Rdbms\Database\affectedRows
affectedRows()
Get the number of rows affected by the last write query.
Definition: Database.php:5180
Wikimedia\Rdbms\Database\fetchAffectedRowCount
fetchAffectedRowCount()
Wikimedia\Rdbms\DatabaseDomain
Class to handle database/schema/prefix specifications for IDatabase.
Definition: DatabaseDomain.php:40
Wikimedia\Rdbms\Database\databasesAreIndependent
databasesAreIndependent()
Returns true if DBs are assumed to be on potentially different servers.In systems like mysql/mariadb,...
Definition: Database.php:3033
Wikimedia\Rdbms\TransactionProfiler
Detect high-contention DB queries via profiling calls.
Definition: TransactionProfiler.php:40
Wikimedia\Rdbms\Database\indexInfo
indexInfo( $table, $index, $fname=__METHOD__)
Get information about an index into an object.
Wikimedia\Rdbms\Database\strreplace
strreplace( $orig, $old, $new)
Returns a SQL expression for simple string replacement (e.g.REPLACE() in mysql)Column to modify Colum...
Definition: Database.php:4051
Wikimedia\Rdbms\Database\$ownerId
int null $ownerId
Integer ID of the managing LBFactory instance or null if none.
Definition: Database.php:204
Wikimedia\Rdbms\Database\sourceFile
sourceFile( $filename, callable $lineCallback=null, callable $resultCallback=null, $fname=false, callable $inputCallback=null)
Read and execute SQL commands from a file.
Definition: Database.php:5388
Wikimedia\Rdbms\Database\doLock
doLock(string $lockName, string $method, int $timeout)
Definition: Database.php:5656
Wikimedia\Rdbms\Database\listViews
listViews( $prefix=null, $fname=__METHOD__)
Lists all the VIEWs in the database.Only show VIEWs with this prefix, eg. unit_test_ Name of calling ...
Definition: Database.php:5158
Wikimedia\Rdbms\Database\runOnAtomicSectionCancelCallbacks
runOnAtomicSectionCancelCallbacks( $trigger, array $sectionIds)
Consume and run any relevant "on atomic section cancel" callbacks for the active transaction.
Definition: Database.php:4486
Wikimedia\Rdbms\Database\newSelectQueryBuilder
newSelectQueryBuilder()
Create an empty SelectQueryBuilder which can be used to run queries against this connection....
Definition: Database.php:1831
Wikimedia\Rdbms\Database\streamStatementEnd
streamStatementEnd(&$sql, &$newLine)
Called by sourceStream() to check if we've reached a statement end.
Definition: Database.php:5504
Wikimedia\Rdbms\Database\makeList
makeList(array $a, $mode=self::LIST_COMMA)
Makes an encoded list of strings from an array.
Definition: Database.php:2655
Wikimedia\Rdbms\IMaintainableDatabase
Advanced database interface for IDatabase handles that include maintenance methods.
Definition: IMaintainableDatabase.php:38
Wikimedia\Rdbms\Database\runTransactionPostRollbackCallbacks
runTransactionPostRollbackCallbacks()
Handle "on transaction idle/resolution" and "transaction listener" callbacks post-ROLLBACK.
Definition: Database.php:4561
Wikimedia\Rdbms\Database\nextSequenceValue
nextSequenceValue( $seqName)
Deprecated method, calls should be removed.
Definition: Database.php:3516
Wikimedia\Rdbms\Subquery
Definition: Subquery.php:27
Wikimedia\Rdbms\Database\selectFieldValues
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:1860
Wikimedia\Rdbms\Database\flatAtomicSectionList
flatAtomicSectionList()
Definition: Database.php:798
Wikimedia\Rdbms\Database\open
open( $server, $user, $password, $db, $schema, $tablePrefix)
Open a new connection to the database (closing any existing one)
Wikimedia\Rdbms\Database\$deprecationLogger
callable $deprecationLogger
Deprecation logging callback.
Definition: Database.php:66
Wikimedia\Rdbms\Database\$errorLogger
callable $errorLogger
Error logging callback.
Definition: Database.php:64
Wikimedia\Rdbms\Database\CONN_HOST
const CONN_HOST
Hostname or IP address to use on all connections.
Definition: Database.php:267
Wikimedia\Rdbms\Database\$conn
object resource null $conn
Database connection.
Definition: Database.php:77
Wikimedia\Rdbms\Database\doRollback
doRollback( $fname)
Issues the ROLLBACK command to the database server.
Definition: Database.php:5090
Wikimedia\Rdbms\Database\$lbInfo
array $lbInfo
Current LoadBalancer tracking information.
Definition: Database.php:108
Wikimedia\Rdbms\Database\getDBname
getDBname()
Get the current database name; null if there isn't one.
Definition: Database.php:3071
Wikimedia\Rdbms\Blob
Definition: Blob.php:9
Wikimedia\Rdbms\Database\getInfinity
getInfinity()
Find out when 'infinity' is.Most DBMSes support this. This is a special keyword for timestamps in Pos...
Definition: Database.php:5839
$type
$type
Definition: testCompression.php:52
Wikimedia\Rdbms\Database\doUpsert
doUpsert(string $table, array $rows, array $identityKey, array $set, string $fname)
Definition: Database.php:3661