rdbms: Restore debug toolbar "Queries" feature
[lhc/web/wiklou.git] / includes / libs / rdbms / database / Database.php
1 <?php
2 /**
3 * @defgroup Database Database
4 *
5 * This file deals with database interface functions
6 * and query specifics/optimisations.
7 *
8 * This program is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU General Public License as published by
10 * the Free Software Foundation; either version 2 of the License, or
11 * (at your option) any later version.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
17 *
18 * You should have received a copy of the GNU General Public License along
19 * with this program; if not, write to the Free Software Foundation, Inc.,
20 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
21 * http://www.gnu.org/copyleft/gpl.html
22 *
23 * @file
24 * @ingroup Database
25 */
26 namespace Wikimedia\Rdbms;
27
28 use Psr\Log\LoggerAwareInterface;
29 use Psr\Log\LoggerInterface;
30 use Psr\Log\NullLogger;
31 use Wikimedia\ScopedCallback;
32 use Wikimedia\Timestamp\ConvertibleTimestamp;
33 use Wikimedia\AtEase\AtEase;
34 use BagOStuff;
35 use HashBagOStuff;
36 use LogicException;
37 use InvalidArgumentException;
38 use UnexpectedValueException;
39 use Exception;
40 use RuntimeException;
41 use Throwable;
42
43 /**
44 * Relational database abstraction object
45 *
46 * @ingroup Database
47 * @since 1.28
48 */
49 abstract class Database implements IDatabase, IMaintainableDatabase, LoggerAwareInterface {
50 /** @var BagOStuff APC cache */
51 protected $srvCache;
52 /** @var LoggerInterface */
53 protected $connLogger;
54 /** @var LoggerInterface */
55 protected $queryLogger;
56 /** @var callable Error logging callback */
57 protected $errorLogger;
58 /** @var callable Deprecation logging callback */
59 protected $deprecationLogger;
60 /** @var callable|null */
61 protected $profiler;
62 /** @var TransactionProfiler */
63 protected $trxProfiler;
64
65 /** @var DatabaseDomain */
66 protected $currentDomain;
67
68 /** @var object|resource|null Database connection */
69 protected $conn;
70
71 /** @var IDatabase|null Lazy handle to the master DB this server replicates from */
72 private $lazyMasterHandle;
73
74 /** @var string Server that this instance is currently connected to */
75 protected $server;
76 /** @var string User that this instance is currently connected under the name of */
77 protected $user;
78 /** @var string Password used to establish the current connection */
79 protected $password;
80 /** @var bool Whether this PHP instance is for a CLI script */
81 protected $cliMode;
82 /** @var string Agent name for query profiling */
83 protected $agent;
84 /** @var array Parameters used by initConnection() to establish a connection */
85 protected $connectionParams;
86 /** @var string[]|int[]|float[] SQL variables values to use for all new connections */
87 protected $connectionVariables;
88 /** @var int Row batch size to use for emulated INSERT SELECT queries */
89 protected $nonNativeInsertSelectBatchSize;
90
91 /** @var int Current bit field of class DBO_* constants */
92 protected $flags;
93 /** @var array Current LoadBalancer tracking information */
94 protected $lbInfo = [];
95 /** @var string Current SQL query delimiter */
96 protected $delimiter = ';';
97 /** @var array[] Current map of (table => (dbname, schema, prefix) map) */
98 protected $tableAliases = [];
99 /** @var string[] Current map of (index alias => index) */
100 protected $indexAliases = [];
101 /** @var array|null Current variables use for schema element placeholders */
102 protected $schemaVars;
103
104 /** @var string|bool|null Stashed value of html_errors INI setting */
105 private $htmlErrors;
106 /** @var int[] Prior flags member variable values */
107 private $priorFlags = [];
108
109 /** @var array Map of (name => 1) for locks obtained via lock() */
110 protected $sessionNamedLocks = [];
111 /** @var array Map of (table name => 1) for TEMPORARY tables */
112 protected $sessionTempTables = [];
113
114 /** @var string ID of the active transaction or the empty string otherwise */
115 private $trxShortId = '';
116 /** @var int Transaction status */
117 private $trxStatus = self::STATUS_TRX_NONE;
118 /** @var Exception|null The last error that caused the status to become STATUS_TRX_ERROR */
119 private $trxStatusCause;
120 /** @var array|null Error details of the last statement-only rollback */
121 private $trxStatusIgnoredCause;
122 /** @var float|null UNIX timestamp at the time of BEGIN for the last transaction */
123 private $trxTimestamp = null;
124 /** @var float Replication lag estimate at the time of BEGIN for the last transaction */
125 private $trxReplicaLag = null;
126 /** @var string Name of the function that start the last transaction */
127 private $trxFname = null;
128 /** @var bool Whether possible write queries were done in the last transaction started */
129 private $trxDoneWrites = false;
130 /** @var bool Whether the current transaction was started implicitly due to DBO_TRX */
131 private $trxAutomatic = false;
132 /** @var int Counter for atomic savepoint identifiers (reset with each transaction) */
133 private $trxAtomicCounter = 0;
134 /** @var array List of (name, unique ID, savepoint ID) for each active atomic section level */
135 private $trxAtomicLevels = [];
136 /** @var bool Whether the current transaction was started implicitly by startAtomic() */
137 private $trxAutomaticAtomic = false;
138 /** @var string[] Write query callers of the current transaction */
139 private $trxWriteCallers = [];
140 /** @var float Seconds spent in write queries for the current transaction */
141 private $trxWriteDuration = 0.0;
142 /** @var int Number of write queries for the current transaction */
143 private $trxWriteQueryCount = 0;
144 /** @var int Number of rows affected by write queries for the current transaction */
145 private $trxWriteAffectedRows = 0;
146 /** @var float Like trxWriteQueryCount but excludes lock-bound, easy to replicate, queries */
147 private $trxWriteAdjDuration = 0.0;
148 /** @var int Number of write queries counted in trxWriteAdjDuration */
149 private $trxWriteAdjQueryCount = 0;
150 /** @var array[] List of (callable, method name, atomic section id) */
151 private $trxIdleCallbacks = [];
152 /** @var array[] List of (callable, method name, atomic section id) */
153 private $trxPreCommitCallbacks = [];
154 /** @var array[] List of (callable, method name, atomic section id) */
155 private $trxEndCallbacks = [];
156 /** @var array[] List of (callable, method name, atomic section id) */
157 private $trxSectionCancelCallbacks = [];
158 /** @var callable[] Map of (name => callable) */
159 private $trxRecurringCallbacks = [];
160 /** @var bool Whether to suppress triggering of transaction end callbacks */
161 private $trxEndCallbacksSuppressed = false;
162
163 /** @var integer|null Rows affected by the last query to query() or its CRUD wrappers */
164 protected $affectedRowCount;
165
166 /** @var float UNIX timestamp */
167 private $lastPing = 0.0;
168 /** @var string The last SQL query attempted */
169 private $lastQuery = '';
170 /** @var float|bool UNIX timestamp of last write query */
171 private $lastWriteTime = false;
172 /** @var string|bool */
173 private $lastPhpError = false;
174 /** @var float Query rount trip time estimate */
175 private $lastRoundTripEstimate = 0.0;
176
177 /** @var int|null Integer ID of the managing LBFactory instance or null if none */
178 private $ownerId;
179
180 /** @var string Lock granularity is on the level of the entire database */
181 const ATTR_DB_LEVEL_LOCKING = 'db-level-locking';
182 /** @var string The SCHEMA keyword refers to a grouping of tables in a database */
183 const ATTR_SCHEMAS_AS_TABLE_GROUPS = 'supports-schemas';
184
185 /** @var int New Database instance will not be connected yet when returned */
186 const NEW_UNCONNECTED = 0;
187 /** @var int New Database instance will already be connected when returned */
188 const NEW_CONNECTED = 1;
189
190 /** @var int Transaction is in a error state requiring a full or savepoint rollback */
191 const STATUS_TRX_ERROR = 1;
192 /** @var int Transaction is active and in a normal state */
193 const STATUS_TRX_OK = 2;
194 /** @var int No transaction is active */
195 const STATUS_TRX_NONE = 3;
196
197 /** @var string Idiom used when a cancelable atomic section started the transaction */
198 private static $NOT_APPLICABLE = 'n/a';
199 /** @var string Prefix to the atomic section counter used to make savepoint IDs */
200 private static $SAVEPOINT_PREFIX = 'wikimedia_rdbms_atomic';
201
202 /** @var int Writes to this temporary table do not affect lastDoneWrites() */
203 private static $TEMP_NORMAL = 1;
204 /** @var int Writes to this temporary table effect lastDoneWrites() */
205 private static $TEMP_PSEUDO_PERMANENT = 2;
206
207 /** @var int Number of times to re-try an operation in case of deadlock */
208 private static $DEADLOCK_TRIES = 4;
209 /** @var int Minimum time to wait before retry, in microseconds */
210 private static $DEADLOCK_DELAY_MIN = 500000;
211 /** @var int Maximum time to wait before retry */
212 private static $DEADLOCK_DELAY_MAX = 1500000;
213
214 /** @var int How long before it is worth doing a dummy query to test the connection */
215 private static $PING_TTL = 1.0;
216 /** @var string Dummy SQL query */
217 private static $PING_QUERY = 'SELECT 1 AS ping';
218
219 /** @var float Guess of how many seconds it takes to replicate a small insert */
220 private static $TINY_WRITE_SEC = 0.010;
221 /** @var float Consider a write slow if it took more than this many seconds */
222 private static $SLOW_WRITE_SEC = 0.500;
223 /** @var float Assume an insert of this many rows or less should be fast to replicate */
224 private static $SMALL_WRITE_ROWS = 100;
225
226 /** @var string[] List of DBO_* flags that can be changed after connection */
227 protected static $MUTABLE_FLAGS = [
228 'DBO_DEBUG',
229 'DBO_NOBUFFER',
230 'DBO_TRX',
231 'DBO_DDLMODE',
232 ];
233 /** @var int Bit field of all DBO_* flags that can be changed after connection */
234 protected static $DBO_MUTABLE = (
235 self::DBO_DEBUG | self::DBO_NOBUFFER | self::DBO_TRX | self::DBO_DDLMODE
236 );
237
238 /**
239 * @note exceptions for missing libraries/drivers should be thrown in initConnection()
240 * @param array $params Parameters passed from Database::factory()
241 */
242 public function __construct( array $params ) {
243 $this->connectionParams = [];
244 foreach ( [ 'host', 'user', 'password', 'dbname', 'schema', 'tablePrefix' ] as $name ) {
245 $this->connectionParams[$name] = $params[$name];
246 }
247 $this->connectionVariables = $params['variables'] ?? [];
248 $this->cliMode = $params['cliMode'];
249 $this->agent = $params['agent'];
250 $this->flags = $params['flags'];
251 if ( $this->flags & self::DBO_DEFAULT ) {
252 if ( $this->cliMode ) {
253 $this->flags &= ~self::DBO_TRX;
254 } else {
255 $this->flags |= self::DBO_TRX;
256 }
257 }
258 $this->nonNativeInsertSelectBatchSize = $params['nonNativeInsertSelectBatchSize'] ?? 10000;
259
260 $this->srvCache = $params['srvCache'] ?? new HashBagOStuff();
261 $this->profiler = is_callable( $params['profiler'] ) ? $params['profiler'] : null;
262 $this->trxProfiler = $params['trxProfiler'];
263 $this->connLogger = $params['connLogger'];
264 $this->queryLogger = $params['queryLogger'];
265 $this->errorLogger = $params['errorLogger'];
266 $this->deprecationLogger = $params['deprecationLogger'];
267
268 // Set initial dummy domain until open() sets the final DB/prefix
269 $this->currentDomain = new DatabaseDomain(
270 $params['dbname'] != '' ? $params['dbname'] : null,
271 $params['schema'] != '' ? $params['schema'] : null,
272 $params['tablePrefix']
273 );
274
275 $this->ownerId = $params['ownerId'] ?? null;
276 }
277
278 /**
279 * Initialize the connection to the database over the wire (or to local files)
280 *
281 * @throws LogicException
282 * @throws InvalidArgumentException
283 * @throws DBConnectionError
284 * @since 1.31
285 */
286 final public function initConnection() {
287 if ( $this->isOpen() ) {
288 throw new LogicException( __METHOD__ . ': already connected' );
289 }
290 // Establish the connection
291 $this->doInitConnection();
292 }
293
294 /**
295 * Actually connect to the database over the wire (or to local files)
296 *
297 * @throws DBConnectionError
298 * @since 1.31
299 */
300 protected function doInitConnection() {
301 $this->open(
302 $this->connectionParams['host'],
303 $this->connectionParams['user'],
304 $this->connectionParams['password'],
305 $this->connectionParams['dbname'],
306 $this->connectionParams['schema'],
307 $this->connectionParams['tablePrefix']
308 );
309 }
310
311 /**
312 * Open a new connection to the database (closing any existing one)
313 *
314 * @param string|null $server Database server host
315 * @param string|null $user Database user name
316 * @param string|null $password Database user password
317 * @param string|null $dbName Database name
318 * @param string|null $schema Database schema name
319 * @param string $tablePrefix Table prefix
320 * @throws DBConnectionError
321 */
322 abstract protected function open( $server, $user, $password, $dbName, $schema, $tablePrefix );
323
324 /**
325 * Construct a Database subclass instance given a database type and parameters
326 *
327 * This also connects to the database immediately upon object construction
328 *
329 * @param string $type A possible DB type (sqlite, mysql, postgres,...)
330 * @param array $params Parameter map with keys:
331 * - host : The hostname of the DB server
332 * - user : The name of the database user the client operates under
333 * - password : The password for the database user
334 * - dbname : The name of the database to use where queries do not specify one.
335 * The database must exist or an error might be thrown. Setting this to the empty string
336 * will avoid any such errors and make the handle have no implicit database scope. This is
337 * useful for queries like SHOW STATUS, CREATE DATABASE, or DROP DATABASE. Note that a
338 * "database" in Postgres is rougly equivalent to an entire MySQL server. This the domain
339 * in which user names and such are defined, e.g. users are database-specific in Postgres.
340 * - schema : The database schema to use (if supported). A "schema" in Postgres is roughly
341 * equivalent to a "database" in MySQL. Note that MySQL and SQLite do not use schemas.
342 * - tablePrefix : Optional table prefix that is implicitly added on to all table names
343 * recognized in queries. This can be used in place of schemas for handle site farms.
344 * - flags : Optional bit field of DBO_* constants that define connection, protocol,
345 * buffering, and transaction behavior. It is STRONGLY adviced to leave the DBO_DEFAULT
346 * flag in place UNLESS this this database simply acts as a key/value store.
347 * - driver: Optional name of a specific DB client driver. For MySQL, there is only the
348 * 'mysqli' driver; the old one 'mysql' has been removed.
349 * - variables: Optional map of session variables to set after connecting. This can be
350 * used to adjust lock timeouts or encoding modes and the like.
351 * - connLogger: Optional PSR-3 logger interface instance.
352 * - queryLogger: Optional PSR-3 logger interface instance.
353 * - profiler : Optional callback that takes a section name argument and returns
354 * a ScopedCallback instance that ends the profile section in its destructor.
355 * These will be called in query(), using a simplified version of the SQL that
356 * also includes the agent as a SQL comment.
357 * - trxProfiler: Optional TransactionProfiler instance.
358 * - errorLogger: Optional callback that takes an Exception and logs it.
359 * - deprecationLogger: Optional callback that takes a string and logs it.
360 * - cliMode: Whether to consider the execution context that of a CLI script.
361 * - agent: Optional name used to identify the end-user in query profiling/logging.
362 * - srvCache: Optional BagOStuff instance to an APC-style cache.
363 * - nonNativeInsertSelectBatchSize: Optional batch size for non-native INSERT SELECT.
364 * - ownerId: Optional integer ID of a LoadBalancer instance that manages this instance.
365 * @param int $connect One of the class constants (NEW_CONNECTED, NEW_UNCONNECTED) [optional]
366 * @return Database|null If the database driver or extension cannot be found
367 * @throws InvalidArgumentException If the database driver or extension cannot be found
368 * @since 1.18
369 */
370 final public static function factory( $type, $params = [], $connect = self::NEW_CONNECTED ) {
371 $class = self::getClass( $type, $params['driver'] ?? null );
372
373 if ( class_exists( $class ) && is_subclass_of( $class, IDatabase::class ) ) {
374 $params += [
375 'host' => null,
376 'user' => null,
377 'password' => null,
378 'dbname' => null,
379 'schema' => null,
380 'tablePrefix' => '',
381 'flags' => 0,
382 'variables' => [],
383 'cliMode' => ( PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg' ),
384 'agent' => basename( $_SERVER['SCRIPT_NAME'] ) . '@' . gethostname(),
385 'ownerId' => null
386 ];
387
388 $normalizedParams = [
389 // Configuration
390 'host' => strlen( $params['host'] ) ? $params['host'] : null,
391 'user' => strlen( $params['user'] ) ? $params['user'] : null,
392 'password' => is_string( $params['password'] ) ? $params['password'] : null,
393 'dbname' => strlen( $params['dbname'] ) ? $params['dbname'] : null,
394 'schema' => strlen( $params['schema'] ) ? $params['schema'] : null,
395 'tablePrefix' => (string)$params['tablePrefix'],
396 'flags' => (int)$params['flags'],
397 'variables' => $params['variables'],
398 'cliMode' => (bool)$params['cliMode'],
399 'agent' => (string)$params['agent'],
400 // Objects and callbacks
401 'srvCache' => $params['srvCache'] ?? new HashBagOStuff(),
402 'profiler' => $params['profiler'] ?? null,
403 'trxProfiler' => $params['trxProfiler'] ?? new TransactionProfiler(),
404 'connLogger' => $params['connLogger'] ?? new NullLogger(),
405 'queryLogger' => $params['queryLogger'] ?? new NullLogger(),
406 'errorLogger' => $params['errorLogger'] ?? function ( Exception $e ) {
407 trigger_error( get_class( $e ) . ': ' . $e->getMessage(), E_USER_WARNING );
408 },
409 'deprecationLogger' => $params['deprecationLogger'] ?? function ( $msg ) {
410 trigger_error( $msg, E_USER_DEPRECATED );
411 }
412 ] + $params;
413
414 /** @var Database $conn */
415 $conn = new $class( $normalizedParams );
416 if ( $connect === self::NEW_CONNECTED ) {
417 $conn->initConnection();
418 }
419 } else {
420 $conn = null;
421 }
422
423 return $conn;
424 }
425
426 /**
427 * @param string $dbType A possible DB type (sqlite, mysql, postgres,...)
428 * @param string|null $driver Optional name of a specific DB client driver
429 * @return array Map of (Database::ATTR_* constant => value) for all such constants
430 * @throws InvalidArgumentException
431 * @since 1.31
432 */
433 final public static function attributesFromType( $dbType, $driver = null ) {
434 static $defaults = [
435 self::ATTR_DB_LEVEL_LOCKING => false,
436 self::ATTR_SCHEMAS_AS_TABLE_GROUPS => false
437 ];
438
439 $class = self::getClass( $dbType, $driver );
440
441 return call_user_func( [ $class, 'getAttributes' ] ) + $defaults;
442 }
443
444 /**
445 * @param string $dbType A possible DB type (sqlite, mysql, postgres,...)
446 * @param string|null $driver Optional name of a specific DB client driver
447 * @return string Database subclass name to use
448 * @throws InvalidArgumentException
449 */
450 private static function getClass( $dbType, $driver = null ) {
451 // For database types with built-in support, the below maps type to IDatabase
452 // implementations. For types with multipe driver implementations (PHP extensions),
453 // an array can be used, keyed by extension name. In case of an array, the
454 // optional 'driver' parameter can be used to force a specific driver. Otherwise,
455 // we auto-detect the first available driver. For types without built-in support,
456 // an class named "Database<Type>" us used, eg. DatabaseFoo for type 'foo'.
457 static $builtinTypes = [
458 'mysql' => [ 'mysqli' => DatabaseMysqli::class ],
459 'sqlite' => DatabaseSqlite::class,
460 'postgres' => DatabasePostgres::class,
461 ];
462
463 $dbType = strtolower( $dbType );
464 $class = false;
465
466 if ( isset( $builtinTypes[$dbType] ) ) {
467 $possibleDrivers = $builtinTypes[$dbType];
468 if ( is_string( $possibleDrivers ) ) {
469 $class = $possibleDrivers;
470 } elseif ( (string)$driver !== '' ) {
471 if ( !isset( $possibleDrivers[$driver] ) ) {
472 throw new InvalidArgumentException( __METHOD__ .
473 " type '$dbType' does not support driver '{$driver}'" );
474 }
475
476 $class = $possibleDrivers[$driver];
477 } else {
478 foreach ( $possibleDrivers as $posDriver => $possibleClass ) {
479 if ( extension_loaded( $posDriver ) ) {
480 $class = $possibleClass;
481 break;
482 }
483 }
484 }
485 } else {
486 $class = 'Database' . ucfirst( $dbType );
487 }
488
489 if ( $class === false ) {
490 throw new InvalidArgumentException( __METHOD__ .
491 " no viable database extension found for type '$dbType'" );
492 }
493
494 return $class;
495 }
496
497 /**
498 * @return array Map of (Database::ATTR_* constant => value)
499 * @since 1.31
500 */
501 protected static function getAttributes() {
502 return [];
503 }
504
505 /**
506 * Set the PSR-3 logger interface to use for query logging. (The logger
507 * interfaces for connection logging and error logging can be set with the
508 * constructor.)
509 *
510 * @param LoggerInterface $logger
511 */
512 public function setLogger( LoggerInterface $logger ) {
513 $this->queryLogger = $logger;
514 }
515
516 public function getServerInfo() {
517 return $this->getServerVersion();
518 }
519
520 /**
521 * Backwards-compatibility no-op method for disabling query buffering
522 *
523 * @param null|bool $buffer Whether to buffer queries (ignored)
524 * @return bool Whether buffering was already enabled (always true)
525 * @deprecated Since 1.34 Use query batching; this no longer does anything
526 */
527 public function bufferResults( $buffer = null ) {
528 return true;
529 }
530
531 final public function trxLevel() {
532 return ( $this->trxShortId != '' ) ? 1 : 0;
533 }
534
535 public function trxTimestamp() {
536 return $this->trxLevel() ? $this->trxTimestamp : null;
537 }
538
539 /**
540 * @return int One of the STATUS_TRX_* class constants
541 * @since 1.31
542 */
543 public function trxStatus() {
544 return $this->trxStatus;
545 }
546
547 public function tablePrefix( $prefix = null ) {
548 $old = $this->currentDomain->getTablePrefix();
549 if ( $prefix !== null ) {
550 $this->currentDomain = new DatabaseDomain(
551 $this->currentDomain->getDatabase(),
552 $this->currentDomain->getSchema(),
553 $prefix
554 );
555 }
556
557 return $old;
558 }
559
560 public function dbSchema( $schema = null ) {
561 if ( strlen( $schema ) && $this->getDBname() === null ) {
562 throw new DBUnexpectedError( $this, "Cannot set schema to '$schema'; no database set" );
563 }
564
565 $old = $this->currentDomain->getSchema();
566 if ( $schema !== null ) {
567 $this->currentDomain = new DatabaseDomain(
568 $this->currentDomain->getDatabase(),
569 // DatabaseDomain uses null for unspecified schemas
570 strlen( $schema ) ? $schema : null,
571 $this->currentDomain->getTablePrefix()
572 );
573 }
574
575 return (string)$old;
576 }
577
578 /**
579 * @return string Schema to use to qualify relations in queries
580 */
581 protected function relationSchemaQualifier() {
582 return $this->dbSchema();
583 }
584
585 public function getLBInfo( $name = null ) {
586 if ( is_null( $name ) ) {
587 return $this->lbInfo;
588 }
589
590 if ( array_key_exists( $name, $this->lbInfo ) ) {
591 return $this->lbInfo[$name];
592 }
593
594 return null;
595 }
596
597 public function setLBInfo( $nameOrArray, $value = null ) {
598 if ( is_array( $nameOrArray ) ) {
599 $this->lbInfo = $nameOrArray;
600 } elseif ( is_string( $nameOrArray ) ) {
601 if ( $value !== null ) {
602 $this->lbInfo[$nameOrArray] = $value;
603 } else {
604 unset( $this->lbInfo[$nameOrArray] );
605 }
606 } else {
607 throw new InvalidArgumentException( "Got non-string key" );
608 }
609 }
610
611 public function setLazyMasterHandle( IDatabase $conn ) {
612 $this->lazyMasterHandle = $conn;
613 }
614
615 /**
616 * @return IDatabase|null
617 * @see setLazyMasterHandle()
618 * @since 1.27
619 */
620 protected function getLazyMasterHandle() {
621 return $this->lazyMasterHandle;
622 }
623
624 public function implicitOrderby() {
625 return true;
626 }
627
628 public function lastQuery() {
629 return $this->lastQuery;
630 }
631
632 public function lastDoneWrites() {
633 return $this->lastWriteTime ?: false;
634 }
635
636 public function writesPending() {
637 return $this->trxLevel() && $this->trxDoneWrites;
638 }
639
640 public function writesOrCallbacksPending() {
641 return $this->trxLevel() && (
642 $this->trxDoneWrites ||
643 $this->trxIdleCallbacks ||
644 $this->trxPreCommitCallbacks ||
645 $this->trxEndCallbacks ||
646 $this->trxSectionCancelCallbacks
647 );
648 }
649
650 public function preCommitCallbacksPending() {
651 return $this->trxLevel() && $this->trxPreCommitCallbacks;
652 }
653
654 /**
655 * @return string|null
656 */
657 final protected function getTransactionRoundId() {
658 // If transaction round participation is enabled, see if one is active
659 if ( $this->getFlag( self::DBO_TRX ) ) {
660 $id = $this->getLBInfo( 'trxRoundId' );
661
662 return is_string( $id ) ? $id : null;
663 }
664
665 return null;
666 }
667
668 public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL ) {
669 if ( !$this->trxLevel() ) {
670 return false;
671 } elseif ( !$this->trxDoneWrites ) {
672 return 0.0;
673 }
674
675 switch ( $type ) {
676 case self::ESTIMATE_DB_APPLY:
677 return $this->pingAndCalculateLastTrxApplyTime();
678 default: // everything
679 return $this->trxWriteDuration;
680 }
681 }
682
683 /**
684 * @return float Time to apply writes to replicas based on trxWrite* fields
685 */
686 private function pingAndCalculateLastTrxApplyTime() {
687 $this->ping( $rtt );
688
689 $rttAdjTotal = $this->trxWriteAdjQueryCount * $rtt;
690 $applyTime = max( $this->trxWriteAdjDuration - $rttAdjTotal, 0 );
691 // For omitted queries, make them count as something at least
692 $omitted = $this->trxWriteQueryCount - $this->trxWriteAdjQueryCount;
693 $applyTime += self::$TINY_WRITE_SEC * $omitted;
694
695 return $applyTime;
696 }
697
698 public function pendingWriteCallers() {
699 return $this->trxLevel() ? $this->trxWriteCallers : [];
700 }
701
702 public function pendingWriteRowsAffected() {
703 return $this->trxWriteAffectedRows;
704 }
705
706 /**
707 * List the methods that have write queries or callbacks for the current transaction
708 *
709 * This method should not be used outside of Database/LoadBalancer
710 *
711 * @return string[]
712 * @since 1.32
713 */
714 public function pendingWriteAndCallbackCallers() {
715 $fnames = $this->pendingWriteCallers();
716 foreach ( [
717 $this->trxIdleCallbacks,
718 $this->trxPreCommitCallbacks,
719 $this->trxEndCallbacks,
720 $this->trxSectionCancelCallbacks
721 ] as $callbacks ) {
722 foreach ( $callbacks as $callback ) {
723 $fnames[] = $callback[1];
724 }
725 }
726
727 return $fnames;
728 }
729
730 /**
731 * @return string
732 */
733 private function flatAtomicSectionList() {
734 return array_reduce( $this->trxAtomicLevels, function ( $accum, $v ) {
735 return $accum === null ? $v[0] : "$accum, " . $v[0];
736 } );
737 }
738
739 public function isOpen() {
740 return (bool)$this->conn;
741 }
742
743 public function setFlag( $flag, $remember = self::REMEMBER_NOTHING ) {
744 if ( $flag & ~static::$DBO_MUTABLE ) {
745 throw new DBUnexpectedError(
746 $this,
747 "Got $flag (allowed: " . implode( ', ', static::$MUTABLE_FLAGS ) . ')'
748 );
749 }
750
751 if ( $remember === self::REMEMBER_PRIOR ) {
752 array_push( $this->priorFlags, $this->flags );
753 }
754
755 $this->flags |= $flag;
756 }
757
758 public function clearFlag( $flag, $remember = self::REMEMBER_NOTHING ) {
759 if ( $flag & ~static::$DBO_MUTABLE ) {
760 throw new DBUnexpectedError(
761 $this,
762 "Got $flag (allowed: " . implode( ', ', static::$MUTABLE_FLAGS ) . ')'
763 );
764 }
765
766 if ( $remember === self::REMEMBER_PRIOR ) {
767 array_push( $this->priorFlags, $this->flags );
768 }
769
770 $this->flags &= ~$flag;
771 }
772
773 public function restoreFlags( $state = self::RESTORE_PRIOR ) {
774 if ( !$this->priorFlags ) {
775 return;
776 }
777
778 if ( $state === self::RESTORE_INITIAL ) {
779 $this->flags = reset( $this->priorFlags );
780 $this->priorFlags = [];
781 } else {
782 $this->flags = array_pop( $this->priorFlags );
783 }
784 }
785
786 public function getFlag( $flag ) {
787 return ( ( $this->flags & $flag ) === $flag );
788 }
789
790 public function getDomainID() {
791 return $this->currentDomain->getId();
792 }
793
794 /**
795 * Get information about an index into an object
796 * @param string $table Table name
797 * @param string $index Index name
798 * @param string $fname Calling function name
799 * @return mixed Database-specific index description class or false if the index does not exist
800 */
801 abstract function indexInfo( $table, $index, $fname = __METHOD__ );
802
803 /**
804 * Wrapper for addslashes()
805 *
806 * @param string $s String to be slashed.
807 * @return string Slashed string.
808 */
809 abstract function strencode( $s );
810
811 /**
812 * Set a custom error handler for logging errors during database connection
813 */
814 protected function installErrorHandler() {
815 $this->lastPhpError = false;
816 $this->htmlErrors = ini_set( 'html_errors', '0' );
817 set_error_handler( [ $this, 'connectionErrorLogger' ] );
818 }
819
820 /**
821 * Restore the previous error handler and return the last PHP error for this DB
822 *
823 * @return bool|string
824 */
825 protected function restoreErrorHandler() {
826 restore_error_handler();
827 if ( $this->htmlErrors !== false ) {
828 ini_set( 'html_errors', $this->htmlErrors );
829 }
830
831 return $this->getLastPHPError();
832 }
833
834 /**
835 * @return string|bool Last PHP error for this DB (typically connection errors)
836 */
837 protected function getLastPHPError() {
838 if ( $this->lastPhpError ) {
839 $error = preg_replace( '!\[<a.*</a>\]!', '', $this->lastPhpError );
840 $error = preg_replace( '!^.*?:\s?(.*)$!', '$1', $error );
841
842 return $error;
843 }
844
845 return false;
846 }
847
848 /**
849 * Error handler for logging errors during database connection
850 * This method should not be used outside of Database classes
851 *
852 * @param int $errno
853 * @param string $errstr
854 */
855 public function connectionErrorLogger( $errno, $errstr ) {
856 $this->lastPhpError = $errstr;
857 }
858
859 /**
860 * Create a log context to pass to PSR-3 logger functions.
861 *
862 * @param array $extras Additional data to add to context
863 * @return array
864 */
865 protected function getLogContext( array $extras = [] ) {
866 return array_merge(
867 [
868 'db_server' => $this->server,
869 'db_name' => $this->getDBname(),
870 'db_user' => $this->user,
871 ],
872 $extras
873 );
874 }
875
876 final public function close( $fname = __METHOD__, $owner = null ) {
877 $error = null; // error to throw after disconnecting
878
879 $wasOpen = (bool)$this->conn;
880 // This should mostly do nothing if the connection is already closed
881 if ( $this->conn ) {
882 // Roll back any dangling transaction first
883 if ( $this->trxLevel() ) {
884 if ( $this->trxAtomicLevels ) {
885 // Cannot let incomplete atomic sections be committed
886 $levels = $this->flatAtomicSectionList();
887 $error = "$fname: atomic sections $levels are still open";
888 } elseif ( $this->trxAutomatic ) {
889 // Only the connection manager can commit non-empty DBO_TRX transactions
890 // (empty ones we can silently roll back)
891 if ( $this->writesOrCallbacksPending() ) {
892 $error = "$fname: " .
893 "expected mass rollback of all peer transactions (DBO_TRX set)";
894 }
895 } else {
896 // Manual transactions should have been committed or rolled
897 // back, even if empty.
898 $error = "$fname: transaction is still open (from {$this->trxFname})";
899 }
900
901 if ( $this->trxEndCallbacksSuppressed && $error === null ) {
902 $error = "$fname: callbacks are suppressed; cannot properly commit";
903 }
904
905 // Rollback the changes and run any callbacks as needed
906 $this->rollback( __METHOD__, self::FLUSHING_INTERNAL );
907 }
908
909 // Close the actual connection in the binding handle
910 $closed = $this->closeConnection();
911 } else {
912 $closed = true; // already closed; nothing to do
913 }
914
915 $this->conn = null;
916
917 // Log or throw any unexpected errors after having disconnected
918 if ( $error !== null ) {
919 // T217819, T231443: if this is probably just LoadBalancer trying to recover from
920 // errors and shutdown, then log any problems and move on since the request has to
921 // end one way or another. Throwing errors is not very useful at some point.
922 if ( $this->ownerId !== null && $owner === $this->ownerId ) {
923 $this->queryLogger->error( $error );
924 } else {
925 throw new DBUnexpectedError( $this, $error );
926 }
927 }
928
929 // Note that various subclasses call close() at the start of open(), which itself is
930 // called by replaceLostConnection(). In that case, just because onTransactionResolution()
931 // callbacks are pending does not mean that an exception should be thrown. Rather, they
932 // will be executed after the reconnection step.
933 if ( $wasOpen ) {
934 // Sanity check that no callbacks are dangling
935 $fnames = $this->pendingWriteAndCallbackCallers();
936 if ( $fnames ) {
937 throw new RuntimeException(
938 "Transaction callbacks are still pending: " . implode( ', ', $fnames )
939 );
940 }
941 }
942
943 return $closed;
944 }
945
946 /**
947 * Make sure there is an open connection handle (alive or not) as a sanity check
948 *
949 * This guards against fatal errors to the binding handle not being defined
950 * in cases where open() was never called or close() was already called
951 *
952 * @throws DBUnexpectedError
953 */
954 final protected function assertHasConnectionHandle() {
955 if ( !$this->isOpen() ) {
956 throw new DBUnexpectedError( $this, "DB connection was already closed" );
957 }
958 }
959
960 /**
961 * Make sure that this server is not marked as a replica nor read-only as a sanity check
962 *
963 * @throws DBReadOnlyRoleError
964 * @throws DBReadOnlyError
965 */
966 protected function assertIsWritableMaster() {
967 if ( $this->getLBInfo( 'replica' ) ) {
968 throw new DBReadOnlyRoleError(
969 $this,
970 'Write operations are not allowed on replica database connections'
971 );
972 }
973 $reason = $this->getReadOnlyReason();
974 if ( $reason !== false ) {
975 throw new DBReadOnlyError( $this, "Database is read-only: $reason" );
976 }
977 }
978
979 /**
980 * Closes underlying database connection
981 * @since 1.20
982 * @return bool Whether connection was closed successfully
983 */
984 abstract protected function closeConnection();
985
986 /**
987 * Run a query and return a DBMS-dependent wrapper or boolean
988 *
989 * This is meant to handle the basic command of actually sending a query to the
990 * server via the driver. No implicit transaction, reconnection, nor retry logic
991 * should happen here. The higher level query() method is designed to handle those
992 * sorts of concerns. This method should not trigger such higher level methods.
993 *
994 * The lastError() and lastErrno() methods should meaningfully reflect what error,
995 * if any, occured during the last call to this method. Methods like executeQuery(),
996 * query(), select(), insert(), update(), delete(), and upsert() implement their calls
997 * to doQuery() such that an immediately subsequent call to lastError()/lastErrno()
998 * meaningfully reflects any error that occured during that public query method call.
999 *
1000 * For SELECT queries, this returns either:
1001 * - a) A driver-specific value/resource, only on success. This can be iterated
1002 * over by calling fetchObject()/fetchRow() until there are no more rows.
1003 * Alternatively, the result can be passed to resultObject() to obtain an
1004 * IResultWrapper instance which can then be iterated over via "foreach".
1005 * - b) False, on any query failure
1006 *
1007 * For non-SELECT queries, this returns either:
1008 * - a) A driver-specific value/resource, only on success
1009 * - b) True, only on success (e.g. no meaningful result other than "OK")
1010 * - c) False, on any query failure
1011 *
1012 * @param string $sql SQL query
1013 * @return mixed|bool An object, resource, or true on success; false on failure
1014 */
1015 abstract protected function doQuery( $sql );
1016
1017 /**
1018 * Determine whether a query writes to the DB. When in doubt, this returns true.
1019 *
1020 * Main use cases:
1021 *
1022 * - Subsequent web requests should not need to wait for replication from
1023 * the master position seen by this web request, unless this request made
1024 * changes to the master. This is handled by ChronologyProtector by checking
1025 * doneWrites() at the end of the request. doneWrites() returns true if any
1026 * query set lastWriteTime; which query() does based on isWriteQuery().
1027 *
1028 * - Reject write queries to replica DBs, in query().
1029 *
1030 * @param string $sql
1031 * @return bool
1032 */
1033 protected function isWriteQuery( $sql ) {
1034 // BEGIN and COMMIT queries are considered read queries here.
1035 // Database backends and drivers (MySQL, MariaDB, php-mysqli) generally
1036 // treat these as write queries, in that their results have "affected rows"
1037 // as meta data as from writes, instead of "num rows" as from reads.
1038 // But, we treat them as read queries because when reading data (from
1039 // either replica or master) we use transactions to enable repeatable-read
1040 // snapshots, which ensures we get consistent results from the same snapshot
1041 // for all queries within a request. Use cases:
1042 // - Treating these as writes would trigger ChronologyProtector (see method doc).
1043 // - We use this method to reject writes to replicas, but we need to allow
1044 // use of transactions on replicas for read snapshots. This is fine given
1045 // that transactions by themselves don't make changes, only actual writes
1046 // within the transaction matter, which we still detect.
1047 return !preg_match(
1048 '/^(?:SELECT|BEGIN|ROLLBACK|COMMIT|SAVEPOINT|RELEASE|SET|SHOW|EXPLAIN|USE|\(SELECT)\b/i',
1049 $sql
1050 );
1051 }
1052
1053 /**
1054 * @param string $sql
1055 * @return string|null
1056 */
1057 protected function getQueryVerb( $sql ) {
1058 return preg_match( '/^\s*([a-z]+)/i', $sql, $m ) ? strtoupper( $m[1] ) : null;
1059 }
1060
1061 /**
1062 * Determine whether a SQL statement is sensitive to isolation level.
1063 *
1064 * A SQL statement is considered transactable if its result could vary
1065 * depending on the transaction isolation level. Operational commands
1066 * such as 'SET' and 'SHOW' are not considered to be transactable.
1067 *
1068 * Main purpose: Used by query() to decide whether to begin a transaction
1069 * before the current query (in DBO_TRX mode, on by default).
1070 *
1071 * @param string $sql
1072 * @return bool
1073 */
1074 protected function isTransactableQuery( $sql ) {
1075 return !in_array(
1076 $this->getQueryVerb( $sql ),
1077 [ 'BEGIN', 'ROLLBACK', 'COMMIT', 'SET', 'SHOW', 'CREATE', 'ALTER', 'USE', 'SHOW' ],
1078 true
1079 );
1080 }
1081
1082 /**
1083 * @param string $sql A SQL query
1084 * @param bool $pseudoPermanent Treat any table from CREATE TEMPORARY as pseudo-permanent
1085 * @return array A n-tuple of:
1086 * - int|null: A self::TEMP_* constant for temp table operations or null otherwise
1087 * - string|null: The name of the new temporary table $sql creates, or null
1088 * - string|null: The name of the temporary table that $sql drops, or null
1089 */
1090 protected function getTempWrites( $sql, $pseudoPermanent ) {
1091 static $qt = '[`"\']?(\w+)[`"\']?'; // quoted table
1092
1093 if ( preg_match(
1094 '/^CREATE\s+TEMPORARY\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?' . $qt . '/i',
1095 $sql,
1096 $matches
1097 ) ) {
1098 $type = $pseudoPermanent ? self::$TEMP_PSEUDO_PERMANENT : self::$TEMP_NORMAL;
1099
1100 return [ $type, $matches[1], null ];
1101 } elseif ( preg_match(
1102 '/^DROP\s+(?:TEMPORARY\s+)?TABLE\s+(?:IF\s+EXISTS\s+)?' . $qt . '/i',
1103 $sql,
1104 $matches
1105 ) ) {
1106 return [ $this->sessionTempTables[$matches[1]] ?? null, null, $matches[1] ];
1107 } elseif ( preg_match(
1108 '/^TRUNCATE\s+(?:TEMPORARY\s+)?TABLE\s+(?:IF\s+EXISTS\s+)?' . $qt . '/i',
1109 $sql,
1110 $matches
1111 ) ) {
1112 return [ $this->sessionTempTables[$matches[1]] ?? null, null, null ];
1113 } elseif ( preg_match(
1114 '/^(?:(?:INSERT|REPLACE)\s+(?:\w+\s+)?INTO|UPDATE|DELETE\s+FROM)\s+' . $qt . '/i',
1115 $sql,
1116 $matches
1117 ) ) {
1118 return [ $this->sessionTempTables[$matches[1]] ?? null, null, null ];
1119 }
1120
1121 return [ null, null, null ];
1122 }
1123
1124 /**
1125 * @param IResultWrapper|bool $ret
1126 * @param int|null $tmpType TEMP_NORMAL or TEMP_PSEUDO_PERMANENT
1127 * @param string|null $tmpNew Name of created temp table
1128 * @param string|null $tmpDel Name of dropped temp table
1129 */
1130 protected function registerTempWrites( $ret, $tmpType, $tmpNew, $tmpDel ) {
1131 if ( $ret !== false ) {
1132 if ( $tmpNew !== null ) {
1133 $this->sessionTempTables[$tmpNew] = $tmpType;
1134 }
1135 if ( $tmpDel !== null ) {
1136 unset( $this->sessionTempTables[$tmpDel] );
1137 }
1138 }
1139 }
1140
1141 public function query( $sql, $fname = __METHOD__, $flags = 0 ) {
1142 $flags = (int)$flags; // b/c; this field used to be a bool
1143 // Sanity check that the SQL query is appropriate in the current context and is
1144 // allowed for an outside caller (e.g. does not break transaction/session tracking).
1145 $this->assertQueryIsCurrentlyAllowed( $sql, $fname );
1146
1147 // Send the query to the server and fetch any corresponding errors
1148 list( $ret, $err, $errno, $unignorable ) = $this->executeQuery( $sql, $fname, $flags );
1149 if ( $ret === false ) {
1150 $ignoreErrors = $this->fieldHasBit( $flags, self::QUERY_SILENCE_ERRORS );
1151 // Throw an error unless both the ignore flag was set and a rollback is not needed
1152 $this->reportQueryError( $err, $errno, $sql, $fname, $ignoreErrors && !$unignorable );
1153 }
1154
1155 return $this->resultObject( $ret );
1156 }
1157
1158 /**
1159 * Execute a query, retrying it if there is a recoverable connection loss
1160 *
1161 * This is similar to query() except:
1162 * - It does not prevent all non-ROLLBACK queries if there is a corrupted transaction
1163 * - It does not disallow raw queries that are supposed to use dedicated IDatabase methods
1164 * - It does not throw exceptions for common error cases
1165 *
1166 * This is meant for internal use with Database subclasses.
1167 *
1168 * @param string $sql Original SQL query
1169 * @param string $fname Name of the calling function
1170 * @param int $flags Bit field of class QUERY_* constants
1171 * @return array An n-tuple of:
1172 * - mixed|bool: An object, resource, or true on success; false on failure
1173 * - string: The result of calling lastError()
1174 * - int: The result of calling lastErrno()
1175 * - bool: Whether a rollback is needed to allow future non-rollback queries
1176 * @throws DBUnexpectedError
1177 */
1178 final protected function executeQuery( $sql, $fname, $flags ) {
1179 $this->assertHasConnectionHandle();
1180
1181 $priorTransaction = $this->trxLevel();
1182
1183 if ( $this->isWriteQuery( $sql ) ) {
1184 // In theory, non-persistent writes are allowed in read-only mode, but due to things
1185 // like https://bugs.mysql.com/bug.php?id=33669 that might not work anyway...
1186 $this->assertIsWritableMaster();
1187 // Do not treat temporary table writes as "meaningful writes" since they are only
1188 // visible to one session and are not permanent. Profile them as reads. Integration
1189 // tests can override this behavior via $flags.
1190 $pseudoPermanent = $this->fieldHasBit( $flags, self::QUERY_PSEUDO_PERMANENT );
1191 list( $tmpType, $tmpNew, $tmpDel ) = $this->getTempWrites( $sql, $pseudoPermanent );
1192 $isPermWrite = ( $tmpType !== self::$TEMP_NORMAL );
1193 // DBConnRef uses QUERY_REPLICA_ROLE to enforce the replica role for raw SQL queries
1194 if ( $isPermWrite && $this->fieldHasBit( $flags, self::QUERY_REPLICA_ROLE ) ) {
1195 throw new DBReadOnlyRoleError( $this, "Cannot write; target role is DB_REPLICA" );
1196 }
1197 } else {
1198 // No permanent writes in this query
1199 $isPermWrite = false;
1200 // No temporary tables written to either
1201 list( $tmpType, $tmpNew, $tmpDel ) = [ null, null, null ];
1202 }
1203
1204 // Add trace comment to the begin of the sql string, right after the operator.
1205 // Or, for one-word queries (like "BEGIN" or COMMIT") add it to the end (T44598).
1206 $encAgent = str_replace( '/', '-', $this->agent );
1207 $commentedSql = preg_replace( '/\s|$/', " /* $fname $encAgent */ ", $sql, 1 );
1208
1209 // Send the query to the server and fetch any corresponding errors.
1210 // This also doubles as a "ping" to see if the connection was dropped.
1211 list( $ret, $err, $errno, $recoverableSR, $recoverableCL, $reconnected ) =
1212 $this->executeQueryAttempt( $sql, $commentedSql, $isPermWrite, $fname, $flags );
1213
1214 // Check if the query failed due to a recoverable connection loss
1215 $allowRetry = !$this->fieldHasBit( $flags, self::QUERY_NO_RETRY );
1216 if ( $ret === false && $recoverableCL && $reconnected && $allowRetry ) {
1217 // Silently resend the query to the server since it is safe and possible
1218 list( $ret, $err, $errno, $recoverableSR, $recoverableCL ) =
1219 $this->executeQueryAttempt( $sql, $commentedSql, $isPermWrite, $fname, $flags );
1220 }
1221
1222 // Register creation and dropping of temporary tables
1223 $this->registerTempWrites( $ret, $tmpType, $tmpNew, $tmpDel );
1224
1225 $corruptedTrx = false;
1226
1227 if ( $ret === false ) {
1228 if ( $priorTransaction ) {
1229 if ( $recoverableSR ) {
1230 # We're ignoring an error that caused just the current query to be aborted.
1231 # But log the cause so we can log a deprecation notice if a caller actually
1232 # does ignore it.
1233 $this->trxStatusIgnoredCause = [ $err, $errno, $fname ];
1234 } elseif ( !$recoverableCL ) {
1235 # Either the query was aborted or all queries after BEGIN where aborted.
1236 # In the first case, the only options going forward are (a) ROLLBACK, or
1237 # (b) ROLLBACK TO SAVEPOINT (if one was set). If the later case, the only
1238 # option is ROLLBACK, since the snapshots would have been released.
1239 $corruptedTrx = true; // cannot recover
1240 $this->trxStatus = self::STATUS_TRX_ERROR;
1241 $this->trxStatusCause =
1242 $this->getQueryExceptionAndLog( $err, $errno, $sql, $fname );
1243 $this->trxStatusIgnoredCause = null;
1244 }
1245 }
1246 }
1247
1248 return [ $ret, $err, $errno, $corruptedTrx ];
1249 }
1250
1251 /**
1252 * Wrapper for doQuery() that handles DBO_TRX, profiling, logging, affected row count
1253 * tracking, and reconnects (without retry) on query failure due to connection loss
1254 *
1255 * @param string $sql Original SQL query
1256 * @param string $commentedSql SQL query with debugging/trace comment
1257 * @param bool $isPermWrite Whether the query is a (non-temporary table) write
1258 * @param string $fname Name of the calling function
1259 * @param int $flags Bit field of class QUERY_* constants
1260 * @return array An n-tuple of:
1261 * - mixed|bool: An object, resource, or true on success; false on failure
1262 * - string: The result of calling lastError()
1263 * - int: The result of calling lastErrno()
1264 * - bool: Whether a statement rollback error occured
1265 * - bool: Whether a disconnect *both* happened *and* was recoverable
1266 * - bool: Whether a reconnection attempt was *both* made *and* succeeded
1267 * @throws DBUnexpectedError
1268 */
1269 private function executeQueryAttempt( $sql, $commentedSql, $isPermWrite, $fname, $flags ) {
1270 $priorWritesPending = $this->writesOrCallbacksPending();
1271
1272 if ( ( $flags & self::QUERY_IGNORE_DBO_TRX ) == 0 ) {
1273 $this->beginIfImplied( $sql, $fname );
1274 }
1275
1276 // Keep track of whether the transaction has write queries pending
1277 if ( $isPermWrite ) {
1278 $this->lastWriteTime = microtime( true );
1279 if ( $this->trxLevel() && !$this->trxDoneWrites ) {
1280 $this->trxDoneWrites = true;
1281 $this->trxProfiler->transactionWritingIn(
1282 $this->server, $this->getDomainID(), $this->trxShortId );
1283 }
1284 }
1285
1286 $prefix = $this->getLBInfo( 'master' ) ? 'query-m: ' : 'query: ';
1287 $generalizedSql = new GeneralizedSql( $sql, $this->trxShortId, $prefix );
1288
1289 $startTime = microtime( true );
1290 $ps = $this->profiler
1291 ? ( $this->profiler )( $generalizedSql->stringify() )
1292 : null;
1293 $this->affectedRowCount = null;
1294 $this->lastQuery = $sql;
1295 $ret = $this->doQuery( $commentedSql );
1296 $lastError = $this->lastError();
1297 $lastErrno = $this->lastErrno();
1298
1299 $this->affectedRowCount = $this->affectedRows();
1300 unset( $ps ); // profile out (if set)
1301 $queryRuntime = max( microtime( true ) - $startTime, 0.0 );
1302
1303 $recoverableSR = false; // recoverable statement rollback?
1304 $recoverableCL = false; // recoverable connection loss?
1305 $reconnected = false; // reconnection both attempted and succeeded?
1306
1307 if ( $ret !== false ) {
1308 $this->lastPing = $startTime;
1309 if ( $isPermWrite && $this->trxLevel() ) {
1310 $this->updateTrxWriteQueryTime( $sql, $queryRuntime, $this->affectedRows() );
1311 $this->trxWriteCallers[] = $fname;
1312 }
1313 } elseif ( $this->wasConnectionError( $lastErrno ) ) {
1314 # Check if no meaningful session state was lost
1315 $recoverableCL = $this->canRecoverFromDisconnect( $sql, $priorWritesPending );
1316 # Update session state tracking and try to restore the connection
1317 $reconnected = $this->replaceLostConnection( __METHOD__ );
1318 } else {
1319 # Check if only the last query was rolled back
1320 $recoverableSR = $this->wasKnownStatementRollbackError();
1321 }
1322
1323 if ( $sql === self::$PING_QUERY ) {
1324 $this->lastRoundTripEstimate = $queryRuntime;
1325 }
1326
1327 $this->trxProfiler->recordQueryCompletion(
1328 $generalizedSql,
1329 $startTime,
1330 $isPermWrite,
1331 $isPermWrite ? $this->affectedRows() : $this->numRows( $ret )
1332 );
1333
1334 // Avoid the overhead of logging calls unless debug mode is enabled
1335 if ( $this->getFlag( self::DBO_DEBUG ) ) {
1336 $this->queryLogger->debug(
1337 "{method} [{runtime}s] {db_host}: {sql}",
1338 [
1339 'method' => $fname,
1340 'db_host' => $this->getServer(),
1341 'sql' => $sql,
1342 'domain' => $this->getDomainID(),
1343 'runtime' => round( $queryRuntime, 3 )
1344 ]
1345 );
1346 }
1347
1348 return [ $ret, $lastError, $lastErrno, $recoverableSR, $recoverableCL, $reconnected ];
1349 }
1350
1351 /**
1352 * Start an implicit transaction if DBO_TRX is enabled and no transaction is active
1353 *
1354 * @param string $sql
1355 * @param string $fname
1356 */
1357 private function beginIfImplied( $sql, $fname ) {
1358 if (
1359 !$this->trxLevel() &&
1360 $this->getFlag( self::DBO_TRX ) &&
1361 $this->isTransactableQuery( $sql )
1362 ) {
1363 $this->begin( __METHOD__ . " ($fname)", self::TRANSACTION_INTERNAL );
1364 $this->trxAutomatic = true;
1365 }
1366 }
1367
1368 /**
1369 * Update the estimated run-time of a query, not counting large row lock times
1370 *
1371 * LoadBalancer can be set to rollback transactions that will create huge replication
1372 * lag. It bases this estimate off of pendingWriteQueryDuration(). Certain simple
1373 * queries, like inserting a row can take a long time due to row locking. This method
1374 * uses some simple heuristics to discount those cases.
1375 *
1376 * @param string $sql A SQL write query
1377 * @param float $runtime Total runtime, including RTT
1378 * @param int $affected Affected row count
1379 */
1380 private function updateTrxWriteQueryTime( $sql, $runtime, $affected ) {
1381 // Whether this is indicative of replica DB runtime (except for RBR or ws_repl)
1382 $indicativeOfReplicaRuntime = true;
1383 if ( $runtime > self::$SLOW_WRITE_SEC ) {
1384 $verb = $this->getQueryVerb( $sql );
1385 // insert(), upsert(), replace() are fast unless bulky in size or blocked on locks
1386 if ( $verb === 'INSERT' ) {
1387 $indicativeOfReplicaRuntime = $this->affectedRows() > self::$SMALL_WRITE_ROWS;
1388 } elseif ( $verb === 'REPLACE' ) {
1389 $indicativeOfReplicaRuntime = $this->affectedRows() > self::$SMALL_WRITE_ROWS / 2;
1390 }
1391 }
1392
1393 $this->trxWriteDuration += $runtime;
1394 $this->trxWriteQueryCount += 1;
1395 $this->trxWriteAffectedRows += $affected;
1396 if ( $indicativeOfReplicaRuntime ) {
1397 $this->trxWriteAdjDuration += $runtime;
1398 $this->trxWriteAdjQueryCount += 1;
1399 }
1400 }
1401
1402 /**
1403 * Error out if the DB is not in a valid state for a query via query()
1404 *
1405 * @param string $sql
1406 * @param string $fname
1407 * @throws DBTransactionStateError
1408 */
1409 private function assertQueryIsCurrentlyAllowed( $sql, $fname ) {
1410 $verb = $this->getQueryVerb( $sql );
1411 if ( $verb === 'USE' ) {
1412 throw new DBUnexpectedError( $this, "Got USE query; use selectDomain() instead" );
1413 }
1414
1415 if ( $verb === 'ROLLBACK' ) { // transaction/savepoint
1416 return;
1417 }
1418
1419 if ( $this->trxStatus < self::STATUS_TRX_OK ) {
1420 throw new DBTransactionStateError(
1421 $this,
1422 "Cannot execute query from $fname while transaction status is ERROR",
1423 [],
1424 $this->trxStatusCause
1425 );
1426 } elseif ( $this->trxStatus === self::STATUS_TRX_OK && $this->trxStatusIgnoredCause ) {
1427 list( $iLastError, $iLastErrno, $iFname ) = $this->trxStatusIgnoredCause;
1428 call_user_func( $this->deprecationLogger,
1429 "Caller from $fname ignored an error originally raised from $iFname: " .
1430 "[$iLastErrno] $iLastError"
1431 );
1432 $this->trxStatusIgnoredCause = null;
1433 }
1434 }
1435
1436 public function assertNoOpenTransactions() {
1437 if ( $this->explicitTrxActive() ) {
1438 throw new DBTransactionError(
1439 $this,
1440 "Explicit transaction still active. A caller may have caught an error. "
1441 . "Open transactions: " . $this->flatAtomicSectionList()
1442 );
1443 }
1444 }
1445
1446 /**
1447 * Determine whether it is safe to retry queries after a database connection is lost
1448 *
1449 * @param string $sql SQL query
1450 * @param bool $priorWritesPending Whether there is a transaction open with
1451 * possible write queries or transaction pre-commit/idle callbacks
1452 * waiting on it to finish.
1453 * @return bool True if it is safe to retry the query, false otherwise
1454 */
1455 private function canRecoverFromDisconnect( $sql, $priorWritesPending ) {
1456 # Transaction dropped; this can mean lost writes, or REPEATABLE-READ snapshots.
1457 # Dropped connections also mean that named locks are automatically released.
1458 # Only allow error suppression in autocommit mode or when the lost transaction
1459 # didn't matter anyway (aside from DBO_TRX snapshot loss).
1460 if ( $this->sessionNamedLocks ) {
1461 return false; // possible critical section violation
1462 } elseif ( $this->sessionTempTables ) {
1463 return false; // tables might be queried latter
1464 } elseif ( $sql === 'COMMIT' ) {
1465 return !$priorWritesPending; // nothing written anyway? (T127428)
1466 } elseif ( $sql === 'ROLLBACK' ) {
1467 return true; // transaction lost...which is also what was requested :)
1468 } elseif ( $this->explicitTrxActive() ) {
1469 return false; // don't drop atomocity and explicit snapshots
1470 } elseif ( $priorWritesPending ) {
1471 return false; // prior writes lost from implicit transaction
1472 }
1473
1474 return true;
1475 }
1476
1477 /**
1478 * Clean things up after session (and thus transaction) loss before reconnect
1479 */
1480 private function handleSessionLossPreconnect() {
1481 // Clean up tracking of session-level things...
1482 // https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html
1483 // https://www.postgresql.org/docs/9.2/static/sql-createtable.html (ignoring ON COMMIT)
1484 $this->sessionTempTables = [];
1485 // https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_get-lock
1486 // https://www.postgresql.org/docs/9.4/static/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS
1487 $this->sessionNamedLocks = [];
1488 // Session loss implies transaction loss
1489 $oldTrxShortId = $this->consumeTrxShortId();
1490 $this->trxAtomicCounter = 0;
1491 $this->trxIdleCallbacks = []; // T67263; transaction already lost
1492 $this->trxPreCommitCallbacks = []; // T67263; transaction already lost
1493 // Clear additional subclass fields
1494 $this->doHandleSessionLossPreconnect();
1495 // @note: leave trxRecurringCallbacks in place
1496 if ( $this->trxDoneWrites ) {
1497 $this->trxProfiler->transactionWritingOut(
1498 $this->server,
1499 $this->getDomainID(),
1500 $oldTrxShortId,
1501 $this->pendingWriteQueryDuration( self::ESTIMATE_TOTAL ),
1502 $this->trxWriteAffectedRows
1503 );
1504 }
1505 }
1506
1507 /**
1508 * Reset any additional subclass trx* and session* fields
1509 */
1510 protected function doHandleSessionLossPreconnect() {
1511 // no-op
1512 }
1513
1514 /**
1515 * Clean things up after session (and thus transaction) loss after reconnect
1516 */
1517 private function handleSessionLossPostconnect() {
1518 try {
1519 // Handle callbacks in trxEndCallbacks, e.g. onTransactionResolution().
1520 // If callback suppression is set then the array will remain unhandled.
1521 $this->runOnTransactionIdleCallbacks( self::TRIGGER_ROLLBACK );
1522 } catch ( Exception $ex ) {
1523 // Already logged; move on...
1524 }
1525 try {
1526 // Handle callbacks in trxRecurringCallbacks, e.g. setTransactionListener()
1527 $this->runTransactionListenerCallbacks( self::TRIGGER_ROLLBACK );
1528 } catch ( Exception $ex ) {
1529 // Already logged; move on...
1530 }
1531 }
1532
1533 /**
1534 * Reset the transaction ID and return the old one
1535 *
1536 * @return string The old transaction ID or the empty string if there wasn't one
1537 */
1538 private function consumeTrxShortId() {
1539 $old = $this->trxShortId;
1540 $this->trxShortId = '';
1541
1542 return $old;
1543 }
1544
1545 /**
1546 * Checks whether the cause of the error is detected to be a timeout.
1547 *
1548 * It returns false by default, and not all engines support detecting this yet.
1549 * If this returns false, it will be treated as a generic query error.
1550 *
1551 * @param string $error Error text
1552 * @param int $errno Error number
1553 * @return bool
1554 */
1555 protected function wasQueryTimeout( $error, $errno ) {
1556 return false;
1557 }
1558
1559 /**
1560 * Report a query error. Log the error, and if neither the object ignore
1561 * flag nor the $ignoreErrors flag is set, throw a DBQueryError.
1562 *
1563 * @param string $error
1564 * @param int $errno
1565 * @param string $sql
1566 * @param string $fname
1567 * @param bool $ignore
1568 * @throws DBQueryError
1569 */
1570 public function reportQueryError( $error, $errno, $sql, $fname, $ignore = false ) {
1571 if ( $ignore ) {
1572 $this->queryLogger->debug( "SQL ERROR (ignored): $error" );
1573 } else {
1574 throw $this->getQueryExceptionAndLog( $error, $errno, $sql, $fname );
1575 }
1576 }
1577
1578 /**
1579 * @param string $error
1580 * @param string|int $errno
1581 * @param string $sql
1582 * @param string $fname
1583 * @return DBError
1584 */
1585 private function getQueryExceptionAndLog( $error, $errno, $sql, $fname ) {
1586 $this->queryLogger->error(
1587 "{fname}\t{db_server}\t{errno}\t{error}\t{sql1line}",
1588 $this->getLogContext( [
1589 'method' => __METHOD__,
1590 'errno' => $errno,
1591 'error' => $error,
1592 'sql1line' => mb_substr( str_replace( "\n", "\\n", $sql ), 0, 5 * 1024 ),
1593 'fname' => $fname,
1594 'trace' => ( new RuntimeException() )->getTraceAsString()
1595 ] )
1596 );
1597
1598 if ( $this->wasQueryTimeout( $error, $errno ) ) {
1599 $e = new DBQueryTimeoutError( $this, $error, $errno, $sql, $fname );
1600 } elseif ( $this->wasConnectionError( $errno ) ) {
1601 $e = new DBQueryDisconnectedError( $this, $error, $errno, $sql, $fname );
1602 } else {
1603 $e = new DBQueryError( $this, $error, $errno, $sql, $fname );
1604 }
1605
1606 return $e;
1607 }
1608
1609 /**
1610 * @param string $error
1611 * @return DBConnectionError
1612 */
1613 final protected function newExceptionAfterConnectError( $error ) {
1614 // Connection was not fully initialized and is not safe for use
1615 $this->conn = null;
1616
1617 $this->connLogger->error(
1618 "Error connecting to {db_server} as user {db_user}: {error}",
1619 $this->getLogContext( [
1620 'error' => $error,
1621 'trace' => ( new RuntimeException() )->getTraceAsString()
1622 ] )
1623 );
1624
1625 return new DBConnectionError( $this, $error );
1626 }
1627
1628 public function freeResult( $res ) {
1629 }
1630
1631 public function selectField(
1632 $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
1633 ) {
1634 if ( $var === '*' ) { // sanity
1635 throw new DBUnexpectedError( $this, "Cannot use a * field: got '$var'" );
1636 }
1637
1638 if ( !is_array( $options ) ) {
1639 $options = [ $options ];
1640 }
1641
1642 $options['LIMIT'] = 1;
1643
1644 $res = $this->select( $table, $var, $cond, $fname, $options, $join_conds );
1645 if ( $res === false ) {
1646 throw new DBUnexpectedError( $this, "Got false from select()" );
1647 }
1648
1649 $row = $this->fetchRow( $res );
1650 if ( $row === false ) {
1651 return false;
1652 }
1653
1654 return reset( $row );
1655 }
1656
1657 public function selectFieldValues(
1658 $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
1659 ) {
1660 if ( $var === '*' ) { // sanity
1661 throw new DBUnexpectedError( $this, "Cannot use a * field" );
1662 } elseif ( !is_string( $var ) ) { // sanity
1663 throw new DBUnexpectedError( $this, "Cannot use an array of fields" );
1664 }
1665
1666 if ( !is_array( $options ) ) {
1667 $options = [ $options ];
1668 }
1669
1670 $res = $this->select( $table, [ 'value' => $var ], $cond, $fname, $options, $join_conds );
1671 if ( $res === false ) {
1672 throw new DBUnexpectedError( $this, "Got false from select()" );
1673 }
1674
1675 $values = [];
1676 foreach ( $res as $row ) {
1677 $values[] = $row->value;
1678 }
1679
1680 return $values;
1681 }
1682
1683 /**
1684 * Returns an optional USE INDEX clause to go after the table, and a
1685 * string to go at the end of the query.
1686 *
1687 * @see Database::select()
1688 *
1689 * @param array $options Associative array of options to be turned into
1690 * an SQL query, valid keys are listed in the function.
1691 * @return array
1692 */
1693 protected function makeSelectOptions( array $options ) {
1694 $preLimitTail = $postLimitTail = '';
1695 $startOpts = '';
1696
1697 $noKeyOptions = [];
1698
1699 foreach ( $options as $key => $option ) {
1700 if ( is_numeric( $key ) ) {
1701 $noKeyOptions[$option] = true;
1702 }
1703 }
1704
1705 $preLimitTail .= $this->makeGroupByWithHaving( $options );
1706
1707 $preLimitTail .= $this->makeOrderBy( $options );
1708
1709 if ( isset( $noKeyOptions['FOR UPDATE'] ) ) {
1710 $postLimitTail .= ' FOR UPDATE';
1711 }
1712
1713 if ( isset( $noKeyOptions['LOCK IN SHARE MODE'] ) ) {
1714 $postLimitTail .= ' LOCK IN SHARE MODE';
1715 }
1716
1717 if ( isset( $noKeyOptions['DISTINCT'] ) || isset( $noKeyOptions['DISTINCTROW'] ) ) {
1718 $startOpts .= 'DISTINCT';
1719 }
1720
1721 # Various MySQL extensions
1722 if ( isset( $noKeyOptions['STRAIGHT_JOIN'] ) ) {
1723 $startOpts .= ' /*! STRAIGHT_JOIN */';
1724 }
1725
1726 if ( isset( $noKeyOptions['SQL_BIG_RESULT'] ) ) {
1727 $startOpts .= ' SQL_BIG_RESULT';
1728 }
1729
1730 if ( isset( $noKeyOptions['SQL_BUFFER_RESULT'] ) ) {
1731 $startOpts .= ' SQL_BUFFER_RESULT';
1732 }
1733
1734 if ( isset( $noKeyOptions['SQL_SMALL_RESULT'] ) ) {
1735 $startOpts .= ' SQL_SMALL_RESULT';
1736 }
1737
1738 if ( isset( $noKeyOptions['SQL_CALC_FOUND_ROWS'] ) ) {
1739 $startOpts .= ' SQL_CALC_FOUND_ROWS';
1740 }
1741
1742 if ( isset( $options['USE INDEX'] ) && is_string( $options['USE INDEX'] ) ) {
1743 $useIndex = $this->useIndexClause( $options['USE INDEX'] );
1744 } else {
1745 $useIndex = '';
1746 }
1747 if ( isset( $options['IGNORE INDEX'] ) && is_string( $options['IGNORE INDEX'] ) ) {
1748 $ignoreIndex = $this->ignoreIndexClause( $options['IGNORE INDEX'] );
1749 } else {
1750 $ignoreIndex = '';
1751 }
1752
1753 return [ $startOpts, $useIndex, $preLimitTail, $postLimitTail, $ignoreIndex ];
1754 }
1755
1756 /**
1757 * Returns an optional GROUP BY with an optional HAVING
1758 *
1759 * @param array $options Associative array of options
1760 * @return string
1761 * @see Database::select()
1762 * @since 1.21
1763 */
1764 protected function makeGroupByWithHaving( $options ) {
1765 $sql = '';
1766 if ( isset( $options['GROUP BY'] ) ) {
1767 $gb = is_array( $options['GROUP BY'] )
1768 ? implode( ',', $options['GROUP BY'] )
1769 : $options['GROUP BY'];
1770 $sql .= ' GROUP BY ' . $gb;
1771 }
1772 if ( isset( $options['HAVING'] ) ) {
1773 $having = is_array( $options['HAVING'] )
1774 ? $this->makeList( $options['HAVING'], self::LIST_AND )
1775 : $options['HAVING'];
1776 $sql .= ' HAVING ' . $having;
1777 }
1778
1779 return $sql;
1780 }
1781
1782 /**
1783 * Returns an optional ORDER BY
1784 *
1785 * @param array $options Associative array of options
1786 * @return string
1787 * @see Database::select()
1788 * @since 1.21
1789 */
1790 protected function makeOrderBy( $options ) {
1791 if ( isset( $options['ORDER BY'] ) ) {
1792 $ob = is_array( $options['ORDER BY'] )
1793 ? implode( ',', $options['ORDER BY'] )
1794 : $options['ORDER BY'];
1795
1796 return ' ORDER BY ' . $ob;
1797 }
1798
1799 return '';
1800 }
1801
1802 public function select(
1803 $table, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
1804 ) {
1805 $sql = $this->selectSQLText( $table, $vars, $conds, $fname, $options, $join_conds );
1806
1807 return $this->query( $sql, $fname );
1808 }
1809
1810 public function selectSQLText( $table, $vars, $conds = '', $fname = __METHOD__,
1811 $options = [], $join_conds = []
1812 ) {
1813 if ( is_array( $vars ) ) {
1814 $fields = implode( ',', $this->fieldNamesWithAlias( $vars ) );
1815 } else {
1816 $fields = $vars;
1817 }
1818
1819 $options = (array)$options;
1820 $useIndexes = ( isset( $options['USE INDEX'] ) && is_array( $options['USE INDEX'] ) )
1821 ? $options['USE INDEX']
1822 : [];
1823 $ignoreIndexes = (
1824 isset( $options['IGNORE INDEX'] ) &&
1825 is_array( $options['IGNORE INDEX'] )
1826 )
1827 ? $options['IGNORE INDEX']
1828 : [];
1829
1830 if (
1831 $this->selectOptionsIncludeLocking( $options ) &&
1832 $this->selectFieldsOrOptionsAggregate( $vars, $options )
1833 ) {
1834 // Some DB types (e.g. postgres) disallow FOR UPDATE with aggregate
1835 // functions. Discourage use of such queries to encourage compatibility.
1836 call_user_func(
1837 $this->deprecationLogger,
1838 __METHOD__ . ": aggregation used with a locking SELECT ($fname)"
1839 );
1840 }
1841
1842 if ( is_array( $table ) ) {
1843 $from = ' FROM ' .
1844 $this->tableNamesWithIndexClauseOrJOIN(
1845 $table, $useIndexes, $ignoreIndexes, $join_conds );
1846 } elseif ( $table != '' ) {
1847 $from = ' FROM ' .
1848 $this->tableNamesWithIndexClauseOrJOIN(
1849 [ $table ], $useIndexes, $ignoreIndexes, [] );
1850 } else {
1851 $from = '';
1852 }
1853
1854 list( $startOpts, $useIndex, $preLimitTail, $postLimitTail, $ignoreIndex ) =
1855 $this->makeSelectOptions( $options );
1856
1857 if ( is_array( $conds ) ) {
1858 $conds = $this->makeList( $conds, self::LIST_AND );
1859 }
1860
1861 if ( $conds === null || $conds === false ) {
1862 $this->queryLogger->warning(
1863 __METHOD__
1864 . ' called from '
1865 . $fname
1866 . ' with incorrect parameters: $conds must be a string or an array'
1867 );
1868 $conds = '';
1869 }
1870
1871 if ( $conds === '' || $conds === '*' ) {
1872 $sql = "SELECT $startOpts $fields $from $useIndex $ignoreIndex $preLimitTail";
1873 } elseif ( is_string( $conds ) ) {
1874 $sql = "SELECT $startOpts $fields $from $useIndex $ignoreIndex " .
1875 "WHERE $conds $preLimitTail";
1876 } else {
1877 throw new DBUnexpectedError( $this, __METHOD__ . ' called with incorrect parameters' );
1878 }
1879
1880 if ( isset( $options['LIMIT'] ) ) {
1881 $sql = $this->limitResult( $sql, $options['LIMIT'],
1882 $options['OFFSET'] ?? false );
1883 }
1884 $sql = "$sql $postLimitTail";
1885
1886 if ( isset( $options['EXPLAIN'] ) ) {
1887 $sql = 'EXPLAIN ' . $sql;
1888 }
1889
1890 return $sql;
1891 }
1892
1893 public function selectRow( $table, $vars, $conds, $fname = __METHOD__,
1894 $options = [], $join_conds = []
1895 ) {
1896 $options = (array)$options;
1897 $options['LIMIT'] = 1;
1898
1899 $res = $this->select( $table, $vars, $conds, $fname, $options, $join_conds );
1900 if ( $res === false ) {
1901 throw new DBUnexpectedError( $this, "Got false from select()" );
1902 }
1903
1904 if ( !$this->numRows( $res ) ) {
1905 return false;
1906 }
1907
1908 return $this->fetchObject( $res );
1909 }
1910
1911 public function estimateRowCount(
1912 $table, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
1913 ) {
1914 $conds = $this->normalizeConditions( $conds, $fname );
1915 $column = $this->extractSingleFieldFromList( $var );
1916 if ( is_string( $column ) && !in_array( $column, [ '*', '1' ] ) ) {
1917 $conds[] = "$column IS NOT NULL";
1918 }
1919
1920 $res = $this->select(
1921 $table, [ 'rowcount' => 'COUNT(*)' ], $conds, $fname, $options, $join_conds
1922 );
1923 $row = $res ? $this->fetchRow( $res ) : [];
1924
1925 return isset( $row['rowcount'] ) ? (int)$row['rowcount'] : 0;
1926 }
1927
1928 public function selectRowCount(
1929 $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
1930 ) {
1931 $conds = $this->normalizeConditions( $conds, $fname );
1932 $column = $this->extractSingleFieldFromList( $var );
1933 if ( is_string( $column ) && !in_array( $column, [ '*', '1' ] ) ) {
1934 $conds[] = "$column IS NOT NULL";
1935 }
1936
1937 $res = $this->select(
1938 [
1939 'tmp_count' => $this->buildSelectSubquery(
1940 $tables,
1941 '1',
1942 $conds,
1943 $fname,
1944 $options,
1945 $join_conds
1946 )
1947 ],
1948 [ 'rowcount' => 'COUNT(*)' ],
1949 [],
1950 $fname
1951 );
1952 $row = $res ? $this->fetchRow( $res ) : [];
1953
1954 return isset( $row['rowcount'] ) ? (int)$row['rowcount'] : 0;
1955 }
1956
1957 /**
1958 * @param string|array $options
1959 * @return bool
1960 */
1961 private function selectOptionsIncludeLocking( $options ) {
1962 $options = (array)$options;
1963 foreach ( [ 'FOR UPDATE', 'LOCK IN SHARE MODE' ] as $lock ) {
1964 if ( in_array( $lock, $options, true ) ) {
1965 return true;
1966 }
1967 }
1968
1969 return false;
1970 }
1971
1972 /**
1973 * @param array|string $fields
1974 * @param array|string $options
1975 * @return bool
1976 */
1977 private function selectFieldsOrOptionsAggregate( $fields, $options ) {
1978 foreach ( (array)$options as $key => $value ) {
1979 if ( is_string( $key ) ) {
1980 if ( preg_match( '/^(?:GROUP BY|HAVING)$/i', $key ) ) {
1981 return true;
1982 }
1983 } elseif ( is_string( $value ) ) {
1984 if ( preg_match( '/^(?:DISTINCT|DISTINCTROW)$/i', $value ) ) {
1985 return true;
1986 }
1987 }
1988 }
1989
1990 $regex = '/^(?:COUNT|MIN|MAX|SUM|GROUP_CONCAT|LISTAGG|ARRAY_AGG)\s*\\(/i';
1991 foreach ( (array)$fields as $field ) {
1992 if ( is_string( $field ) && preg_match( $regex, $field ) ) {
1993 return true;
1994 }
1995 }
1996
1997 return false;
1998 }
1999
2000 /**
2001 * @param array|string $conds
2002 * @param string $fname
2003 * @return array
2004 */
2005 final protected function normalizeConditions( $conds, $fname ) {
2006 if ( $conds === null || $conds === false ) {
2007 $this->queryLogger->warning(
2008 __METHOD__
2009 . ' called from '
2010 . $fname
2011 . ' with incorrect parameters: $conds must be a string or an array'
2012 );
2013 $conds = '';
2014 }
2015
2016 if ( !is_array( $conds ) ) {
2017 $conds = ( $conds === '' ) ? [] : [ $conds ];
2018 }
2019
2020 return $conds;
2021 }
2022
2023 /**
2024 * @param array|string $var Field parameter in the style of select()
2025 * @return string|null Column name or null; ignores aliases
2026 * @throws DBUnexpectedError Errors out if multiple columns are given
2027 */
2028 final protected function extractSingleFieldFromList( $var ) {
2029 if ( is_array( $var ) ) {
2030 if ( !$var ) {
2031 $column = null;
2032 } elseif ( count( $var ) == 1 ) {
2033 $column = $var[0] ?? reset( $var );
2034 } else {
2035 throw new DBUnexpectedError( $this, __METHOD__ . ': got multiple columns' );
2036 }
2037 } else {
2038 $column = $var;
2039 }
2040
2041 return $column;
2042 }
2043
2044 public function lockForUpdate(
2045 $table, $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
2046 ) {
2047 if ( !$this->trxLevel() && !$this->getFlag( self::DBO_TRX ) ) {
2048 throw new DBUnexpectedError(
2049 $this,
2050 __METHOD__ . ': no transaction is active nor is DBO_TRX set'
2051 );
2052 }
2053
2054 $options = (array)$options;
2055 $options[] = 'FOR UPDATE';
2056
2057 return $this->selectRowCount( $table, '*', $conds, $fname, $options, $join_conds );
2058 }
2059
2060 public function fieldExists( $table, $field, $fname = __METHOD__ ) {
2061 $info = $this->fieldInfo( $table, $field );
2062
2063 return (bool)$info;
2064 }
2065
2066 public function indexExists( $table, $index, $fname = __METHOD__ ) {
2067 if ( !$this->tableExists( $table ) ) {
2068 return null;
2069 }
2070
2071 $info = $this->indexInfo( $table, $index, $fname );
2072 if ( is_null( $info ) ) {
2073 return null;
2074 } else {
2075 return $info !== false;
2076 }
2077 }
2078
2079 abstract public function tableExists( $table, $fname = __METHOD__ );
2080
2081 public function indexUnique( $table, $index ) {
2082 $indexInfo = $this->indexInfo( $table, $index );
2083
2084 if ( !$indexInfo ) {
2085 return null;
2086 }
2087
2088 return !$indexInfo[0]->Non_unique;
2089 }
2090
2091 /**
2092 * Helper for Database::insert().
2093 *
2094 * @param array $options
2095 * @return string
2096 */
2097 protected function makeInsertOptions( $options ) {
2098 return implode( ' ', $options );
2099 }
2100
2101 public function insert( $table, $a, $fname = __METHOD__, $options = [] ) {
2102 # No rows to insert, easy just return now
2103 if ( !count( $a ) ) {
2104 return true;
2105 }
2106
2107 $table = $this->tableName( $table );
2108
2109 if ( !is_array( $options ) ) {
2110 $options = [ $options ];
2111 }
2112
2113 $options = $this->makeInsertOptions( $options );
2114
2115 if ( isset( $a[0] ) && is_array( $a[0] ) ) {
2116 $multi = true;
2117 $keys = array_keys( $a[0] );
2118 } else {
2119 $multi = false;
2120 $keys = array_keys( $a );
2121 }
2122
2123 $sql = 'INSERT ' . $options .
2124 " INTO $table (" . implode( ',', $keys ) . ') VALUES ';
2125
2126 if ( $multi ) {
2127 $first = true;
2128 foreach ( $a as $row ) {
2129 if ( $first ) {
2130 $first = false;
2131 } else {
2132 $sql .= ',';
2133 }
2134 $sql .= '(' . $this->makeList( $row ) . ')';
2135 }
2136 } else {
2137 $sql .= '(' . $this->makeList( $a ) . ')';
2138 }
2139
2140 $this->query( $sql, $fname );
2141
2142 return true;
2143 }
2144
2145 /**
2146 * Make UPDATE options array for Database::makeUpdateOptions
2147 *
2148 * @param array $options
2149 * @return array
2150 */
2151 protected function makeUpdateOptionsArray( $options ) {
2152 if ( !is_array( $options ) ) {
2153 $options = [ $options ];
2154 }
2155
2156 $opts = [];
2157
2158 if ( in_array( 'IGNORE', $options ) ) {
2159 $opts[] = 'IGNORE';
2160 }
2161
2162 return $opts;
2163 }
2164
2165 /**
2166 * Make UPDATE options for the Database::update function
2167 *
2168 * @param array $options The options passed to Database::update
2169 * @return string
2170 */
2171 protected function makeUpdateOptions( $options ) {
2172 $opts = $this->makeUpdateOptionsArray( $options );
2173
2174 return implode( ' ', $opts );
2175 }
2176
2177 public function update( $table, $values, $conds, $fname = __METHOD__, $options = [] ) {
2178 $table = $this->tableName( $table );
2179 $opts = $this->makeUpdateOptions( $options );
2180 $sql = "UPDATE $opts $table SET " . $this->makeList( $values, self::LIST_SET );
2181
2182 if ( $conds !== [] && $conds !== '*' ) {
2183 $sql .= " WHERE " . $this->makeList( $conds, self::LIST_AND );
2184 }
2185
2186 $this->query( $sql, $fname );
2187
2188 return true;
2189 }
2190
2191 public function makeList( $a, $mode = self::LIST_COMMA ) {
2192 if ( !is_array( $a ) ) {
2193 throw new DBUnexpectedError( $this, __METHOD__ . ' called with incorrect parameters' );
2194 }
2195
2196 $first = true;
2197 $list = '';
2198
2199 foreach ( $a as $field => $value ) {
2200 if ( !$first ) {
2201 if ( $mode == self::LIST_AND ) {
2202 $list .= ' AND ';
2203 } elseif ( $mode == self::LIST_OR ) {
2204 $list .= ' OR ';
2205 } else {
2206 $list .= ',';
2207 }
2208 } else {
2209 $first = false;
2210 }
2211
2212 if ( ( $mode == self::LIST_AND || $mode == self::LIST_OR ) && is_numeric( $field ) ) {
2213 $list .= "($value)";
2214 } elseif ( $mode == self::LIST_SET && is_numeric( $field ) ) {
2215 $list .= "$value";
2216 } elseif (
2217 ( $mode == self::LIST_AND || $mode == self::LIST_OR ) && is_array( $value )
2218 ) {
2219 // Remove null from array to be handled separately if found
2220 $includeNull = false;
2221 foreach ( array_keys( $value, null, true ) as $nullKey ) {
2222 $includeNull = true;
2223 unset( $value[$nullKey] );
2224 }
2225 if ( count( $value ) == 0 && !$includeNull ) {
2226 throw new InvalidArgumentException(
2227 __METHOD__ . ": empty input for field $field" );
2228 } elseif ( count( $value ) == 0 ) {
2229 // only check if $field is null
2230 $list .= "$field IS NULL";
2231 } else {
2232 // IN clause contains at least one valid element
2233 if ( $includeNull ) {
2234 // Group subconditions to ensure correct precedence
2235 $list .= '(';
2236 }
2237 if ( count( $value ) == 1 ) {
2238 // Special-case single values, as IN isn't terribly efficient
2239 // Don't necessarily assume the single key is 0; we don't
2240 // enforce linear numeric ordering on other arrays here.
2241 $value = array_values( $value )[0];
2242 $list .= $field . " = " . $this->addQuotes( $value );
2243 } else {
2244 $list .= $field . " IN (" . $this->makeList( $value ) . ") ";
2245 }
2246 // if null present in array, append IS NULL
2247 if ( $includeNull ) {
2248 $list .= " OR $field IS NULL)";
2249 }
2250 }
2251 } elseif ( $value === null ) {
2252 if ( $mode == self::LIST_AND || $mode == self::LIST_OR ) {
2253 $list .= "$field IS ";
2254 } elseif ( $mode == self::LIST_SET ) {
2255 $list .= "$field = ";
2256 }
2257 $list .= 'NULL';
2258 } else {
2259 if (
2260 $mode == self::LIST_AND || $mode == self::LIST_OR || $mode == self::LIST_SET
2261 ) {
2262 $list .= "$field = ";
2263 }
2264 $list .= $mode == self::LIST_NAMES ? $value : $this->addQuotes( $value );
2265 }
2266 }
2267
2268 return $list;
2269 }
2270
2271 public function makeWhereFrom2d( $data, $baseKey, $subKey ) {
2272 $conds = [];
2273
2274 foreach ( $data as $base => $sub ) {
2275 if ( count( $sub ) ) {
2276 $conds[] = $this->makeList(
2277 [ $baseKey => $base, $subKey => array_keys( $sub ) ],
2278 self::LIST_AND );
2279 }
2280 }
2281
2282 if ( $conds ) {
2283 return $this->makeList( $conds, self::LIST_OR );
2284 } else {
2285 // Nothing to search for...
2286 return false;
2287 }
2288 }
2289
2290 public function aggregateValue( $valuedata, $valuename = 'value' ) {
2291 return $valuename;
2292 }
2293
2294 public function bitNot( $field ) {
2295 return "(~$field)";
2296 }
2297
2298 public function bitAnd( $fieldLeft, $fieldRight ) {
2299 return "($fieldLeft & $fieldRight)";
2300 }
2301
2302 public function bitOr( $fieldLeft, $fieldRight ) {
2303 return "($fieldLeft | $fieldRight)";
2304 }
2305
2306 public function buildConcat( $stringList ) {
2307 return 'CONCAT(' . implode( ',', $stringList ) . ')';
2308 }
2309
2310 public function buildGroupConcatField(
2311 $delim, $table, $field, $conds = '', $join_conds = []
2312 ) {
2313 $fld = "GROUP_CONCAT($field SEPARATOR " . $this->addQuotes( $delim ) . ')';
2314
2315 return '(' . $this->selectSQLText( $table, $fld, $conds, null, [], $join_conds ) . ')';
2316 }
2317
2318 public function buildSubstring( $input, $startPosition, $length = null ) {
2319 $this->assertBuildSubstringParams( $startPosition, $length );
2320 $functionBody = "$input FROM $startPosition";
2321 if ( $length !== null ) {
2322 $functionBody .= " FOR $length";
2323 }
2324 return 'SUBSTRING(' . $functionBody . ')';
2325 }
2326
2327 /**
2328 * Check type and bounds for parameters to self::buildSubstring()
2329 *
2330 * All supported databases have substring functions that behave the same for
2331 * positive $startPosition and non-negative $length, but behaviors differ when
2332 * given 0 or negative $startPosition or negative $length. The simplest
2333 * solution to that is to just forbid those values.
2334 *
2335 * @param int $startPosition
2336 * @param int|null $length
2337 * @since 1.31
2338 */
2339 protected function assertBuildSubstringParams( $startPosition, $length ) {
2340 if ( !is_int( $startPosition ) || $startPosition <= 0 ) {
2341 throw new InvalidArgumentException(
2342 '$startPosition must be a positive integer'
2343 );
2344 }
2345 if ( !( is_int( $length ) && $length >= 0 || $length === null ) ) {
2346 throw new InvalidArgumentException(
2347 '$length must be null or an integer greater than or equal to 0'
2348 );
2349 }
2350 }
2351
2352 public function buildStringCast( $field ) {
2353 // In theory this should work for any standards-compliant
2354 // SQL implementation, although it may not be the best way to do it.
2355 return "CAST( $field AS CHARACTER )";
2356 }
2357
2358 public function buildIntegerCast( $field ) {
2359 return 'CAST( ' . $field . ' AS INTEGER )';
2360 }
2361
2362 public function buildSelectSubquery(
2363 $table, $vars, $conds = '', $fname = __METHOD__,
2364 $options = [], $join_conds = []
2365 ) {
2366 return new Subquery(
2367 $this->selectSQLText( $table, $vars, $conds, $fname, $options, $join_conds )
2368 );
2369 }
2370
2371 public function databasesAreIndependent() {
2372 return false;
2373 }
2374
2375 final public function selectDB( $db ) {
2376 $this->selectDomain( new DatabaseDomain(
2377 $db,
2378 $this->currentDomain->getSchema(),
2379 $this->currentDomain->getTablePrefix()
2380 ) );
2381
2382 return true;
2383 }
2384
2385 final public function selectDomain( $domain ) {
2386 $this->doSelectDomain( DatabaseDomain::newFromId( $domain ) );
2387 }
2388
2389 /**
2390 * @param DatabaseDomain $domain
2391 * @throws DBConnectionError
2392 * @throws DBError
2393 * @since 1.32
2394 */
2395 protected function doSelectDomain( DatabaseDomain $domain ) {
2396 $this->currentDomain = $domain;
2397 }
2398
2399 public function getDBname() {
2400 return $this->currentDomain->getDatabase();
2401 }
2402
2403 public function getServer() {
2404 return $this->server;
2405 }
2406
2407 public function tableName( $name, $format = 'quoted' ) {
2408 if ( $name instanceof Subquery ) {
2409 throw new DBUnexpectedError(
2410 $this,
2411 __METHOD__ . ': got Subquery instance when expecting a string'
2412 );
2413 }
2414
2415 # Skip the entire process when we have a string quoted on both ends.
2416 # Note that we check the end so that we will still quote any use of
2417 # use of `database`.table. But won't break things if someone wants
2418 # to query a database table with a dot in the name.
2419 if ( $this->isQuotedIdentifier( $name ) ) {
2420 return $name;
2421 }
2422
2423 # Lets test for any bits of text that should never show up in a table
2424 # name. Basically anything like JOIN or ON which are actually part of
2425 # SQL queries, but may end up inside of the table value to combine
2426 # sql. Such as how the API is doing.
2427 # Note that we use a whitespace test rather than a \b test to avoid
2428 # any remote case where a word like on may be inside of a table name
2429 # surrounded by symbols which may be considered word breaks.
2430 if ( preg_match( '/(^|\s)(DISTINCT|JOIN|ON|AS)(\s|$)/i', $name ) !== 0 ) {
2431 $this->queryLogger->warning(
2432 __METHOD__ . ": use of subqueries is not supported this way",
2433 [ 'trace' => ( new RuntimeException() )->getTraceAsString() ]
2434 );
2435
2436 return $name;
2437 }
2438
2439 # Split database and table into proper variables.
2440 list( $database, $schema, $prefix, $table ) = $this->qualifiedTableComponents( $name );
2441
2442 # Quote $table and apply the prefix if not quoted.
2443 # $tableName might be empty if this is called from Database::replaceVars()
2444 $tableName = "{$prefix}{$table}";
2445 if ( $format === 'quoted'
2446 && !$this->isQuotedIdentifier( $tableName )
2447 && $tableName !== ''
2448 ) {
2449 $tableName = $this->addIdentifierQuotes( $tableName );
2450 }
2451
2452 # Quote $schema and $database and merge them with the table name if needed
2453 $tableName = $this->prependDatabaseOrSchema( $schema, $tableName, $format );
2454 $tableName = $this->prependDatabaseOrSchema( $database, $tableName, $format );
2455
2456 return $tableName;
2457 }
2458
2459 /**
2460 * Get the table components needed for a query given the currently selected database
2461 *
2462 * @param string $name Table name in the form of db.schema.table, db.table, or table
2463 * @return array (DB name or "" for default, schema name, table prefix, table name)
2464 */
2465 protected function qualifiedTableComponents( $name ) {
2466 # We reverse the explode so that database.table and table both output the correct table.
2467 $dbDetails = explode( '.', $name, 3 );
2468 if ( count( $dbDetails ) == 3 ) {
2469 list( $database, $schema, $table ) = $dbDetails;
2470 # We don't want any prefix added in this case
2471 $prefix = '';
2472 } elseif ( count( $dbDetails ) == 2 ) {
2473 list( $database, $table ) = $dbDetails;
2474 # We don't want any prefix added in this case
2475 $prefix = '';
2476 # In dbs that support it, $database may actually be the schema
2477 # but that doesn't affect any of the functionality here
2478 $schema = '';
2479 } else {
2480 list( $table ) = $dbDetails;
2481 if ( isset( $this->tableAliases[$table] ) ) {
2482 $database = $this->tableAliases[$table]['dbname'];
2483 $schema = is_string( $this->tableAliases[$table]['schema'] )
2484 ? $this->tableAliases[$table]['schema']
2485 : $this->relationSchemaQualifier();
2486 $prefix = is_string( $this->tableAliases[$table]['prefix'] )
2487 ? $this->tableAliases[$table]['prefix']
2488 : $this->tablePrefix();
2489 } else {
2490 $database = '';
2491 $schema = $this->relationSchemaQualifier(); # Default schema
2492 $prefix = $this->tablePrefix(); # Default prefix
2493 }
2494 }
2495
2496 return [ $database, $schema, $prefix, $table ];
2497 }
2498
2499 /**
2500 * @param string|null $namespace Database or schema
2501 * @param string $relation Name of table, view, sequence, etc...
2502 * @param string $format One of (raw, quoted)
2503 * @return string Relation name with quoted and merged $namespace as needed
2504 */
2505 private function prependDatabaseOrSchema( $namespace, $relation, $format ) {
2506 if ( strlen( $namespace ) ) {
2507 if ( $format === 'quoted' && !$this->isQuotedIdentifier( $namespace ) ) {
2508 $namespace = $this->addIdentifierQuotes( $namespace );
2509 }
2510 $relation = $namespace . '.' . $relation;
2511 }
2512
2513 return $relation;
2514 }
2515
2516 public function tableNames() {
2517 $inArray = func_get_args();
2518 $retVal = [];
2519
2520 foreach ( $inArray as $name ) {
2521 $retVal[$name] = $this->tableName( $name );
2522 }
2523
2524 return $retVal;
2525 }
2526
2527 public function tableNamesN() {
2528 $inArray = func_get_args();
2529 $retVal = [];
2530
2531 foreach ( $inArray as $name ) {
2532 $retVal[] = $this->tableName( $name );
2533 }
2534
2535 return $retVal;
2536 }
2537
2538 /**
2539 * Get an aliased table name
2540 *
2541 * This returns strings like "tableName AS newTableName" for aliased tables
2542 * and "(SELECT * from tableA) newTablename" for subqueries (e.g. derived tables)
2543 *
2544 * @see Database::tableName()
2545 * @param string|Subquery $table Table name or object with a 'sql' field
2546 * @param string|bool $alias Table alias (optional)
2547 * @return string SQL name for aliased table. Will not alias a table to its own name
2548 */
2549 protected function tableNameWithAlias( $table, $alias = false ) {
2550 if ( is_string( $table ) ) {
2551 $quotedTable = $this->tableName( $table );
2552 } elseif ( $table instanceof Subquery ) {
2553 $quotedTable = (string)$table;
2554 } else {
2555 throw new InvalidArgumentException( "Table must be a string or Subquery" );
2556 }
2557
2558 if ( $alias === false || $alias === $table ) {
2559 if ( $table instanceof Subquery ) {
2560 throw new InvalidArgumentException( "Subquery table missing alias" );
2561 }
2562
2563 return $quotedTable;
2564 } else {
2565 return $quotedTable . ' ' . $this->addIdentifierQuotes( $alias );
2566 }
2567 }
2568
2569 /**
2570 * Gets an array of aliased table names
2571 *
2572 * @param array $tables [ [alias] => table ]
2573 * @return string[] See tableNameWithAlias()
2574 */
2575 protected function tableNamesWithAlias( $tables ) {
2576 $retval = [];
2577 foreach ( $tables as $alias => $table ) {
2578 if ( is_numeric( $alias ) ) {
2579 $alias = $table;
2580 }
2581 $retval[] = $this->tableNameWithAlias( $table, $alias );
2582 }
2583
2584 return $retval;
2585 }
2586
2587 /**
2588 * Get an aliased field name
2589 * e.g. fieldName AS newFieldName
2590 *
2591 * @param string $name Field name
2592 * @param string|bool $alias Alias (optional)
2593 * @return string SQL name for aliased field. Will not alias a field to its own name
2594 */
2595 protected function fieldNameWithAlias( $name, $alias = false ) {
2596 if ( !$alias || (string)$alias === (string)$name ) {
2597 return $name;
2598 } else {
2599 return $name . ' AS ' . $this->addIdentifierQuotes( $alias ); // PostgreSQL needs AS
2600 }
2601 }
2602
2603 /**
2604 * Gets an array of aliased field names
2605 *
2606 * @param array $fields [ [alias] => field ]
2607 * @return string[] See fieldNameWithAlias()
2608 */
2609 protected function fieldNamesWithAlias( $fields ) {
2610 $retval = [];
2611 foreach ( $fields as $alias => $field ) {
2612 if ( is_numeric( $alias ) ) {
2613 $alias = $field;
2614 }
2615 $retval[] = $this->fieldNameWithAlias( $field, $alias );
2616 }
2617
2618 return $retval;
2619 }
2620
2621 /**
2622 * Get the aliased table name clause for a FROM clause
2623 * which might have a JOIN and/or USE INDEX or IGNORE INDEX clause
2624 *
2625 * @param array $tables ( [alias] => table )
2626 * @param array $use_index Same as for select()
2627 * @param array $ignore_index Same as for select()
2628 * @param array $join_conds Same as for select()
2629 * @return string
2630 */
2631 protected function tableNamesWithIndexClauseOrJOIN(
2632 $tables, $use_index = [], $ignore_index = [], $join_conds = []
2633 ) {
2634 $ret = [];
2635 $retJOIN = [];
2636 $use_index = (array)$use_index;
2637 $ignore_index = (array)$ignore_index;
2638 $join_conds = (array)$join_conds;
2639
2640 foreach ( $tables as $alias => $table ) {
2641 if ( !is_string( $alias ) ) {
2642 // No alias? Set it equal to the table name
2643 $alias = $table;
2644 }
2645
2646 if ( is_array( $table ) ) {
2647 // A parenthesized group
2648 if ( count( $table ) > 1 ) {
2649 $joinedTable = '(' .
2650 $this->tableNamesWithIndexClauseOrJOIN(
2651 $table, $use_index, $ignore_index, $join_conds ) . ')';
2652 } else {
2653 // Degenerate case
2654 $innerTable = reset( $table );
2655 $innerAlias = key( $table );
2656 $joinedTable = $this->tableNameWithAlias(
2657 $innerTable,
2658 is_string( $innerAlias ) ? $innerAlias : $innerTable
2659 );
2660 }
2661 } else {
2662 $joinedTable = $this->tableNameWithAlias( $table, $alias );
2663 }
2664
2665 // Is there a JOIN clause for this table?
2666 if ( isset( $join_conds[$alias] ) ) {
2667 list( $joinType, $conds ) = $join_conds[$alias];
2668 $tableClause = $joinType;
2669 $tableClause .= ' ' . $joinedTable;
2670 if ( isset( $use_index[$alias] ) ) { // has USE INDEX?
2671 $use = $this->useIndexClause( implode( ',', (array)$use_index[$alias] ) );
2672 if ( $use != '' ) {
2673 $tableClause .= ' ' . $use;
2674 }
2675 }
2676 if ( isset( $ignore_index[$alias] ) ) { // has IGNORE INDEX?
2677 $ignore = $this->ignoreIndexClause(
2678 implode( ',', (array)$ignore_index[$alias] ) );
2679 if ( $ignore != '' ) {
2680 $tableClause .= ' ' . $ignore;
2681 }
2682 }
2683 $on = $this->makeList( (array)$conds, self::LIST_AND );
2684 if ( $on != '' ) {
2685 $tableClause .= ' ON (' . $on . ')';
2686 }
2687
2688 $retJOIN[] = $tableClause;
2689 } elseif ( isset( $use_index[$alias] ) ) {
2690 // Is there an INDEX clause for this table?
2691 $tableClause = $joinedTable;
2692 $tableClause .= ' ' . $this->useIndexClause(
2693 implode( ',', (array)$use_index[$alias] )
2694 );
2695
2696 $ret[] = $tableClause;
2697 } elseif ( isset( $ignore_index[$alias] ) ) {
2698 // Is there an INDEX clause for this table?
2699 $tableClause = $joinedTable;
2700 $tableClause .= ' ' . $this->ignoreIndexClause(
2701 implode( ',', (array)$ignore_index[$alias] )
2702 );
2703
2704 $ret[] = $tableClause;
2705 } else {
2706 $tableClause = $joinedTable;
2707
2708 $ret[] = $tableClause;
2709 }
2710 }
2711
2712 // We can't separate explicit JOIN clauses with ',', use ' ' for those
2713 $implicitJoins = implode( ',', $ret );
2714 $explicitJoins = implode( ' ', $retJOIN );
2715
2716 // Compile our final table clause
2717 return implode( ' ', [ $implicitJoins, $explicitJoins ] );
2718 }
2719
2720 /**
2721 * Allows for index remapping in queries where this is not consistent across DBMS
2722 *
2723 * @param string $index
2724 * @return string
2725 */
2726 protected function indexName( $index ) {
2727 return $this->indexAliases[$index] ?? $index;
2728 }
2729
2730 public function addQuotes( $s ) {
2731 if ( $s instanceof Blob ) {
2732 $s = $s->fetch();
2733 }
2734 if ( $s === null ) {
2735 return 'NULL';
2736 } elseif ( is_bool( $s ) ) {
2737 return (int)$s;
2738 } else {
2739 # This will also quote numeric values. This should be harmless,
2740 # and protects against weird problems that occur when they really
2741 # _are_ strings such as article titles and string->number->string
2742 # conversion is not 1:1.
2743 return "'" . $this->strencode( $s ) . "'";
2744 }
2745 }
2746
2747 public function addIdentifierQuotes( $s ) {
2748 return '"' . str_replace( '"', '""', $s ) . '"';
2749 }
2750
2751 /**
2752 * Returns if the given identifier looks quoted or not according to
2753 * the database convention for quoting identifiers .
2754 *
2755 * @note Do not use this to determine if untrusted input is safe.
2756 * A malicious user can trick this function.
2757 * @param string $name
2758 * @return bool
2759 */
2760 public function isQuotedIdentifier( $name ) {
2761 return $name[0] == '"' && substr( $name, -1, 1 ) == '"';
2762 }
2763
2764 /**
2765 * @param string $s
2766 * @param string $escapeChar
2767 * @return string
2768 */
2769 protected function escapeLikeInternal( $s, $escapeChar = '`' ) {
2770 return str_replace( [ $escapeChar, '%', '_' ],
2771 [ "{$escapeChar}{$escapeChar}", "{$escapeChar}%", "{$escapeChar}_" ],
2772 $s );
2773 }
2774
2775 public function buildLike( $param, ...$params ) {
2776 if ( is_array( $param ) ) {
2777 $params = $param;
2778 } else {
2779 $params = func_get_args();
2780 }
2781
2782 $s = '';
2783
2784 // We use ` instead of \ as the default LIKE escape character, since addQuotes()
2785 // may escape backslashes, creating problems of double escaping. The `
2786 // character has good cross-DBMS compatibility, avoiding special operators
2787 // in MS SQL like ^ and %
2788 $escapeChar = '`';
2789
2790 foreach ( $params as $value ) {
2791 if ( $value instanceof LikeMatch ) {
2792 $s .= $value->toString();
2793 } else {
2794 $s .= $this->escapeLikeInternal( $value, $escapeChar );
2795 }
2796 }
2797
2798 return ' LIKE ' .
2799 $this->addQuotes( $s ) . ' ESCAPE ' . $this->addQuotes( $escapeChar ) . ' ';
2800 }
2801
2802 public function anyChar() {
2803 return new LikeMatch( '_' );
2804 }
2805
2806 public function anyString() {
2807 return new LikeMatch( '%' );
2808 }
2809
2810 public function nextSequenceValue( $seqName ) {
2811 return null;
2812 }
2813
2814 /**
2815 * USE INDEX clause. Unlikely to be useful for anything but MySQL. This
2816 * is only needed because a) MySQL must be as efficient as possible due to
2817 * its use on Wikipedia, and b) MySQL 4.0 is kind of dumb sometimes about
2818 * which index to pick. Anyway, other databases might have different
2819 * indexes on a given table. So don't bother overriding this unless you're
2820 * MySQL.
2821 * @param string $index
<