51596da7c3e5d9d0c80460a64dc45376e5d40014
[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 'domain' => $this->getDomainID(),
1342 'runtime' => round( $queryRuntime, 3 )
1343 ]
1344 );
1345 }
1346
1347 return [ $ret, $lastError, $lastErrno, $recoverableSR, $recoverableCL, $reconnected ];
1348 }
1349
1350 /**
1351 * Start an implicit transaction if DBO_TRX is enabled and no transaction is active
1352 *
1353 * @param string $sql
1354 * @param string $fname
1355 */
1356 private function beginIfImplied( $sql, $fname ) {
1357 if (
1358 !$this->trxLevel() &&
1359 $this->getFlag( self::DBO_TRX ) &&
1360 $this->isTransactableQuery( $sql )
1361 ) {
1362 $this->begin( __METHOD__ . " ($fname)", self::TRANSACTION_INTERNAL );
1363 $this->trxAutomatic = true;
1364 }
1365 }
1366
1367 /**
1368 * Update the estimated run-time of a query, not counting large row lock times
1369 *
1370 * LoadBalancer can be set to rollback transactions that will create huge replication
1371 * lag. It bases this estimate off of pendingWriteQueryDuration(). Certain simple
1372 * queries, like inserting a row can take a long time due to row locking. This method
1373 * uses some simple heuristics to discount those cases.
1374 *
1375 * @param string $sql A SQL write query
1376 * @param float $runtime Total runtime, including RTT
1377 * @param int $affected Affected row count
1378 */
1379 private function updateTrxWriteQueryTime( $sql, $runtime, $affected ) {
1380 // Whether this is indicative of replica DB runtime (except for RBR or ws_repl)
1381 $indicativeOfReplicaRuntime = true;
1382 if ( $runtime > self::$SLOW_WRITE_SEC ) {
1383 $verb = $this->getQueryVerb( $sql );
1384 // insert(), upsert(), replace() are fast unless bulky in size or blocked on locks
1385 if ( $verb === 'INSERT' ) {
1386 $indicativeOfReplicaRuntime = $this->affectedRows() > self::$SMALL_WRITE_ROWS;
1387 } elseif ( $verb === 'REPLACE' ) {
1388 $indicativeOfReplicaRuntime = $this->affectedRows() > self::$SMALL_WRITE_ROWS / 2;
1389 }
1390 }
1391
1392 $this->trxWriteDuration += $runtime;
1393 $this->trxWriteQueryCount += 1;
1394 $this->trxWriteAffectedRows += $affected;
1395 if ( $indicativeOfReplicaRuntime ) {
1396 $this->trxWriteAdjDuration += $runtime;
1397 $this->trxWriteAdjQueryCount += 1;
1398 }
1399 }
1400
1401 /**
1402 * Error out if the DB is not in a valid state for a query via query()
1403 *
1404 * @param string $sql
1405 * @param string $fname
1406 * @throws DBTransactionStateError
1407 */
1408 private function assertQueryIsCurrentlyAllowed( $sql, $fname ) {
1409 $verb = $this->getQueryVerb( $sql );
1410 if ( $verb === 'USE' ) {
1411 throw new DBUnexpectedError( $this, "Got USE query; use selectDomain() instead" );
1412 }
1413
1414 if ( $verb === 'ROLLBACK' ) { // transaction/savepoint
1415 return;
1416 }
1417
1418 if ( $this->trxStatus < self::STATUS_TRX_OK ) {
1419 throw new DBTransactionStateError(
1420 $this,
1421 "Cannot execute query from $fname while transaction status is ERROR",
1422 [],
1423 $this->trxStatusCause
1424 );
1425 } elseif ( $this->trxStatus === self::STATUS_TRX_OK && $this->trxStatusIgnoredCause ) {
1426 list( $iLastError, $iLastErrno, $iFname ) = $this->trxStatusIgnoredCause;
1427 call_user_func( $this->deprecationLogger,
1428 "Caller from $fname ignored an error originally raised from $iFname: " .
1429 "[$iLastErrno] $iLastError"
1430 );
1431 $this->trxStatusIgnoredCause = null;
1432 }
1433 }
1434
1435 public function assertNoOpenTransactions() {
1436 if ( $this->explicitTrxActive() ) {
1437 throw new DBTransactionError(
1438 $this,
1439 "Explicit transaction still active. A caller may have caught an error. "
1440 . "Open transactions: " . $this->flatAtomicSectionList()
1441 );
1442 }
1443 }
1444
1445 /**
1446 * Determine whether it is safe to retry queries after a database connection is lost
1447 *
1448 * @param string $sql SQL query
1449 * @param bool $priorWritesPending Whether there is a transaction open with
1450 * possible write queries or transaction pre-commit/idle callbacks
1451 * waiting on it to finish.
1452 * @return bool True if it is safe to retry the query, false otherwise
1453 */
1454 private function canRecoverFromDisconnect( $sql, $priorWritesPending ) {
1455 # Transaction dropped; this can mean lost writes, or REPEATABLE-READ snapshots.
1456 # Dropped connections also mean that named locks are automatically released.
1457 # Only allow error suppression in autocommit mode or when the lost transaction
1458 # didn't matter anyway (aside from DBO_TRX snapshot loss).
1459 if ( $this->sessionNamedLocks ) {
1460 return false; // possible critical section violation
1461 } elseif ( $this->sessionTempTables ) {
1462 return false; // tables might be queried latter
1463 } elseif ( $sql === 'COMMIT' ) {
1464 return !$priorWritesPending; // nothing written anyway? (T127428)
1465 } elseif ( $sql === 'ROLLBACK' ) {
1466 return true; // transaction lost...which is also what was requested :)
1467 } elseif ( $this->explicitTrxActive() ) {
1468 return false; // don't drop atomocity and explicit snapshots
1469 } elseif ( $priorWritesPending ) {
1470 return false; // prior writes lost from implicit transaction
1471 }
1472
1473 return true;
1474 }
1475
1476 /**
1477 * Clean things up after session (and thus transaction) loss before reconnect
1478 */
1479 private function handleSessionLossPreconnect() {
1480 // Clean up tracking of session-level things...
1481 // https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html
1482 // https://www.postgresql.org/docs/9.2/static/sql-createtable.html (ignoring ON COMMIT)
1483 $this->sessionTempTables = [];
1484 // https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_get-lock
1485 // https://www.postgresql.org/docs/9.4/static/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS
1486 $this->sessionNamedLocks = [];
1487 // Session loss implies transaction loss
1488 $oldTrxShortId = $this->consumeTrxShortId();
1489 $this->trxAtomicCounter = 0;
1490 $this->trxIdleCallbacks = []; // T67263; transaction already lost
1491 $this->trxPreCommitCallbacks = []; // T67263; transaction already lost
1492 // Clear additional subclass fields
1493 $this->doHandleSessionLossPreconnect();
1494 // @note: leave trxRecurringCallbacks in place
1495 if ( $this->trxDoneWrites ) {
1496 $this->trxProfiler->transactionWritingOut(
1497 $this->server,
1498 $this->getDomainID(),
1499 $oldTrxShortId,
1500 $this->pendingWriteQueryDuration( self::ESTIMATE_TOTAL ),
1501 $this->trxWriteAffectedRows
1502 );
1503 }
1504 }
1505
1506 /**
1507 * Reset any additional subclass trx* and session* fields
1508 */
1509 protected function doHandleSessionLossPreconnect() {
1510 // no-op
1511 }
1512
1513 /**
1514 * Clean things up after session (and thus transaction) loss after reconnect
1515 */
1516 private function handleSessionLossPostconnect() {
1517 try {
1518 // Handle callbacks in trxEndCallbacks, e.g. onTransactionResolution().
1519 // If callback suppression is set then the array will remain unhandled.
1520 $this->runOnTransactionIdleCallbacks( self::TRIGGER_ROLLBACK );
1521 } catch ( Exception $ex ) {
1522 // Already logged; move on...
1523 }
1524 try {
1525 // Handle callbacks in trxRecurringCallbacks, e.g. setTransactionListener()
1526 $this->runTransactionListenerCallbacks( self::TRIGGER_ROLLBACK );
1527 } catch ( Exception $ex ) {
1528 // Already logged; move on...
1529 }
1530 }
1531
1532 /**
1533 * Reset the transaction ID and return the old one
1534 *
1535 * @return string The old transaction ID or the empty string if there wasn't one
1536 */
1537 private function consumeTrxShortId() {
1538 $old = $this->trxShortId;
1539 $this->trxShortId = '';
1540
1541 return $old;
1542 }
1543
1544 /**
1545 * Checks whether the cause of the error is detected to be a timeout.
1546 *
1547 * It returns false by default, and not all engines support detecting this yet.
1548 * If this returns false, it will be treated as a generic query error.
1549 *
1550 * @param string $error Error text
1551 * @param int $errno Error number
1552 * @return bool
1553 */
1554 protected function wasQueryTimeout( $error, $errno ) {
1555 return false;
1556 }
1557
1558 /**
1559 * Report a query error. Log the error, and if neither the object ignore
1560 * flag nor the $ignoreErrors flag is set, throw a DBQueryError.
1561 *
1562 * @param string $error
1563 * @param int $errno
1564 * @param string $sql
1565 * @param string $fname
1566 * @param bool $ignore
1567 * @throws DBQueryError
1568 */
1569 public function reportQueryError( $error, $errno, $sql, $fname, $ignore = false ) {
1570 if ( $ignore ) {
1571 $this->queryLogger->debug( "SQL ERROR (ignored): $error" );
1572 } else {
1573 throw $this->getQueryExceptionAndLog( $error, $errno, $sql, $fname );
1574 }
1575 }
1576
1577 /**
1578 * @param string $error
1579 * @param string|int $errno
1580 * @param string $sql
1581 * @param string $fname
1582 * @return DBError
1583 */
1584 private function getQueryExceptionAndLog( $error, $errno, $sql, $fname ) {
1585 $this->queryLogger->error(
1586 "{fname}\t{db_server}\t{errno}\t{error}\t{sql1line}",
1587 $this->getLogContext( [
1588 'method' => __METHOD__,
1589 'errno' => $errno,
1590 'error' => $error,
1591 'sql1line' => mb_substr( str_replace( "\n", "\\n", $sql ), 0, 5 * 1024 ),
1592 'fname' => $fname,
1593 'trace' => ( new RuntimeException() )->getTraceAsString()
1594 ] )
1595 );
1596
1597 if ( $this->wasQueryTimeout( $error, $errno ) ) {
1598 $e = new DBQueryTimeoutError( $this, $error, $errno, $sql, $fname );
1599 } elseif ( $this->wasConnectionError( $errno ) ) {
1600 $e = new DBQueryDisconnectedError( $this, $error, $errno, $sql, $fname );
1601 } else {
1602 $e = new DBQueryError( $this, $error, $errno, $sql, $fname );
1603 }
1604
1605 return $e;
1606 }
1607
1608 /**
1609 * @param string $error
1610 * @return DBConnectionError
1611 */
1612 final protected function newExceptionAfterConnectError( $error ) {
1613 // Connection was not fully initialized and is not safe for use
1614 $this->conn = null;
1615
1616 $this->connLogger->error(
1617 "Error connecting to {db_server} as user {db_user}: {error}",
1618 $this->getLogContext( [
1619 'error' => $error,
1620 'trace' => ( new RuntimeException() )->getTraceAsString()
1621 ] )
1622 );
1623
1624 return new DBConnectionError( $this, $error );
1625 }
1626
1627 public function freeResult( $res ) {
1628 }
1629
1630 public function selectField(
1631 $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
1632 ) {
1633 if ( $var === '*' ) { // sanity
1634 throw new DBUnexpectedError( $this, "Cannot use a * field: got '$var'" );
1635 }
1636
1637 if ( !is_array( $options ) ) {
1638 $options = [ $options ];
1639 }
1640
1641 $options['LIMIT'] = 1;
1642
1643 $res = $this->select( $table, $var, $cond, $fname, $options, $join_conds );
1644 if ( $res === false ) {
1645 throw new DBUnexpectedError( $this, "Got false from select()" );
1646 }
1647
1648 $row = $this->fetchRow( $res );
1649 if ( $row === false ) {
1650 return false;
1651 }
1652
1653 return reset( $row );
1654 }
1655
1656 public function selectFieldValues(
1657 $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
1658 ) {
1659 if ( $var === '*' ) { // sanity
1660 throw new DBUnexpectedError( $this, "Cannot use a * field" );
1661 } elseif ( !is_string( $var ) ) { // sanity
1662 throw new DBUnexpectedError( $this, "Cannot use an array of fields" );
1663 }
1664
1665 if ( !is_array( $options ) ) {
1666 $options = [ $options ];
1667 }
1668
1669 $res = $this->select( $table, [ 'value' => $var ], $cond, $fname, $options, $join_conds );
1670 if ( $res === false ) {
1671 throw new DBUnexpectedError( $this, "Got false from select()" );
1672 }
1673
1674 $values = [];
1675 foreach ( $res as $row ) {
1676 $values[] = $row->value;
1677 }
1678
1679 return $values;
1680 }
1681
1682 /**
1683 * Returns an optional USE INDEX clause to go after the table, and a
1684 * string to go at the end of the query.
1685 *
1686 * @see Database::select()
1687 *
1688 * @param array $options Associative array of options to be turned into
1689 * an SQL query, valid keys are listed in the function.
1690 * @return array
1691 */
1692 protected function makeSelectOptions( array $options ) {
1693 $preLimitTail = $postLimitTail = '';
1694 $startOpts = '';
1695
1696 $noKeyOptions = [];
1697
1698 foreach ( $options as $key => $option ) {
1699 if ( is_numeric( $key ) ) {
1700 $noKeyOptions[$option] = true;
1701 }
1702 }
1703
1704 $preLimitTail .= $this->makeGroupByWithHaving( $options );
1705
1706 $preLimitTail .= $this->makeOrderBy( $options );
1707
1708 if ( isset( $noKeyOptions['FOR UPDATE'] ) ) {
1709 $postLimitTail .= ' FOR UPDATE';
1710 }
1711
1712 if ( isset( $noKeyOptions['LOCK IN SHARE MODE'] ) ) {
1713 $postLimitTail .= ' LOCK IN SHARE MODE';
1714 }
1715
1716 if ( isset( $noKeyOptions['DISTINCT'] ) || isset( $noKeyOptions['DISTINCTROW'] ) ) {
1717 $startOpts .= 'DISTINCT';
1718 }
1719
1720 # Various MySQL extensions
1721 if ( isset( $noKeyOptions['STRAIGHT_JOIN'] ) ) {
1722 $startOpts .= ' /*! STRAIGHT_JOIN */';
1723 }
1724
1725 if ( isset( $noKeyOptions['SQL_BIG_RESULT'] ) ) {
1726 $startOpts .= ' SQL_BIG_RESULT';
1727 }
1728
1729 if ( isset( $noKeyOptions['SQL_BUFFER_RESULT'] ) ) {
1730 $startOpts .= ' SQL_BUFFER_RESULT';
1731 }
1732
1733 if ( isset( $noKeyOptions['SQL_SMALL_RESULT'] ) ) {
1734 $startOpts .= ' SQL_SMALL_RESULT';
1735 }
1736
1737 if ( isset( $noKeyOptions['SQL_CALC_FOUND_ROWS'] ) ) {
1738 $startOpts .= ' SQL_CALC_FOUND_ROWS';
1739 }
1740
1741 if ( isset( $options['USE INDEX'] ) && is_string( $options['USE INDEX'] ) ) {
1742 $useIndex = $this->useIndexClause( $options['USE INDEX'] );
1743 } else {
1744 $useIndex = '';
1745 }
1746 if ( isset( $options['IGNORE INDEX'] ) && is_string( $options['IGNORE INDEX'] ) ) {
1747 $ignoreIndex = $this->ignoreIndexClause( $options['IGNORE INDEX'] );
1748 } else {
1749 $ignoreIndex = '';
1750 }
1751
1752 return [ $startOpts, $useIndex, $preLimitTail, $postLimitTail, $ignoreIndex ];
1753 }
1754
1755 /**
1756 * Returns an optional GROUP BY with an optional HAVING
1757 *
1758 * @param array $options Associative array of options
1759 * @return string
1760 * @see Database::select()
1761 * @since 1.21
1762 */
1763 protected function makeGroupByWithHaving( $options ) {
1764 $sql = '';
1765 if ( isset( $options['GROUP BY'] ) ) {
1766 $gb = is_array( $options['GROUP BY'] )
1767 ? implode( ',', $options['GROUP BY'] )
1768 : $options['GROUP BY'];
1769 $sql .= ' GROUP BY ' . $gb;
1770 }
1771 if ( isset( $options['HAVING'] ) ) {
1772 $having = is_array( $options['HAVING'] )
1773 ? $this->makeList( $options['HAVING'], self::LIST_AND )
1774 : $options['HAVING'];
1775 $sql .= ' HAVING ' . $having;
1776 }
1777
1778 return $sql;
1779 }
1780
1781 /**
1782 * Returns an optional ORDER BY
1783 *
1784 * @param array $options Associative array of options
1785 * @return string
1786 * @see Database::select()
1787 * @since 1.21
1788 */
1789 protected function makeOrderBy( $options ) {
1790 if ( isset( $options['ORDER BY'] ) ) {
1791 $ob = is_array( $options['ORDER BY'] )
1792 ? implode( ',', $options['ORDER BY'] )
1793 : $options['ORDER BY'];
1794
1795 return ' ORDER BY ' . $ob;
1796 }
1797
1798 return '';
1799 }
1800
1801 public function select(
1802 $table, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
1803 ) {
1804 $sql = $this->selectSQLText( $table, $vars, $conds, $fname, $options, $join_conds );
1805
1806 return $this->query( $sql, $fname );
1807 }
1808
1809 public function selectSQLText( $table, $vars, $conds = '', $fname = __METHOD__,
1810 $options = [], $join_conds = []
1811 ) {
1812 if ( is_array( $vars ) ) {
1813 $fields = implode( ',', $this->fieldNamesWithAlias( $vars ) );
1814 } else {
1815 $fields = $vars;
1816 }
1817
1818 $options = (array)$options;
1819 $useIndexes = ( isset( $options['USE INDEX'] ) && is_array( $options['USE INDEX'] ) )
1820 ? $options['USE INDEX']
1821 : [];
1822 $ignoreIndexes = (
1823 isset( $options['IGNORE INDEX'] ) &&
1824 is_array( $options['IGNORE INDEX'] )
1825 )
1826 ? $options['IGNORE INDEX']
1827 : [];
1828
1829 if (
1830 $this->selectOptionsIncludeLocking( $options ) &&
1831 $this->selectFieldsOrOptionsAggregate( $vars, $options )
1832 ) {
1833 // Some DB types (e.g. postgres) disallow FOR UPDATE with aggregate
1834 // functions. Discourage use of such queries to encourage compatibility.
1835 call_user_func(
1836 $this->deprecationLogger,
1837 __METHOD__ . ": aggregation used with a locking SELECT ($fname)"
1838 );
1839 }
1840
1841 if ( is_array( $table ) ) {
1842 $from = ' FROM ' .
1843 $this->tableNamesWithIndexClauseOrJOIN(
1844 $table, $useIndexes, $ignoreIndexes, $join_conds );
1845 } elseif ( $table != '' ) {
1846 $from = ' FROM ' .
1847 $this->tableNamesWithIndexClauseOrJOIN(
1848 [ $table ], $useIndexes, $ignoreIndexes, [] );
1849 } else {
1850 $from = '';
1851 }
1852
1853 list( $startOpts, $useIndex, $preLimitTail, $postLimitTail, $ignoreIndex ) =
1854 $this->makeSelectOptions( $options );
1855
1856 if ( is_array( $conds ) ) {
1857 $conds = $this->makeList( $conds, self::LIST_AND );
1858 }
1859
1860 if ( $conds === null || $conds === false ) {
1861 $this->queryLogger->warning(
1862 __METHOD__
1863 . ' called from '
1864 . $fname
1865 . ' with incorrect parameters: $conds must be a string or an array'
1866 );
1867 $conds = '';
1868 }
1869
1870 if ( $conds === '' || $conds === '*' ) {
1871 $sql = "SELECT $startOpts $fields $from $useIndex $ignoreIndex $preLimitTail";
1872 } elseif ( is_string( $conds ) ) {
1873 $sql = "SELECT $startOpts $fields $from $useIndex $ignoreIndex " .
1874 "WHERE $conds $preLimitTail";
1875 } else {
1876 throw new DBUnexpectedError( $this, __METHOD__ . ' called with incorrect parameters' );
1877 }
1878
1879 if ( isset( $options['LIMIT'] ) ) {
1880 $sql = $this->limitResult( $sql, $options['LIMIT'],
1881 $options['OFFSET'] ?? false );
1882 }
1883 $sql = "$sql $postLimitTail";
1884
1885 if ( isset( $options['EXPLAIN'] ) ) {
1886 $sql = 'EXPLAIN ' . $sql;
1887 }
1888
1889 return $sql;
1890 }
1891
1892 public function selectRow( $table, $vars, $conds, $fname = __METHOD__,
1893 $options = [], $join_conds = []
1894 ) {
1895 $options = (array)$options;
1896 $options['LIMIT'] = 1;
1897
1898 $res = $this->select( $table, $vars, $conds, $fname, $options, $join_conds );
1899 if ( $res === false ) {
1900 throw new DBUnexpectedError( $this, "Got false from select()" );
1901 }
1902
1903 if ( !$this->numRows( $res ) ) {
1904 return false;
1905 }
1906
1907 return $this->fetchObject( $res );
1908 }
1909
1910 public function estimateRowCount(
1911 $table, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
1912 ) {
1913 $conds = $this->normalizeConditions( $conds, $fname );
1914 $column = $this->extractSingleFieldFromList( $var );
1915 if ( is_string( $column ) && !in_array( $column, [ '*', '1' ] ) ) {
1916 $conds[] = "$column IS NOT NULL";
1917 }
1918
1919 $res = $this->select(
1920 $table, [ 'rowcount' => 'COUNT(*)' ], $conds, $fname, $options, $join_conds
1921 );
1922 $row = $res ? $this->fetchRow( $res ) : [];
1923
1924 return isset( $row['rowcount'] ) ? (int)$row['rowcount'] : 0;
1925 }
1926
1927 public function selectRowCount(
1928 $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
1929 ) {
1930 $conds = $this->normalizeConditions( $conds, $fname );
1931 $column = $this->extractSingleFieldFromList( $var );
1932 if ( is_string( $column ) && !in_array( $column, [ '*', '1' ] ) ) {
1933 $conds[] = "$column IS NOT NULL";
1934 }
1935
1936 $res = $this->select(
1937 [
1938 'tmp_count' => $this->buildSelectSubquery(
1939 $tables,
1940 '1',
1941 $conds,
1942 $fname,
1943 $options,
1944 $join_conds
1945 )
1946 ],
1947 [ 'rowcount' => 'COUNT(*)' ],
1948 [],
1949 $fname
1950 );
1951 $row = $res ? $this->fetchRow( $res ) : [];
1952
1953 return isset( $row['rowcount'] ) ? (int)$row['rowcount'] : 0;
1954 }
1955
1956 /**
1957 * @param string|array $options
1958 * @return bool
1959 */
1960 private function selectOptionsIncludeLocking( $options ) {
1961 $options = (array)$options;
1962 foreach ( [ 'FOR UPDATE', 'LOCK IN SHARE MODE' ] as $lock ) {
1963 if ( in_array( $lock, $options, true ) ) {
1964 return true;
1965 }
1966 }
1967
1968 return false;
1969 }
1970
1971 /**
1972 * @param array|string $fields
1973 * @param array|string $options
1974 * @return bool
1975 */
1976 private function selectFieldsOrOptionsAggregate( $fields, $options ) {
1977 foreach ( (array)$options as $key => $value ) {
1978 if ( is_string( $key ) ) {
1979 if ( preg_match( '/^(?:GROUP BY|HAVING)$/i', $key ) ) {
1980 return true;
1981 }
1982 } elseif ( is_string( $value ) ) {
1983 if ( preg_match( '/^(?:DISTINCT|DISTINCTROW)$/i', $value ) ) {
1984 return true;
1985 }
1986 }
1987 }
1988
1989 $regex = '/^(?:COUNT|MIN|MAX|SUM|GROUP_CONCAT|LISTAGG|ARRAY_AGG)\s*\\(/i';
1990 foreach ( (array)$fields as $field ) {
1991 if ( is_string( $field ) && preg_match( $regex, $field ) ) {
1992 return true;
1993 }
1994 }
1995
1996 return false;
1997 }
1998
1999 /**
2000 * @param array|string $conds
2001 * @param string $fname
2002 * @return array
2003 */
2004 final protected function normalizeConditions( $conds, $fname ) {
2005 if ( $conds === null || $conds === false ) {
2006 $this->queryLogger->warning(
2007 __METHOD__
2008 . ' called from '
2009 . $fname
2010 . ' with incorrect parameters: $conds must be a string or an array'
2011 );
2012 $conds = '';
2013 }
2014
2015 if ( !is_array( $conds ) ) {
2016 $conds = ( $conds === '' ) ? [] : [ $conds ];
2017 }
2018
2019 return $conds;
2020 }
2021
2022 /**
2023 * @param array|string $var Field parameter in the style of select()
2024 * @return string|null Column name or null; ignores aliases
2025 * @throws DBUnexpectedError Errors out if multiple columns are given
2026 */
2027 final protected function extractSingleFieldFromList( $var ) {
2028 if ( is_array( $var ) ) {
2029 if ( !$var ) {
2030 $column = null;
2031 } elseif ( count( $var ) == 1 ) {
2032 $column = $var[0] ?? reset( $var );
2033 } else {
2034 throw new DBUnexpectedError( $this, __METHOD__ . ': got multiple columns' );
2035 }
2036 } else {
2037 $column = $var;
2038 }
2039
2040 return $column;
2041 }
2042
2043 public function lockForUpdate(
2044 $table, $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
2045 ) {
2046 if ( !$this->trxLevel() && !$this->getFlag( self::DBO_TRX ) ) {
2047 throw new DBUnexpectedError(
2048 $this,
2049 __METHOD__ . ': no transaction is active nor is DBO_TRX set'
2050 );
2051 }
2052
2053 $options = (array)$options;
2054 $options[] = 'FOR UPDATE';
2055
2056 return $this->selectRowCount( $table, '*', $conds, $fname, $options, $join_conds );
2057 }
2058
2059 public function fieldExists( $table, $field, $fname = __METHOD__ ) {
2060 $info = $this->fieldInfo( $table, $field );
2061
2062 return (bool)$info;
2063 }
2064
2065 public function indexExists( $table, $index, $fname = __METHOD__ ) {
2066 if ( !$this->tableExists( $table ) ) {
2067 return null;
2068 }
2069
2070 $info = $this->indexInfo( $table, $index, $fname );
2071 if ( is_null( $info ) ) {
2072 return null;
2073 } else {
2074 return $info !== false;
2075 }
2076 }
2077
2078 abstract public function tableExists( $table, $fname = __METHOD__ );
2079
2080 public function indexUnique( $table, $index ) {
2081 $indexInfo = $this->indexInfo( $table, $index );
2082
2083 if ( !$indexInfo ) {
2084 return null;
2085 }
2086
2087 return !$indexInfo[0]->Non_unique;
2088 }
2089
2090 /**
2091 * Helper for Database::insert().
2092 *
2093 * @param array $options
2094 * @return string
2095 */
2096 protected function makeInsertOptions( $options ) {
2097 return implode( ' ', $options );
2098 }
2099
2100 public function insert( $table, $a, $fname = __METHOD__, $options = [] ) {
2101 # No rows to insert, easy just return now
2102 if ( !count( $a ) ) {
2103 return true;
2104 }
2105
2106 $table = $this->tableName( $table );
2107
2108 if ( !is_array( $options ) ) {
2109 $options = [ $options ];
2110 }
2111
2112 $options = $this->makeInsertOptions( $options );
2113
2114 if ( isset( $a[0] ) && is_array( $a[0] ) ) {
2115 $multi = true;
2116 $keys = array_keys( $a[0] );
2117 } else {
2118 $multi = false;
2119 $keys = array_keys( $a );
2120 }
2121
2122 $sql = 'INSERT ' . $options .
2123 " INTO $table (" . implode( ',', $keys ) . ') VALUES ';
2124
2125 if ( $multi ) {
2126 $first = true;
2127 foreach ( $a as $row ) {
2128 if ( $first ) {
2129 $first = false;
2130 } else {
2131 $sql .= ',';
2132 }
2133 $sql .= '(' . $this->makeList( $row ) . ')';
2134 }
2135 } else {
2136 $sql .= '(' . $this->makeList( $a ) . ')';
2137 }
2138
2139 $this->query( $sql, $fname );
2140
2141 return true;
2142 }
2143
2144 /**
2145 * Make UPDATE options array for Database::makeUpdateOptions
2146 *
2147 * @param array $options
2148 * @return array
2149 */
2150 protected function makeUpdateOptionsArray( $options ) {
2151 if ( !is_array( $options ) ) {
2152 $options = [ $options ];
2153 }
2154
2155 $opts = [];
2156
2157 if ( in_array( 'IGNORE', $options ) ) {
2158 $opts[] = 'IGNORE';
2159 }
2160
2161 return $opts;
2162 }
2163
2164 /**
2165 * Make UPDATE options for the Database::update function
2166 *
2167 * @param array $options The options passed to Database::update
2168 * @return string
2169 */
2170 protected function makeUpdateOptions( $options ) {
2171 $opts = $this->makeUpdateOptionsArray( $options );
2172
2173 return implode( ' ', $opts );
2174 }
2175
2176 public function update( $table, $values, $conds, $fname = __METHOD__, $options = [] ) {
2177 $table = $this->tableName( $table );
2178 $opts = $this->makeUpdateOptions( $options );
2179 $sql = "UPDATE $opts $table SET " . $this->makeList( $values, self::LIST_SET );
2180
2181 if ( $conds !== [] && $conds !== '*' ) {
2182 $sql .= " WHERE " . $this->makeList( $conds, self::LIST_AND );
2183 }
2184
2185 $this->query( $sql, $fname );
2186
2187 return true;
2188 }
2189
2190 public function makeList( $a, $mode = self::LIST_COMMA ) {
2191 if ( !is_array( $a ) ) {
2192 throw new DBUnexpectedError( $this, __METHOD__ . ' called with incorrect parameters' );
2193 }
2194
2195 $first = true;
2196 $list = '';
2197
2198 foreach ( $a as $field => $value ) {
2199 if ( !$first ) {
2200 if ( $mode == self::LIST_AND ) {
2201 $list .= ' AND ';
2202 } elseif ( $mode == self::LIST_OR ) {
2203 $list .= ' OR ';
2204 } else {
2205 $list .= ',';
2206 }
2207 } else {
2208 $first = false;
2209 }
2210
2211 if ( ( $mode == self::LIST_AND || $mode == self::LIST_OR ) && is_numeric( $field ) ) {
2212 $list .= "($value)";
2213 } elseif ( $mode == self::LIST_SET && is_numeric( $field ) ) {
2214 $list .= "$value";
2215 } elseif (
2216 ( $mode == self::LIST_AND || $mode == self::LIST_OR ) && is_array( $value )
2217 ) {
2218 // Remove null from array to be handled separately if found
2219 $includeNull = false;
2220 foreach ( array_keys( $value, null, true ) as $nullKey ) {
2221 $includeNull = true;
2222 unset( $value[$nullKey] );
2223 }
2224 if ( count( $value ) == 0 && !$includeNull ) {
2225 throw new InvalidArgumentException(
2226 __METHOD__ . ": empty input for field $field" );
2227 } elseif ( count( $value ) == 0 ) {
2228 // only check if $field is null
2229 $list .= "$field IS NULL";
2230 } else {
2231 // IN clause contains at least one valid element
2232 if ( $includeNull ) {
2233 // Group subconditions to ensure correct precedence
2234 $list .= '(';
2235 }
2236 if ( count( $value ) == 1 ) {
2237 // Special-case single values, as IN isn't terribly efficient
2238 // Don't necessarily assume the single key is 0; we don't
2239 // enforce linear numeric ordering on other arrays here.
2240 $value = array_values( $value )[0];
2241 $list .= $field . " = " . $this->addQuotes( $value );
2242 } else {
2243 $list .= $field . " IN (" . $this->makeList( $value ) . ") ";
2244 }
2245 // if null present in array, append IS NULL
2246 if ( $includeNull ) {
2247 $list .= " OR $field IS NULL)";
2248 }
2249 }
2250 } elseif ( $value === null ) {
2251 if ( $mode == self::LIST_AND || $mode == self::LIST_OR ) {
2252 $list .= "$field IS ";
2253 } elseif ( $mode == self::LIST_SET ) {
2254 $list .= "$field = ";
2255 }
2256 $list .= 'NULL';
2257 } else {
2258 if (
2259 $mode == self::LIST_AND || $mode == self::LIST_OR || $mode == self::LIST_SET
2260 ) {
2261 $list .= "$field = ";
2262 }
2263 $list .= $mode == self::LIST_NAMES ? $value : $this->addQuotes( $value );
2264 }
2265 }
2266
2267 return $list;
2268 }
2269
2270 public function makeWhereFrom2d( $data, $baseKey, $subKey ) {
2271 $conds = [];
2272
2273 foreach ( $data as $base => $sub ) {
2274 if ( count( $sub ) ) {
2275 $conds[] = $this->makeList(
2276 [ $baseKey => $base, $subKey => array_keys( $sub ) ],
2277 self::LIST_AND );
2278 }
2279 }
2280
2281 if ( $conds ) {
2282 return $this->makeList( $conds, self::LIST_OR );
2283 } else {
2284 // Nothing to search for...
2285 return false;
2286 }
2287 }
2288
2289 public function aggregateValue( $valuedata, $valuename = 'value' ) {
2290 return $valuename;
2291 }
2292
2293 public function bitNot( $field ) {
2294 return "(~$field)";
2295 }
2296
2297 public function bitAnd( $fieldLeft, $fieldRight ) {
2298 return "($fieldLeft & $fieldRight)";
2299 }
2300
2301 public function bitOr( $fieldLeft, $fieldRight ) {
2302 return "($fieldLeft | $fieldRight)";
2303 }
2304
2305 public function buildConcat( $stringList ) {
2306 return 'CONCAT(' . implode( ',', $stringList ) . ')';
2307 }
2308
2309 public function buildGroupConcatField(
2310 $delim, $table, $field, $conds = '', $join_conds = []
2311 ) {
2312 $fld = "GROUP_CONCAT($field SEPARATOR " . $this->addQuotes( $delim ) . ')';
2313
2314 return '(' . $this->selectSQLText( $table, $fld, $conds, null, [], $join_conds ) . ')';
2315 }
2316
2317 public function buildSubstring( $input, $startPosition, $length = null ) {
2318 $this->assertBuildSubstringParams( $startPosition, $length );
2319 $functionBody = "$input FROM $startPosition";
2320 if ( $length !== null ) {
2321 $functionBody .= " FOR $length";
2322 }
2323 return 'SUBSTRING(' . $functionBody . ')';
2324 }
2325
2326 /**
2327 * Check type and bounds for parameters to self::buildSubstring()
2328 *
2329 * All supported databases have substring functions that behave the same for
2330 * positive $startPosition and non-negative $length, but behaviors differ when
2331 * given 0 or negative $startPosition or negative $length. The simplest
2332 * solution to that is to just forbid those values.
2333 *
2334 * @param int $startPosition
2335 * @param int|null $length
2336 * @since 1.31
2337 */
2338 protected function assertBuildSubstringParams( $startPosition, $length ) {
2339 if ( !is_int( $startPosition ) || $startPosition <= 0 ) {
2340 throw new InvalidArgumentException(
2341 '$startPosition must be a positive integer'
2342 );
2343 }
2344 if ( !( is_int( $length ) && $length >= 0 || $length === null ) ) {
2345 throw new InvalidArgumentException(
2346 '$length must be null or an integer greater than or equal to 0'
2347 );
2348 }
2349 }
2350
2351 public function buildStringCast( $field ) {
2352 // In theory this should work for any standards-compliant
2353 // SQL implementation, although it may not be the best way to do it.
2354 return "CAST( $field AS CHARACTER )";
2355 }
2356
2357 public function buildIntegerCast( $field ) {
2358 return 'CAST( ' . $field . ' AS INTEGER )';
2359 }
2360
2361 public function buildSelectSubquery(
2362 $table, $vars, $conds = '', $fname = __METHOD__,
2363 $options = [], $join_conds = []
2364 ) {
2365 return new Subquery(
2366 $this->selectSQLText( $table, $vars, $conds, $fname, $options, $join_conds )
2367 );
2368 }
2369
2370 public function databasesAreIndependent() {
2371 return false;
2372 }
2373
2374 final public function selectDB( $db ) {
2375 $this->selectDomain( new DatabaseDomain(
2376 $db,
2377 $this->currentDomain->getSchema(),
2378 $this->currentDomain->getTablePrefix()
2379 ) );
2380
2381 return true;
2382 }
2383
2384 final public function selectDomain( $domain ) {
2385 $this->doSelectDomain( DatabaseDomain::newFromId( $domain ) );
2386 }
2387
2388 /**
2389 * @param DatabaseDomain $domain
2390 * @throws DBConnectionError
2391 * @throws DBError
2392 * @since 1.32
2393 */
2394 protected function doSelectDomain( DatabaseDomain $domain ) {
2395 $this->currentDomain = $domain;
2396 }
2397
2398 public function getDBname() {
2399 return $this->currentDomain->getDatabase();
2400 }
2401
2402 public function getServer() {
2403 return $this->server;
2404 }
2405
2406 public function tableName( $name, $format = 'quoted' ) {
2407 if ( $name instanceof Subquery ) {
2408 throw new DBUnexpectedError(
2409 $this,
2410 __METHOD__ . ': got Subquery instance when expecting a string'
2411 );
2412 }
2413
2414 # Skip the entire process when we have a string quoted on both ends.
2415 # Note that we check the end so that we will still quote any use of
2416 # use of `database`.table. But won't break things if someone wants
2417 # to query a database table with a dot in the name.
2418 if ( $this->isQuotedIdentifier( $name ) ) {
2419 return $name;
2420 }
2421
2422 # Lets test for any bits of text that should never show up in a table
2423 # name. Basically anything like JOIN or ON which are actually part of
2424 # SQL queries, but may end up inside of the table value to combine
2425 # sql. Such as how the API is doing.
2426 # Note that we use a whitespace test rather than a \b test to avoid
2427 # any remote case where a word like on may be inside of a table name
2428 # surrounded by symbols which may be considered word breaks.
2429 if ( preg_match( '/(^|\s)(DISTINCT|JOIN|ON|AS)(\s|$)/i', $name ) !== 0 ) {
2430 $this->queryLogger->warning(
2431 __METHOD__ . ": use of subqueries is not supported this way",
2432 [ 'trace' => ( new RuntimeException() )->getTraceAsString() ]
2433 );
2434
2435 return $name;
2436 }
2437
2438 # Split database and table into proper variables.
2439 list( $database, $schema, $prefix, $table ) = $this->qualifiedTableComponents( $name );
2440
2441 # Quote $table and apply the prefix if not quoted.
2442 # $tableName might be empty if this is called from Database::replaceVars()
2443 $tableName = "{$prefix}{$table}";
2444 if ( $format === 'quoted'
2445 && !$this->isQuotedIdentifier( $tableName )
2446 && $tableName !== ''
2447 ) {
2448 $tableName = $this->addIdentifierQuotes( $tableName );
2449 }
2450
2451 # Quote $schema and $database and merge them with the table name if needed
2452 $tableName = $this->prependDatabaseOrSchema( $schema, $tableName, $format );
2453 $tableName = $this->prependDatabaseOrSchema( $database, $tableName, $format );
2454
2455 return $tableName;
2456 }
2457
2458 /**
2459 * Get the table components needed for a query given the currently selected database
2460 *
2461 * @param string $name Table name in the form of db.schema.table, db.table, or table
2462 * @return array (DB name or "" for default, schema name, table prefix, table name)
2463 */
2464 protected function qualifiedTableComponents( $name ) {
2465 # We reverse the explode so that database.table and table both output the correct table.
2466 $dbDetails = explode( '.', $name, 3 );
2467 if ( count( $dbDetails ) == 3 ) {
2468 list( $database, $schema, $table ) = $dbDetails;
2469 # We don't want any prefix added in this case
2470 $prefix = '';
2471 } elseif ( count( $dbDetails ) == 2 ) {
2472 list( $database, $table ) = $dbDetails;
2473 # We don't want any prefix added in this case
2474 $prefix = '';
2475 # In dbs that support it, $database may actually be the schema
2476 # but that doesn't affect any of the functionality here
2477 $schema = '';
2478 } else {
2479 list( $table ) = $dbDetails;
2480 if ( isset( $this->tableAliases[$table] ) ) {
2481 $database = $this->tableAliases[$table]['dbname'];
2482 $schema = is_string( $this->tableAliases[$table]['schema'] )
2483 ? $this->tableAliases[$table]['schema']
2484 : $this->relationSchemaQualifier();
2485 $prefix = is_string( $this->tableAliases[$table]['prefix'] )
2486 ? $this->tableAliases[$table]['prefix']
2487 : $this->tablePrefix();
2488 } else {
2489 $database = '';
2490 $schema = $this->relationSchemaQualifier(); # Default schema
2491 $prefix = $this->tablePrefix(); # Default prefix
2492 }
2493 }
2494
2495 return [ $database, $schema, $prefix, $table ];
2496 }
2497
2498 /**
2499 * @param string|null $namespace Database or schema
2500 * @param string $relation Name of table, view, sequence, etc...
2501 * @param string $format One of (raw, quoted)
2502 * @return string Relation name with quoted and merged $namespace as needed
2503 */
2504 private function prependDatabaseOrSchema( $namespace, $relation, $format ) {
2505 if ( strlen( $namespace ) ) {
2506 if ( $format === 'quoted' && !$this->isQuotedIdentifier( $namespace ) ) {
2507 $namespace = $this->addIdentifierQuotes( $namespace );
2508 }
2509 $relation = $namespace . '.' . $relation;
2510 }
2511
2512 return $relation;
2513 }
2514
2515 public function tableNames() {
2516 $inArray = func_get_args();
2517 $retVal = [];
2518
2519 foreach ( $inArray as $name ) {
2520 $retVal[$name] = $this->tableName( $name );
2521 }
2522
2523 return $retVal;
2524 }
2525
2526 public function tableNamesN() {
2527 $inArray = func_get_args();
2528 $retVal = [];
2529
2530 foreach ( $inArray as $name ) {
2531 $retVal[] = $this->tableName( $name );
2532 }
2533
2534 return $retVal;
2535 }
2536
2537 /**
2538 * Get an aliased table name
2539 *
2540 * This returns strings like "tableName AS newTableName" for aliased tables
2541 * and "(SELECT * from tableA) newTablename" for subqueries (e.g. derived tables)
2542 *
2543 * @see Database::tableName()
2544 * @param string|Subquery $table Table name or object with a 'sql' field
2545 * @param string|bool $alias Table alias (optional)
2546 * @return string SQL name for aliased table. Will not alias a table to its own name
2547 */
2548 protected function tableNameWithAlias( $table, $alias = false ) {
2549 if ( is_string( $table ) ) {
2550 $quotedTable = $this->tableName( $table );
2551 } elseif ( $table instanceof Subquery ) {
2552 $quotedTable = (string)$table;
2553 } else {
2554 throw new InvalidArgumentException( "Table must be a string or Subquery" );
2555 }
2556
2557 if ( $alias === false || $alias === $table ) {
2558 if ( $table instanceof Subquery ) {
2559 throw new InvalidArgumentException( "Subquery table missing alias" );
2560 }
2561
2562 return $quotedTable;
2563 } else {
2564 return $quotedTable . ' ' . $this->addIdentifierQuotes( $alias );
2565 }
2566 }
2567
2568 /**
2569 * Gets an array of aliased table names
2570 *
2571 * @param array $tables [ [alias] => table ]
2572 * @return string[] See tableNameWithAlias()
2573 */
2574 protected function tableNamesWithAlias( $tables ) {
2575 $retval = [];
2576 foreach ( $tables as $alias => $table ) {
2577 if ( is_numeric( $alias ) ) {
2578 $alias = $table;
2579 }
2580 $retval[] = $this->tableNameWithAlias( $table, $alias );
2581 }
2582
2583 return $retval;
2584 }
2585
2586 /**
2587 * Get an aliased field name
2588 * e.g. fieldName AS newFieldName
2589 *
2590 * @param string $name Field name
2591 * @param string|bool $alias Alias (optional)
2592 * @return string SQL name for aliased field. Will not alias a field to its own name
2593 */
2594 protected function fieldNameWithAlias( $name, $alias = false ) {
2595 if ( !$alias || (string)$alias === (string)$name ) {
2596 return $name;
2597 } else {
2598 return $name . ' AS ' . $this->addIdentifierQuotes( $alias ); // PostgreSQL needs AS
2599 }
2600 }
2601
2602 /**
2603 * Gets an array of aliased field names
2604 *
2605 * @param array $fields [ [alias] => field ]
2606 * @return string[] See fieldNameWithAlias()
2607 */
2608 protected function fieldNamesWithAlias( $fields ) {
2609 $retval = [];
2610 foreach ( $fields as $alias => $field ) {
2611 if ( is_numeric( $alias ) ) {
2612 $alias = $field;
2613 }
2614 $retval[] = $this->fieldNameWithAlias( $field, $alias );
2615 }
2616
2617 return $retval;
2618 }
2619
2620 /**
2621 * Get the aliased table name clause for a FROM clause
2622 * which might have a JOIN and/or USE INDEX or IGNORE INDEX clause
2623 *
2624 * @param array $tables ( [alias] => table )
2625 * @param array $use_index Same as for select()
2626 * @param array $ignore_index Same as for select()
2627 * @param array $join_conds Same as for select()
2628 * @return string
2629 */
2630 protected function tableNamesWithIndexClauseOrJOIN(
2631 $tables, $use_index = [], $ignore_index = [], $join_conds = []
2632 ) {
2633 $ret = [];
2634 $retJOIN = [];
2635 $use_index = (array)$use_index;
2636 $ignore_index = (array)$ignore_index;
2637 $join_conds = (array)$join_conds;
2638
2639 foreach ( $tables as $alias => $table ) {
2640 if ( !is_string( $alias ) ) {
2641 // No alias? Set it equal to the table name
2642 $alias = $table;
2643 }
2644
2645 if ( is_array( $table ) ) {
2646 // A parenthesized group
2647 if ( count( $table ) > 1 ) {
2648 $joinedTable = '(' .
2649 $this->tableNamesWithIndexClauseOrJOIN(
2650 $table, $use_index, $ignore_index, $join_conds ) . ')';
2651 } else {
2652 // Degenerate case
2653 $innerTable = reset( $table );
2654 $innerAlias = key( $table );
2655 $joinedTable = $this->tableNameWithAlias(
2656 $innerTable,
2657 is_string( $innerAlias ) ? $innerAlias : $innerTable
2658 );
2659 }
2660 } else {
2661 $joinedTable = $this->tableNameWithAlias( $table, $alias );
2662 }
2663
2664 // Is there a JOIN clause for this table?
2665 if ( isset( $join_conds[$alias] ) ) {
2666 list( $joinType, $conds ) = $join_conds[$alias];
2667 $tableClause = $joinType;
2668 $tableClause .= ' ' . $joinedTable;
2669 if ( isset( $use_index[$alias] ) ) { // has USE INDEX?
2670 $use = $this->useIndexClause( implode( ',', (array)$use_index[$alias] ) );
2671 if ( $use != '' ) {
2672 $tableClause .= ' ' . $use;
2673 }
2674 }
2675 if ( isset( $ignore_index[$alias] ) ) { // has IGNORE INDEX?
2676 $ignore = $this->ignoreIndexClause(
2677 implode( ',', (array)$ignore_index[$alias] ) );
2678 if ( $ignore != '' ) {
2679 $tableClause .= ' ' . $ignore;
2680 }
2681 }
2682 $on = $this->makeList( (array)$conds, self::LIST_AND );
2683 if ( $on != '' ) {
2684 $tableClause .= ' ON (' . $on . ')';
2685 }
2686
2687 $retJOIN[] = $tableClause;
2688 } elseif ( isset( $use_index[$alias] ) ) {
2689 // Is there an INDEX clause for this table?
2690 $tableClause = $joinedTable;
2691 $tableClause .= ' ' . $this->useIndexClause(
2692 implode( ',', (array)$use_index[$alias] )
2693 );
2694
2695 $ret[] = $tableClause;
2696 } elseif ( isset( $ignore_index[$alias] ) ) {
2697 // Is there an INDEX clause for this table?
2698 $tableClause = $joinedTable;
2699 $tableClause .= ' ' . $this->ignoreIndexClause(
2700 implode( ',', (array)$ignore_index[$alias] )
2701 );
2702
2703 $ret[] = $tableClause;
2704 } else {
2705 $tableClause = $joinedTable;
2706
2707 $ret[] = $tableClause;
2708 }
2709 }
2710
2711 // We can't separate explicit JOIN clauses with ',', use ' ' for those
2712 $implicitJoins = implode( ',', $ret );
2713 $explicitJoins = implode( ' ', $retJOIN );
2714
2715 // Compile our final table clause
2716 return implode( ' ', [ $implicitJoins, $explicitJoins ] );
2717 }
2718
2719 /**
2720 * Allows for index remapping in queries where this is not consistent across DBMS
2721 *
2722 * @param string $index
2723 * @return string
2724 */
2725 protected function indexName( $index ) {
2726 return $this->indexAliases[$index] ?? $index;
2727 }
2728
2729 public function addQuotes( $s ) {
2730 if ( $s instanceof Blob ) {
2731 $s = $s->fetch();
2732 }
2733 if ( $s === null ) {
2734 return 'NULL';
2735 } elseif ( is_bool( $s ) ) {
2736 return (int)$s;
2737 } else {
2738 # This will also quote numeric values. This should be harmless,
2739 # and protects against weird problems that occur when they really
2740 # _are_ strings such as article titles and string->number->string
2741 # conversion is not 1:1.
2742 return "'" . $this->strencode( $s ) . "'";
2743 }
2744 }
2745
2746 public function addIdentifierQuotes( $s ) {
2747 return '"' . str_replace( '"', '""', $s ) . '"';
2748 }
2749
2750 /**
2751 * Returns if the given identifier looks quoted or not according to
2752 * the database convention for quoting identifiers .
2753 *
2754 * @note Do not use this to determine if untrusted input is safe.
2755 * A malicious user can trick this function.
2756 * @param string $name
2757 * @return bool
2758 */
2759 public function isQuotedIdentifier( $name ) {
2760 return $name[0] == '"' && substr( $name, -1, 1 ) == '"';
2761 }
2762
2763 /**
2764 * @param string $s
2765 * @param string $escapeChar
2766 * @return string
2767 */
2768 protected function escapeLikeInternal( $s, $escapeChar = '`' ) {
2769 return str_replace( [ $escapeChar, '%', '_' ],
2770 [ "{$escapeChar}{$escapeChar}", "{$escapeChar}%", "{$escapeChar}_" ],
2771 $s );
2772 }
2773
2774 public function buildLike( $param, ...$params ) {
2775 if ( is_array( $param ) ) {
2776 $params = $param;
2777 } else {
2778 $params = func_get_args();
2779 }
2780
2781 $s = '';
2782
2783 // We use ` instead of \ as the default LIKE escape character, since addQuotes()
2784 // may escape backslashes, creating problems of double escaping. The `
2785 // character has good cross-DBMS compatibility, avoiding special operators
2786 // in MS SQL like ^ and %
2787 $escapeChar = '`';
2788
2789 foreach ( $params as $value ) {
2790 if ( $value instanceof LikeMatch ) {
2791 $s .= $value->toString();
2792 } else {
2793 $s .= $this->escapeLikeInternal( $value, $escapeChar );
2794 }
2795 }
2796
2797 return ' LIKE ' .
2798 $this->addQuotes( $s ) . ' ESCAPE ' . $this->addQuotes( $escapeChar ) . ' ';
2799 }
2800
2801 public function anyChar() {
2802 return new LikeMatch( '_' );
2803 }
2804
2805 public function anyString() {
2806 return new LikeMatch( '%' );
2807 }
2808
2809 public function nextSequenceValue( $seqName ) {
2810 return null;
2811 }
2812
2813 /**
2814 * USE INDEX clause. Unlikely to be useful for anything but MySQL. This
2815 * is only needed because a) MySQL must be as efficient as possible due to
2816 * its use on Wikipedia, and b) MySQL 4.0 is kind of dumb sometimes about
2817 * which index to pick. Anyway, other databases might have different
2818 * indexes on a given table. So don't bother overriding this unless you're
2819 * MySQL.
2820 * @param string $index
2821 * @return string
2822 */
2823 public function useIndexClause( $index ) {
2824 return '';
2825 }
2826
2827 /**
2828 * IGNORE INDEX clause. Unlikely to be useful for anything but MySQL. This
2829 * is only needed because a) MySQL must be as efficient as possible due to
2830 * its use on Wikipedia, and b) MySQL 4.0 is kind of dumb sometimes about
2831 * which index to pick. Anyway, other databases might have different
2832 * indexes on a given table. So don't bother overriding this unless you're
2833 * MySQL.
2834 * @param string $index
2835 * @return string
2836 */
2837 public function ignoreIndexClause( $index ) {
2838 return '';
2839 }
2840
2841 public function replace( $table, $uniqueIndexes, $rows, $fname = __METHOD__ ) {
2842 if ( count( $rows ) == 0 ) {
2843 return;
2844 }
2845
2846 $uniqueIndexes = (array)$uniqueIndexes;
2847 // Single row case
2848 if ( !is_array( reset( $rows ) ) ) {
2849 $rows = [ $rows ];
2850 }
2851
2852 try {
2853 $this->startAtomic( $fname, self::ATOMIC_CANCELABLE );
2854 $affectedRowCount = 0;
2855 foreach ( $rows as $row ) {
2856 // Delete rows which collide with this one
2857 $indexWhereClauses = [];
2858 foreach ( $uniqueIndexes as $index ) {
2859 $indexColumns = (array)$index;
2860 $indexRowValues = array_intersect_key( $row, array_flip( $indexColumns ) );
2861 if ( count( $indexRowValues ) != count( $indexColumns ) ) {
2862 throw new DBUnexpectedError(
2863 $this,
2864 'New record does not provide all values for unique key (' .
2865 implode( ', ', $indexColumns ) . ')'
2866 );
2867 } elseif ( in_array( null, $indexRowValues, true ) ) {
2868 throw new DBUnexpectedError(
2869 $this,
2870 'New record has a null value for unique key (' .
2871 implode( ', ', $indexColumns ) . ')'
2872 );
2873 }
2874 $indexWhereClauses[] = $this->makeList( $indexRowValues, LIST_AND );
2875 }
2876
2877 if ( $indexWhereClauses ) {
2878 $this->delete( $table, $this->makeList( $indexWhereClauses, LIST_OR ), $fname );
2879 $affectedRowCount += $this->affectedRows();
2880 }
2881
2882 // Now insert the row
2883 $this->insert( $table, $row, $fname );
2884 $affectedRowCount += $this->affectedRows();
2885 }
2886 $this->endAtomic( $fname );
2887 $this->affectedRowCount = $affectedRowCount;
2888 } catch ( Exception $e ) {
2889 $this->cancelAtomic( $fname );
2890 throw $e;
2891 }
2892 }
2893
2894 /**
2895 * REPLACE query wrapper for MySQL and SQLite, which have a native REPLACE
2896 * statement.
2897 *
2898 * @param string $table Table name
2899 * @param array|string $rows Row(s) to insert
2900 * @param string $fname Caller function name
2901 */
2902 protected function nativeReplace( $table, $rows, $fname ) {
2903 $table = $this->tableName( $table );
2904
2905 # Single row case
2906 if ( !is_array( reset( $rows ) ) ) {
2907 $rows = [ $rows ];
2908 }
2909
2910 $sql = "REPLACE INTO $table (" . implode( ',', array_keys( $rows[0] ) ) . ') VALUES ';
2911 $first = true;
2912
2913 foreach ( $rows as $row ) {
2914 if ( $first ) {
2915 $first = false;
2916 } else {
2917 $sql .= ',';
2918 }
2919
2920 $sql .= '(' . $this->makeList( $row ) . ')';
2921 }
2922
2923 $this->query( $sql, $fname );
2924 }
2925
2926 public function upsert( $table, array $rows, $uniqueIndexes, array $set,
2927 $fname = __METHOD__
2928 ) {
2929 if ( $rows === [] ) {
2930 return true; // nothing to do
2931 }
2932
2933 $uniqueIndexes = (array)$uniqueIndexes;
2934 if ( !is_array( reset( $rows ) ) ) {
2935 $rows = [ $rows ];
2936 }
2937
2938 if ( count( $uniqueIndexes ) ) {
2939 $clauses = []; // list WHERE clauses that each identify a single row
2940 foreach ( $rows as $row ) {
2941 foreach ( $uniqueIndexes as $index ) {
2942 $index = is_array( $index ) ? $index : [ $index ]; // columns
2943 $rowKey = []; // unique key to this row
2944 foreach ( $index as $column ) {
2945 $rowKey[$column] = $row[$column];
2946 }
2947 $clauses[] = $this->makeList( $rowKey, self::LIST_AND );
2948 }
2949 }
2950 $where = [ $this->makeList( $clauses, self::LIST_OR ) ];
2951 } else {
2952 $where = false;
2953 }
2954
2955 $affectedRowCount = 0;
2956 try {
2957 $this->startAtomic( $fname, self::ATOMIC_CANCELABLE );
2958 # Update any existing conflicting row(s)
2959 if ( $where !== false ) {
2960 $this->update( $table, $set, $where, $fname );
2961 $affectedRowCount += $this->affectedRows();
2962 }
2963 # Now insert any non-conflicting row(s)
2964 $this->insert( $table, $rows, $fname, [ 'IGNORE' ] );
2965 $affectedRowCount += $this->affectedRows();
2966 $this->endAtomic( $fname );
2967 $this->affectedRowCount = $affectedRowCount;
2968 } catch ( Exception $e ) {
2969 $this->cancelAtomic( $fname );
2970 throw $e;
2971 }
2972
2973 return true;
2974 }
2975
2976 public function deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds,
2977 $fname = __METHOD__
2978 ) {
2979 if ( !$conds ) {
2980 throw new DBUnexpectedError( $this, __METHOD__ . ' called with empty $conds' );
2981 }
2982
2983 $delTable = $this->tableName( $delTable );
2984 $joinTable = $this->tableName( $joinTable );
2985 $sql = "DELETE FROM $delTable WHERE $delVar IN (SELECT $joinVar FROM $joinTable ";
2986 if ( $conds != '*' ) {
2987 $sql .= 'WHERE ' . $this->makeList( $conds, self::LIST_AND );
2988 }
2989 $sql .= ')';
2990
2991 $this->query( $sql, $fname );
2992 }
2993
2994 public function textFieldSize( $table, $field ) {
2995 $table = $this->tableName( $table );
2996 $sql = "SHOW COLUMNS FROM $table LIKE \"$field\"";
2997 $res = $this->query( $sql, __METHOD__ );
2998 $row = $this->fetchObject( $res );
2999
3000 $m = [];
3001
3002 if ( preg_match( '/\((.*)\)/', $row->Type, $m ) ) {
3003 $size = $m[1];
3004 } else {
3005 $size = -1;
3006 }
3007
3008 return $size;
3009 }
3010
3011 public function delete( $table, $conds, $fname = __METHOD__ ) {
3012 if ( !$conds ) {
3013 throw new DBUnexpectedError( $this, __METHOD__ . ' called with no conditions' );
3014 }
3015
3016 $table = $this->tableName( $table );
3017 $sql = "DELETE FROM $table";
3018
3019 if ( $conds != '*' ) {
3020 if ( is_array( $conds ) ) {
3021 $conds = $this->makeList( $conds, self::LIST_AND );
3022 }
3023 $sql .= ' WHERE ' . $conds;
3024 }
3025
3026 $this->query( $sql, $fname );
3027
3028 return true;
3029 }
3030
3031 final public function insertSelect(
3032 $destTable, $srcTable, $varMap, $conds,
3033 $fname = __METHOD__, $insertOptions = [], $selectOptions = [], $selectJoinConds = []
3034 ) {
3035 static $hints = [ 'NO_AUTO_COLUMNS' ];
3036
3037 $insertOptions = (array)$insertOptions;
3038 $selectOptions = (array)$selectOptions;
3039
3040 if ( $this->cliMode && $this->isInsertSelectSafe( $insertOptions, $selectOptions ) ) {
3041 // For massive migrations with downtime, we don't want to select everything
3042 // into memory and OOM, so do all this native on the server side if possible.
3043 $this->nativeInsertSelect(
3044 $destTable,
3045 $srcTable,
3046 $varMap,
3047 $conds,
3048 $fname,
3049 array_diff( $insertOptions, $hints ),
3050 $selectOptions,
3051 $selectJoinConds
3052 );
3053 } else {
3054 $this->nonNativeInsertSelect(
3055 $destTable,
3056 $srcTable,
3057 $varMap,
3058 $conds,
3059 $fname,
3060 array_diff( $insertOptions, $hints ),
3061 $selectOptions,
3062 $selectJoinConds
3063 );
3064 }
3065
3066 return true;
3067 }
3068
3069 /**
3070 * @param array $insertOptions INSERT options
3071 * @param array $selectOptions SELECT options
3072 * @return bool Whether an INSERT SELECT with these options will be replication safe
3073 * @since 1.31
3074 */
3075 protected function isInsertSelectSafe( array $insertOptions, array $selectOptions ) {
3076 return true;
3077 }
3078
3079 /**
3080 * Implementation of insertSelect() based on select() and insert()
3081 *
3082 * @see IDatabase::insertSelect()
3083 * @since 1.30
3084 * @param string $destTable
3085 * @param string|array $srcTable
3086 * @param array $varMap
3087 * @param array $conds
3088 * @param string $fname
3089 * @param array $insertOptions
3090 * @param array $selectOptions
3091 * @param array $selectJoinConds
3092 */
3093 protected function nonNativeInsertSelect( $destTable, $srcTable, $varMap, $conds,
3094 $fname = __METHOD__,
3095 $insertOptions = [], $selectOptions = [], $selectJoinConds = []
3096 ) {
3097 // For web requests, do a locking SELECT and then INSERT. This puts the SELECT burden
3098 // on only the master (without needing row-based-replication). It also makes it easy to
3099 // know how big the INSERT is going to be.
3100 $fields = [];
3101 foreach ( $varMap as $dstColumn => $sourceColumnOrSql ) {
3102 $fields[] = $this->fieldNameWithAlias( $sourceColumnOrSql, $dstColumn );
3103 }
3104 $selectOptions[] = 'FOR UPDATE';
3105 $res = $this->select(
3106 $srcTable, implode( ',', $fields ), $conds, $fname, $selectOptions, $selectJoinConds
3107 );
3108 if ( !$res ) {
3109 return;
3110 }
3111
3112 try {
3113 $affectedRowCount = 0;
3114 $this->startAtomic( $fname, self::ATOMIC_CANCELABLE );
3115 $rows = [];
3116 $ok = true;
3117 foreach ( $res as $row ) {
3118 $rows[] = (array)$row;
3119
3120 // Avoid inserts that are too huge
3121 if ( count( $rows ) >= $this->nonNativeInsertSelectBatchSize ) {
3122 $ok = $this->insert( $destTable, $rows, $fname, $insertOptions );
3123 if ( !$ok ) {
3124 break;
3125 }
3126 $affectedRowCount += $this->affectedRows();
3127 $rows = [];
3128 }
3129 }
3130 if ( $rows && $ok ) {
3131 $ok = $this->insert( $destTable, $rows, $fname, $insertOptions );
3132 if ( $ok ) {
3133 $affectedRowCount += $this->affectedRows();
3134 }
3135 }
3136 if ( $ok ) {
3137 $this->endAtomic( $fname );
3138 $this->affectedRowCount = $affectedRowCount;
3139 } else {
3140 $this->cancelAtomic( $fname );
3141 }
3142 } catch ( Exception $e ) {
3143 $this->cancelAtomic( $fname );
3144 throw $e;
3145 }
3146 }
3147
3148 /**
3149 * Native server-side implementation of insertSelect() for situations where
3150 * we don't want to select everything into memory
3151 *
3152 * @see IDatabase::insertSelect()
3153 * @param string $destTable
3154 * @param string|array $srcTable
3155 * @param array $varMap
3156 * @param array $conds
3157 * @param string $fname
3158 * @param array $insertOptions
3159 * @param array $selectOptions
3160 * @param array $selectJoinConds
3161 */
3162 protected function nativeInsertSelect( $destTable, $srcTable, $varMap, $conds,
3163 $fname = __METHOD__,
3164 $insertOptions = [], $selectOptions = [], $selectJoinConds = []
3165 ) {
3166 $destTable = $this->tableName( $destTable );
3167
3168 if ( !is_array( $insertOptions ) ) {
3169 $insertOptions = [ $insertOptions ];
3170 }
3171
3172 $insertOptions = $this->makeInsertOptions( $insertOptions );
3173
3174 $selectSql = $this->selectSQLText(
3175 $srcTable,
3176 array_values( $varMap ),
3177 $conds,
3178 $fname,
3179 $selectOptions,
3180 $selectJoinConds
3181 );
3182
3183 $sql = "INSERT $insertOptions" .
3184 " INTO $destTable (" . implode( ',', array_keys( $varMap ) ) . ') ' .
3185 $selectSql;
3186
3187 $this->query( $sql, $fname );
3188 }
3189
3190 public function limitResult( $sql, $limit, $offset = false ) {
3191 if ( !is_numeric( $limit ) ) {
3192 throw new DBUnexpectedError(
3193 $this,
3194 "Invalid non-numeric limit passed to " . __METHOD__
3195 );
3196 }
3197 // This version works in MySQL and SQLite. It will very likely need to be
3198 // overridden for most other RDBMS subclasses.
31