dépôts / lhc / web / wiklou.git / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
history | raw | HEAD
rdbms: fix transaction flushing in Database::close
[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;
34 use BagOStuff;
35 use HashBagOStuff;
36 use LogicException;
37 use InvalidArgumentException;
38 use UnexpectedValueException;
39 use Exception;
40 use RuntimeException;
41
42 /**
43 * Relational database abstraction object
44 *
45 * @ingroup Database
46 * @since 1.28
47 */
48 abstract class Database implements IDatabase, IMaintainableDatabase, LoggerAwareInterface {
49 /** Number of times to re-try an operation in case of deadlock */
50 const DEADLOCK_TRIES = 4;
51 /** Minimum time to wait before retry, in microseconds */
52 const DEADLOCK_DELAY_MIN = 500000;
53 /** Maximum time to wait before retry */
54 const DEADLOCK_DELAY_MAX = 1500000;
55
56 /** How long before it is worth doing a dummy query to test the connection */
57 const PING_TTL = 1.0;
58 const PING_QUERY = 'SELECT 1 AS ping';
59
60 const TINY_WRITE_SEC = 0.010;
61 const SLOW_WRITE_SEC = 0.500;
62 const SMALL_WRITE_ROWS = 100;
63
64 /** @var string Whether lock granularity is on the level of the entire database */
65 const ATTR_DB_LEVEL_LOCKING = 'db-level-locking';
66
67 /** @var int New Database instance will not be connected yet when returned */
68 const NEW_UNCONNECTED = 0;
69 /** @var int New Database instance will already be connected when returned */
70 const NEW_CONNECTED = 1;
71
72 /** @var string SQL query */
73 protected $lastQuery = '';
74 /** @var float|bool UNIX timestamp of last write query */
75 protected $lastWriteTime = false;
76 /** @var string|bool */
77 protected $phpError = false;
78 /** @var string Server that this instance is currently connected to */
79 protected $server;
80 /** @var string User that this instance is currently connected under the name of */
81 protected $user;
82 /** @var string Password used to establish the current connection */
83 protected $password;
84 /** @var string Database that this instance is currently connected to */
85 protected $dbName;
86 /** @var array[] Map of (table => (dbname, schema, prefix) map) */
87 protected $tableAliases = [];
88 /** @var string[] Map of (index alias => index) */
89 protected $indexAliases = [];
90 /** @var bool Whether this PHP instance is for a CLI script */
91 protected $cliMode;
92 /** @var string Agent name for query profiling */
93 protected $agent;
94 /** @var array Parameters used by initConnection() to establish a connection */
95 protected $connectionParams = [];
96 /** @var BagOStuff APC cache */
97 protected $srvCache;
98 /** @var LoggerInterface */
99 protected $connLogger;
100 /** @var LoggerInterface */
101 protected $queryLogger;
102 /** @var callback Error logging callback */
103 protected $errorLogger;
104 /** @var callback Deprecation logging callback */
105 protected $deprecationLogger;
106
107 /** @var resource|null Database connection */
108 protected $conn = null;
109 /** @var bool */
110 protected $opened = false;
111
112 /** @var array[] List of (callable, method name) */
113 protected $trxIdleCallbacks = [];
114 /** @var array[] List of (callable, method name) */
115 protected $trxPreCommitCallbacks = [];
116 /** @var array[] List of (callable, method name) */
117 protected $trxEndCallbacks = [];
118 /** @var callable[] Map of (name => callable) */
119 protected $trxRecurringCallbacks = [];
120 /** @var bool Whether to suppress triggering of transaction end callbacks */
121 protected $trxEndCallbacksSuppressed = false;
122
123 /** @var string */
124 protected $tablePrefix = '';
125 /** @var string */
126 protected $schema = '';
127 /** @var int */
128 protected $flags;
129 /** @var array */
130 protected $lbInfo = [];
131 /** @var array|bool */
132 protected $schemaVars = false;
133 /** @var array */
134 protected $sessionVars = [];
135 /** @var array|null */
136 protected $preparedArgs;
137 /** @var string|bool|null Stashed value of html_errors INI setting */
138 protected $htmlErrors;
139 /** @var string */
140 protected $delimiter = ';';
141 /** @var DatabaseDomain */
142 protected $currentDomain;
143 /** @var integer|null Rows affected by the last query to query() or its CRUD wrappers */
144 protected $affectedRowCount;
145
146 /**
147 * @var int Transaction status
148 */
149 protected $trxStatus = self::STATUS_TRX_NONE;
150 /**
151 * @var Exception|null The last error that caused the status to become STATUS_TRX_ERROR
152 */
153 protected $trxStatusCause;
154 /**
155 * @var array|null If wasKnownStatementRollbackError() prevented trxStatus from being set,
156 * the relevant details are stored here.
157 */
158 protected $trxStatusIgnoredCause;
159 /**
160 * Either 1 if a transaction is active or 0 otherwise.
161 * The other Trx fields may not be meaningfull if this is 0.
162 *
163 * @var int
164 */
165 protected $trxLevel = 0;
166 /**
167 * Either a short hexidecimal string if a transaction is active or ""
168 *
169 * @var string
170 * @see Database::trxLevel
171 */
172 protected $trxShortId = '';
173 /**
174 * The UNIX time that the transaction started. Callers can assume that if
175 * snapshot isolation is used, then the data is *at least* up to date to that
176 * point (possibly more up-to-date since the first SELECT defines the snapshot).
177 *
178 * @var float|null
179 * @see Database::trxLevel
180 */
181 private $trxTimestamp = null;
182 /** @var float Lag estimate at the time of BEGIN */
183 private $trxReplicaLag = null;
184 /**
185 * Remembers the function name given for starting the most recent transaction via begin().
186 * Used to provide additional context for error reporting.
187 *
188 * @var string
189 * @see Database::trxLevel
190 */
191 private $trxFname = null;
192 /**
193 * Record if possible write queries were done in the last transaction started
194 *
195 * @var bool
196 * @see Database::trxLevel
197 */
198 private $trxDoneWrites = false;
199 /**
200 * Record if the current transaction was started implicitly due to DBO_TRX being set.
201 *
202 * @var bool
203 * @see Database::trxLevel
204 */
205 private $trxAutomatic = false;
206 /**
207 * Counter for atomic savepoint identifiers. Reset when a new transaction begins.
208 *
209 * @var int
210 */
211 private $trxAtomicCounter = 0;
212 /**
213 * Array of levels of atomicity within transactions
214 *
215 * @var array
216 */
217 private $trxAtomicLevels = [];
218 /**
219 * Record if the current transaction was started implicitly by Database::startAtomic
220 *
221 * @var bool
222 */
223 private $trxAutomaticAtomic = false;
224 /**
225 * Track the write query callers of the current transaction
226 *
227 * @var string[]
228 */
229 private $trxWriteCallers = [];
230 /**
231 * @var float Seconds spent in write queries for the current transaction
232 */
233 private $trxWriteDuration = 0.0;
234 /**
235 * @var int Number of write queries for the current transaction
236 */
237 private $trxWriteQueryCount = 0;
238 /**
239 * @var int Number of rows affected by write queries for the current transaction
240 */
241 private $trxWriteAffectedRows = 0;
242 /**
243 * @var float Like trxWriteQueryCount but excludes lock-bound, easy to replicate, queries
244 */
245 private $trxWriteAdjDuration = 0.0;
246 /**
247 * @var int Number of write queries counted in trxWriteAdjDuration
248 */
249 private $trxWriteAdjQueryCount = 0;
250 /**
251 * @var float RTT time estimate
252 */
253 private $rttEstimate = 0.0;
254
255 /** @var array Map of (name => 1) for locks obtained via lock() */
256 private $namedLocksHeld = [];
257 /** @var array Map of (table name => 1) for TEMPORARY tables */
258 protected $sessionTempTables = [];
259
260 /** @var IDatabase|null Lazy handle to the master DB this server replicates from */
261 private $lazyMasterHandle;
262
263 /** @var float UNIX timestamp */
264 protected $lastPing = 0.0;
265
266 /** @var int[] Prior flags member variable values */
267 private $priorFlags = [];
268
269 /** @var object|string Class name or object With profileIn/profileOut methods */
270 protected $profiler;
271 /** @var TransactionProfiler */
272 protected $trxProfiler;
273
274 /** @var int */
275 protected $nonNativeInsertSelectBatchSize = 10000;
276
277 /** @var int Transaction is in a error state requiring a full or savepoint rollback */
278 const STATUS_TRX_ERROR = 1;
279 /** @var int Transaction is active and in a normal state */
280 const STATUS_TRX_OK = 2;
281 /** @var int No transaction is active */
282 const STATUS_TRX_NONE = 3;
283
284 /**
285 * @note: exceptions for missing libraries/drivers should be thrown in initConnection()
286 * @param array $params Parameters passed from Database::factory()
287 */
288 protected function __construct( array $params ) {
289 foreach ( [ 'host', 'user', 'password', 'dbname' ] as $name ) {
290 $this->connectionParams[$name] = $params[$name];
291 }
292
293 $this->schema = $params['schema'];
294 $this->tablePrefix = $params['tablePrefix'];
295
296 $this->cliMode = $params['cliMode'];
297 // Agent name is added to SQL queries in a comment, so make sure it can't break out
298 $this->agent = str_replace( '/', '-', $params['agent'] );
299
300 $this->flags = $params['flags'];
301 if ( $this->flags & self::DBO_DEFAULT ) {
302 if ( $this->cliMode ) {
303 $this->flags &= ~self::DBO_TRX;
304 } else {
305 $this->flags |= self::DBO_TRX;
306 }
307 }
308 // Disregard deprecated DBO_IGNORE flag (T189999)
309 $this->flags &= ~self::DBO_IGNORE;
310
311 $this->sessionVars = $params['variables'];
312
313 $this->srvCache = isset( $params['srvCache'] )
314 ? $params['srvCache']
315 : new HashBagOStuff();
316
317 $this->profiler = $params['profiler'];
318 $this->trxProfiler = $params['trxProfiler'];
319 $this->connLogger = $params['connLogger'];
320 $this->queryLogger = $params['queryLogger'];
321 $this->errorLogger = $params['errorLogger'];
322 $this->deprecationLogger = $params['deprecationLogger'];
323
324 if ( isset( $params['nonNativeInsertSelectBatchSize'] ) ) {
325 $this->nonNativeInsertSelectBatchSize = $params['nonNativeInsertSelectBatchSize'];
326 }
327
328 // Set initial dummy domain until open() sets the final DB/prefix
329 $this->currentDomain = DatabaseDomain::newUnspecified();
330 }
331
332 /**
333 * Initialize the connection to the database over the wire (or to local files)
334 *
335 * @throws LogicException
336 * @throws InvalidArgumentException
337 * @throws DBConnectionError
338 * @since 1.31
339 */
340 final public function initConnection() {
341 if ( $this->isOpen() ) {
342 throw new LogicException( __METHOD__ . ': already connected.' );
343 }
344 // Establish the connection
345 $this->doInitConnection();
346 // Set the domain object after open() sets the relevant fields
347 if ( $this->dbName != '' ) {
348 // Domains with server scope but a table prefix are not used by IDatabase classes
349 $this->currentDomain = new DatabaseDomain( $this->dbName, null, $this->tablePrefix );
350 }
351 }
352
353 /**
354 * Actually connect to the database over the wire (or to local files)
355 *
356 * @throws InvalidArgumentException
357 * @throws DBConnectionError
358 * @since 1.31
359 */
360 protected function doInitConnection() {
361 if ( strlen( $this->connectionParams['user'] ) ) {
362 $this->open(
363 $this->connectionParams['host'],
364 $this->connectionParams['user'],
365 $this->connectionParams['password'],
366 $this->connectionParams['dbname']
367 );
368 } else {
369 throw new InvalidArgumentException( "No database user provided." );
370 }
371 }
372
373 /**
374 * Construct a Database subclass instance given a database type and parameters
375 *
376 * This also connects to the database immediately upon object construction
377 *
378 * @param string $dbType A possible DB type (sqlite, mysql, postgres,...)
379 * @param array $p Parameter map with keys:
380 * - host : The hostname of the DB server
381 * - user : The name of the database user the client operates under
382 * - password : The password for the database user
383 * - dbname : The name of the database to use where queries do not specify one.
384 * The database must exist or an error might be thrown. Setting this to the empty string
385 * will avoid any such errors and make the handle have no implicit database scope. This is
386 * useful for queries like SHOW STATUS, CREATE DATABASE, or DROP DATABASE. Note that a
387 * "database" in Postgres is rougly equivalent to an entire MySQL server. This the domain
388 * in which user names and such are defined, e.g. users are database-specific in Postgres.
389 * - schema : The database schema to use (if supported). A "schema" in Postgres is roughly
390 * equivalent to a "database" in MySQL. Note that MySQL and SQLite do not use schemas.
391 * - tablePrefix : Optional table prefix that is implicitly added on to all table names
392 * recognized in queries. This can be used in place of schemas for handle site farms.
393 * - flags : Optional bitfield of DBO_* constants that define connection, protocol,
394 * buffering, and transaction behavior. It is STRONGLY adviced to leave the DBO_DEFAULT
395 * flag in place UNLESS this this database simply acts as a key/value store.
396 * - driver: Optional name of a specific DB client driver. For MySQL, there is only the
397 * 'mysqli' driver; the old one 'mysql' has been removed.
398 * - variables: Optional map of session variables to set after connecting. This can be
399 * used to adjust lock timeouts or encoding modes and the like.
400 * - connLogger: Optional PSR-3 logger interface instance.
401 * - queryLogger: Optional PSR-3 logger interface instance.
402 * - profiler: Optional class name or object with profileIn()/profileOut() methods.
403 * These will be called in query(), using a simplified version of the SQL that also
404 * includes the agent as a SQL comment.
405 * - trxProfiler: Optional TransactionProfiler instance.
406 * - errorLogger: Optional callback that takes an Exception and logs it.
407 * - deprecationLogger: Optional callback that takes a string and logs it.
408 * - cliMode: Whether to consider the execution context that of a CLI script.
409 * - agent: Optional name used to identify the end-user in query profiling/logging.
410 * - srvCache: Optional BagOStuff instance to an APC-style cache.
411 * - nonNativeInsertSelectBatchSize: Optional batch size for non-native INSERT SELECT emulation.
412 * @param int $connect One of the class constants (NEW_CONNECTED, NEW_UNCONNECTED) [optional]
413 * @return Database|null If the database driver or extension cannot be found
414 * @throws InvalidArgumentException If the database driver or extension cannot be found
415 * @since 1.18
416 */
417 final public static function factory( $dbType, $p = [], $connect = self::NEW_CONNECTED ) {
418 $class = self::getClass( $dbType, isset( $p['driver'] ) ? $p['driver'] : null );
419
420 if ( class_exists( $class ) && is_subclass_of( $class, IDatabase::class ) ) {
421 // Resolve some defaults for b/c
422 $p['host'] = isset( $p['host'] ) ? $p['host'] : false;
423 $p['user'] = isset( $p['user'] ) ? $p['user'] : false;
424 $p['password'] = isset( $p['password'] ) ? $p['password'] : false;
425 $p['dbname'] = isset( $p['dbname'] ) ? $p['dbname'] : false;
426 $p['flags'] = isset( $p['flags'] ) ? $p['flags'] : 0;
427 $p['variables'] = isset( $p['variables'] ) ? $p['variables'] : [];
428 $p['tablePrefix'] = isset( $p['tablePrefix'] ) ? $p['tablePrefix'] : '';
429 $p['schema'] = isset( $p['schema'] ) ? $p['schema'] : '';
430 $p['cliMode'] = isset( $p['cliMode'] )
431 ? $p['cliMode']
432 : ( PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg' );
433 $p['agent'] = isset( $p['agent'] ) ? $p['agent'] : '';
434 if ( !isset( $p['connLogger'] ) ) {
435 $p['connLogger'] = new NullLogger();
436 }
437 if ( !isset( $p['queryLogger'] ) ) {
438 $p['queryLogger'] = new NullLogger();
439 }
440 $p['profiler'] = isset( $p['profiler'] ) ? $p['profiler'] : null;
441 if ( !isset( $p['trxProfiler'] ) ) {
442 $p['trxProfiler'] = new TransactionProfiler();
443 }
444 if ( !isset( $p['errorLogger'] ) ) {
445 $p['errorLogger'] = function ( Exception $e ) {
446 trigger_error( get_class( $e ) . ': ' . $e->getMessage(), E_USER_WARNING );
447 };
448 }
449 if ( !isset( $p['deprecationLogger'] ) ) {
450 $p['deprecationLogger'] = function ( $msg ) {
451 trigger_error( $msg, E_USER_DEPRECATED );
452 };
453 }
454
455 /** @var Database $conn */
456 $conn = new $class( $p );
457 if ( $connect == self::NEW_CONNECTED ) {
458 $conn->initConnection();
459 }
460 } else {
461 $conn = null;
462 }
463
464 return $conn;
465 }
466
467 /**
468 * @param string $dbType A possible DB type (sqlite, mysql, postgres,...)
469 * @param string|null $driver Optional name of a specific DB client driver
470 * @return array Map of (Database::ATTRIBUTE_* constant => value) for all such constants
471 * @throws InvalidArgumentException
472 * @since 1.31
473 */
474 final public static function attributesFromType( $dbType, $driver = null ) {
475 static $defaults = [ self::ATTR_DB_LEVEL_LOCKING => false ];
476
477 $class = self::getClass( $dbType, $driver );
478
479 return call_user_func( [ $class, 'getAttributes' ] ) + $defaults;
480 }
481
482 /**
483 * @param string $dbType A possible DB type (sqlite, mysql, postgres,...)
484 * @param string|null $driver Optional name of a specific DB client driver
485 * @return string Database subclass name to use
486 * @throws InvalidArgumentException
487 */
488 private static function getClass( $dbType, $driver = null ) {
489 // For database types with built-in support, the below maps type to IDatabase
490 // implementations. For types with multipe driver implementations (PHP extensions),
491 // an array can be used, keyed by extension name. In case of an array, the
492 // optional 'driver' parameter can be used to force a specific driver. Otherwise,
493 // we auto-detect the first available driver. For types without built-in support,
494 // an class named "Database<Type>" us used, eg. DatabaseFoo for type 'foo'.
495 static $builtinTypes = [
496 'mssql' => DatabaseMssql::class,
497 'mysql' => [ 'mysqli' => DatabaseMysqli::class ],
498 'sqlite' => DatabaseSqlite::class,
499 'postgres' => DatabasePostgres::class,
500 ];
501
502 $dbType = strtolower( $dbType );
503 $class = false;
504
505 if ( isset( $builtinTypes[$dbType] ) ) {
506 $possibleDrivers = $builtinTypes[$dbType];
507 if ( is_string( $possibleDrivers ) ) {
508 $class = $possibleDrivers;
509 } else {
510 if ( (string)$driver !== '' ) {
511 if ( !isset( $possibleDrivers[$driver] ) ) {
512 throw new InvalidArgumentException( __METHOD__ .
513 " type '$dbType' does not support driver '{$driver}'" );
514 } else {
515 $class = $possibleDrivers[$driver];
516 }
517 } else {
518 foreach ( $possibleDrivers as $posDriver => $possibleClass ) {
519 if ( extension_loaded( $posDriver ) ) {
520 $class = $possibleClass;
521 break;
522 }
523 }
524 }
525 }
526 } else {
527 $class = 'Database' . ucfirst( $dbType );
528 }
529
530 if ( $class === false ) {
531 throw new InvalidArgumentException( __METHOD__ .
532 " no viable database extension found for type '$dbType'" );
533 }
534
535 return $class;
536 }
537
538 /**
539 * @return array Map of (Database::ATTRIBUTE_* constant => value
540 * @since 1.31
541 */
542 protected static function getAttributes() {
543 return [];
544 }
545
546 /**
547 * Set the PSR-3 logger interface to use for query logging. (The logger
548 * interfaces for connection logging and error logging can be set with the
549 * constructor.)
550 *
551 * @param LoggerInterface $logger
552 */
553 public function setLogger( LoggerInterface $logger ) {
554 $this->queryLogger = $logger;
555 }
556
557 public function getServerInfo() {
558 return $this->getServerVersion();
559 }
560
561 public function bufferResults( $buffer = null ) {
562 $res = !$this->getFlag( self::DBO_NOBUFFER );
563 if ( $buffer !== null ) {
564 $buffer
565 ? $this->clearFlag( self::DBO_NOBUFFER )
566 : $this->setFlag( self::DBO_NOBUFFER );
567 }
568
569 return $res;
570 }
571
572 public function trxLevel() {
573 return $this->trxLevel;
574 }
575
576 public function trxTimestamp() {
577 return $this->trxLevel ? $this->trxTimestamp : null;
578 }
579
580 /**
581 * @return int One of the STATUS_TRX_* class constants
582 * @since 1.31
583 */
584 public function trxStatus() {
585 return $this->trxStatus;
586 }
587
588 public function tablePrefix( $prefix = null ) {
589 $old = $this->tablePrefix;
590 if ( $prefix !== null ) {
591 $this->tablePrefix = $prefix;
592 $this->currentDomain = ( $this->dbName != '' )
593 ? new DatabaseDomain( $this->dbName, null, $this->tablePrefix )
594 : DatabaseDomain::newUnspecified();
595 }
596
597 return $old;
598 }
599
600 public function dbSchema( $schema = null ) {
601 $old = $this->schema;
602 if ( $schema !== null ) {
603 $this->schema = $schema;
604 }
605
606 return $old;
607 }
608
609 public function getLBInfo( $name = null ) {
610 if ( is_null( $name ) ) {
611 return $this->lbInfo;
612 } else {
613 if ( array_key_exists( $name, $this->lbInfo ) ) {
614 return $this->lbInfo[$name];
615 } else {
616 return null;
617 }
618 }
619 }
620
621 public function setLBInfo( $name, $value = null ) {
622 if ( is_null( $value ) ) {
623 $this->lbInfo = $name;
624 } else {
625 $this->lbInfo[$name] = $value;
626 }
627 }
628
629 public function setLazyMasterHandle( IDatabase $conn ) {
630 $this->lazyMasterHandle = $conn;
631 }
632
633 /**
634 * @return IDatabase|null
635 * @see setLazyMasterHandle()
636 * @since 1.27
637 */
638 protected function getLazyMasterHandle() {
639 return $this->lazyMasterHandle;
640 }
641
642 public function implicitGroupby() {
643 return true;
644 }
645
646 public function implicitOrderby() {
647 return true;
648 }
649
650 public function lastQuery() {
651 return $this->lastQuery;
652 }
653
654 public function doneWrites() {
655 return (bool)$this->lastWriteTime;
656 }
657
658 public function lastDoneWrites() {
659 return $this->lastWriteTime ?: false;
660 }
661
662 public function writesPending() {
663 return $this->trxLevel && $this->trxDoneWrites;
664 }
665
666 public function writesOrCallbacksPending() {
667 return $this->trxLevel && (
668 $this->trxDoneWrites ||
669 $this->trxIdleCallbacks ||
670 $this->trxPreCommitCallbacks ||
671 $this->trxEndCallbacks
672 );
673 }
674
675 /**
676 * @return string|null
677 */
678 final protected function getTransactionRoundId() {
679 // If transaction round participation is enabled, see if one is active
680 if ( $this->getFlag( self::DBO_TRX ) ) {
681 $id = $this->getLBInfo( 'trxRoundId' );
682
683 return is_string( $id ) ? $id : null;
684 }
685
686 return null;
687 }
688
689 public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL ) {
690 if ( !$this->trxLevel ) {
691 return false;
692 } elseif ( !$this->trxDoneWrites ) {
693 return 0.0;
694 }
695
696 switch ( $type ) {
697 case self::ESTIMATE_DB_APPLY:
698 $this->ping( $rtt );
699 $rttAdjTotal = $this->trxWriteAdjQueryCount * $rtt;
700 $applyTime = max( $this->trxWriteAdjDuration - $rttAdjTotal, 0 );
701 // For omitted queries, make them count as something at least
702 $omitted = $this->trxWriteQueryCount - $this->trxWriteAdjQueryCount;
703 $applyTime += self::TINY_WRITE_SEC * $omitted;
704
705 return $applyTime;
706 default: // everything
707 return $this->trxWriteDuration;
708 }
709 }
710
711 public function pendingWriteCallers() {
712 return $this->trxLevel ? $this->trxWriteCallers : [];
713 }
714
715 public function pendingWriteRowsAffected() {
716 return $this->trxWriteAffectedRows;
717 }
718
719 /**
720 * Get the list of method names that have pending write queries or callbacks
721 * for this transaction
722 *
723 * @return array
724 */
725 protected function pendingWriteAndCallbackCallers() {
726 if ( !$this->trxLevel ) {
727 return [];
728 }
729
730 $fnames = $this->trxWriteCallers;
731 foreach ( [
732 $this->trxIdleCallbacks,
733 $this->trxPreCommitCallbacks,
734 $this->trxEndCallbacks
735 ] as $callbacks ) {
736 foreach ( $callbacks as $callback ) {
737 $fnames[] = $callback[1];
738 }
739 }
740
741 return $fnames;
742 }
743
744 /**
745 * @return string
746 */
747 private function flatAtomicSectionList() {
748 return array_reduce( $this->trxAtomicLevels, function ( $accum, $v ) {
749 return $accum === null ? $v[0] : "$accum, " . $v[0];
750 } );
751 }
752
753 public function isOpen() {
754 return $this->opened;
755 }
756
757 public function setFlag( $flag, $remember = self::REMEMBER_NOTHING ) {
758 if ( ( $flag & self::DBO_IGNORE ) ) {
759 throw new UnexpectedValueException( "Modifying DBO_IGNORE is not allowed." );
760 }
761
762 if ( $remember === self::REMEMBER_PRIOR ) {
763 array_push( $this->priorFlags, $this->flags );
764 }
765 $this->flags |= $flag;
766 }
767
768 public function clearFlag( $flag, $remember = self::REMEMBER_NOTHING ) {
769 if ( ( $flag & self::DBO_IGNORE ) ) {
770 throw new UnexpectedValueException( "Modifying DBO_IGNORE is not allowed." );
771 }
772
773 if ( $remember === self::REMEMBER_PRIOR ) {
774 array_push( $this->priorFlags, $this->flags );
775 }
776 $this->flags &= ~$flag;
777 }
778
779 public function restoreFlags( $state = self::RESTORE_PRIOR ) {
780 if ( !$this->priorFlags ) {
781 return;
782 }
783
784 if ( $state === self::RESTORE_INITIAL ) {
785 $this->flags = reset( $this->priorFlags );
786 $this->priorFlags = [];
787 } else {
788 $this->flags = array_pop( $this->priorFlags );
789 }
790 }
791
792 public function getFlag( $flag ) {
793 return !!( $this->flags & $flag );
794 }
795
796 /**
797 * @param string $name Class field name
798 * @return mixed
799 * @deprecated Since 1.28
800 */
801 public function getProperty( $name ) {
802 return $this->$name;
803 }
804
805 public function getDomainID() {
806 return $this->currentDomain->getId();
807 }
808
809 final public function getWikiID() {
810 return $this->getDomainID();
811 }
812
813 /**
814 * Get information about an index into an object
815 * @param string $table Table name
816 * @param string $index Index name
817 * @param string $fname Calling function name
818 * @return mixed Database-specific index description class or false if the index does not exist
819 */
820 abstract function indexInfo( $table, $index, $fname = __METHOD__ );
821
822 /**
823 * Wrapper for addslashes()
824 *
825 * @param string $s String to be slashed.
826 * @return string Slashed string.
827 */
828 abstract function strencode( $s );
829
830 /**
831 * Set a custom error handler for logging errors during database connection
832 */
833 protected function installErrorHandler() {
834 $this->phpError = false;
835 $this->htmlErrors = ini_set( 'html_errors', '0' );
836 set_error_handler( [ $this, 'connectionErrorLogger' ] );
837 }
838
839 /**
840 * Restore the previous error handler and return the last PHP error for this DB
841 *
842 * @return bool|string
843 */
844 protected function restoreErrorHandler() {
845 restore_error_handler();
846 if ( $this->htmlErrors !== false ) {
847 ini_set( 'html_errors', $this->htmlErrors );
848 }
849
850 return $this->getLastPHPError();
851 }
852
853 /**
854 * @return string|bool Last PHP error for this DB (typically connection errors)
855 */
856 protected function getLastPHPError() {
857 if ( $this->phpError ) {
858 $error = preg_replace( '!\[<a.*</a>\]!', '', $this->phpError );
859 $error = preg_replace( '!^.*?:\s?(.*)$!', '$1', $error );
860
861 return $error;
862 }
863
864 return false;
865 }
866
867 /**
868 * Error handler for logging errors during database connection
869 * This method should not be used outside of Database classes
870 *
871 * @param int $errno
872 * @param string $errstr
873 */
874 public function connectionErrorLogger( $errno, $errstr ) {
875 $this->phpError = $errstr;
876 }
877
878 /**
879 * Create a log context to pass to PSR-3 logger functions.
880 *
881 * @param array $extras Additional data to add to context
882 * @return array
883 */
884 protected function getLogContext( array $extras = [] ) {
885 return array_merge(
886 [
887 'db_server' => $this->server,
888 'db_name' => $this->dbName,
889 'db_user' => $this->user,
890 ],
891 $extras
892 );
893 }
894
895 final public function close() {
896 $exception = null; // error to throw after disconnecting
897
898 if ( $this->conn ) {
899 // Resolve any dangling transaction first
900 if ( $this->trxLevel ) {
901 if ( $this->trxAtomicLevels ) {
902 // Cannot let incomplete atomic sections be committed
903 $levels = $this->flatAtomicSectionList();
904 $exception = new DBUnexpectedError(
905 $this,
906 __METHOD__ . ": atomic sections $levels are still open."
907 );
908 } elseif ( $this->trxAutomatic ) {
909 // Only the connection manager can commit non-empty DBO_TRX transactions
910 if ( $this->writesOrCallbacksPending() ) {
911 $exception = new DBUnexpectedError(
912 $this,
913 __METHOD__ .
914 ": mass commit/rollback of peer transaction required (DBO_TRX set)."
915 );
916 }
917 } elseif ( $this->trxLevel ) {
918 // Commit explicit transactions as if this was commit()
919 $this->queryLogger->warning(
920 __METHOD__ . ": writes or callbacks still pending.",
921 [ 'trace' => ( new RuntimeException() )->getTraceAsString() ]
922 );
923 }
924
925 if ( $this->trxEndCallbacksSuppressed ) {
926 $exception = $exception ?: new DBUnexpectedError(
927 $this,
928 __METHOD__ . ': callbacks are suppressed; cannot properly commit.'
929 );
930 }
931
932 // Commit or rollback the changes and run any callbacks as needed
933 if ( $this->trxStatus === self::STATUS_TRX_OK && !$exception ) {
934 $this->commit(
935 __METHOD__,
936 $this->trxAutomatic ? self::FLUSHING_INTERNAL : self::FLUSHING_ONE
937 );
938 } else {
939 $this->rollback( __METHOD__, self::FLUSHING_INTERNAL );
940 }
941 }
942
943 // Close the actual connection in the binding handle
944 $closed = $this->closeConnection();
945 $this->conn = false;
946 } else {
947 $closed = true; // already closed; nothing to do
948 }
949
950 $this->opened = false;
951
952 // Throw any unexpected errors after having disconnected
953 if ( $exception instanceof Exception ) {
954 throw $exception;
955 }
956
957 // Sanity check that no callbacks are dangling
958 if (
959 $this->trxIdleCallbacks || $this->trxPreCommitCallbacks || $this->trxEndCallbacks
960 ) {
961 throw new RuntimeException(
962 "Transaction callbacks are still pending:\n" .
963 implode( ', ', $this->pendingWriteAndCallbackCallers() )
964 );
965 }
966
967 return $closed;
968 }
969
970 /**
971 * Make sure isOpen() returns true as a sanity check
972 *
973 * @throws DBUnexpectedError
974 */
975 protected function assertOpen() {
976 if ( !$this->isOpen() ) {
977 throw new DBUnexpectedError( $this, "DB connection was already closed." );
978 }
979 }
980
981 /**
982 * Closes underlying database connection
983 * @since 1.20
984 * @return bool Whether connection was closed successfully
985 */
986 abstract protected function closeConnection();
987
988 /**
989 * @param string $error Fallback error message, used if none is given by DB
990 * @throws DBConnectionError
991 */
992 public function reportConnectionError( $error = 'Unknown error' ) {
993 $myError = $this->lastError();
994 if ( $myError ) {
995 $error = $myError;
996 }
997
998 # New method
999 throw new DBConnectionError( $this, $error );
1000 }
1001
1002 /**
1003 * Run a query and return a DBMS-dependent wrapper (that has all IResultWrapper methods)
1004 *
1005 * This might return things, such as mysqli_result, that do not formally implement
1006 * IResultWrapper, but nonetheless implement all of its methods correctly
1007 *
1008 * @param string $sql SQL query.
1009 * @return IResultWrapper|bool Iterator to feed to fetchObject/fetchRow; false on failure
1010 */
1011 abstract protected function doQuery( $sql );
1012
1013 /**
1014 * Determine whether a query writes to the DB.
1015 * Should return true if unsure.
1016 *
1017 * @param string $sql
1018 * @return bool
1019 */
1020 protected function isWriteQuery( $sql ) {
1021 return !preg_match(
1022 '/^(?:SELECT|BEGIN|ROLLBACK|COMMIT|SET|SHOW|EXPLAIN|\(SELECT)\b/i', $sql );
1023 }
1024
1025 /**
1026 * @param string $sql
1027 * @return string|null
1028 */
1029 protected function getQueryVerb( $sql ) {
1030 return preg_match( '/^\s*([a-z]+)/i', $sql, $m ) ? strtoupper( $m[1] ) : null;
1031 }
1032
1033 /**
1034 * Determine whether a SQL statement is sensitive to isolation level.
1035 * A SQL statement is considered transactable if its result could vary
1036 * depending on the transaction isolation level. Operational commands
1037 * such as 'SET' and 'SHOW' are not considered to be transactable.
1038 *
1039 * @param string $sql
1040 * @return bool
1041 */
1042 protected function isTransactableQuery( $sql ) {
1043 return !in_array(
1044 $this->getQueryVerb( $sql ),
1045 [ 'BEGIN', 'COMMIT', 'ROLLBACK', 'SHOW', 'SET', 'CREATE', 'ALTER' ],
1046 true
1047 );
1048 }
1049
1050 /**
1051 * @param string $sql A SQL query
1052 * @return bool Whether $sql is SQL for TEMPORARY table operation
1053 */
1054 protected function registerTempTableOperation( $sql ) {
1055 if ( preg_match(
1056 '/^CREATE\s+TEMPORARY\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[`"\']?(\w+)[`"\']?/i',
1057 $sql,
1058 $matches
1059 ) ) {
1060 $this->sessionTempTables[$matches[1]] = 1;
1061
1062 return true;
1063 } elseif ( preg_match(
1064 '/^DROP\s+(?:TEMPORARY\s+)?TABLE\s+(?:IF\s+EXISTS\s+)?[`"\']?(\w+)[`"\']?/i',
1065 $sql,
1066 $matches
1067 ) ) {
1068 $isTemp = isset( $this->sessionTempTables[$matches[1]] );
1069 unset( $this->sessionTempTables[$matches[1]] );
1070
1071 return $isTemp;
1072 } elseif ( preg_match(
1073 '/^TRUNCATE\s+(?:TEMPORARY\s+)?TABLE\s+(?:IF\s+EXISTS\s+)?[`"\']?(\w+)[`"\']?/i',
1074 $sql,
1075 $matches
1076 ) ) {
1077 return isset( $this->sessionTempTables[$matches[1]] );
1078 } elseif ( preg_match(
1079 '/^(?:INSERT\s+(?:\w+\s+)?INTO|UPDATE|DELETE\s+FROM)\s+[`"\']?(\w+)[`"\']?/i',
1080 $sql,
1081 $matches
1082 ) ) {
1083 return isset( $this->sessionTempTables[$matches[1]] );
1084 }
1085
1086 return false;
1087 }
1088
1089 public function query( $sql, $fname = __METHOD__, $tempIgnore = false ) {
1090 $this->assertTransactionStatus( $sql, $fname );
1091
1092 # Avoid fatals if close() was called
1093 $this->assertOpen();
1094
1095 $priorWritesPending = $this->writesOrCallbacksPending();
1096 $this->lastQuery = $sql;
1097
1098 $isWrite = $this->isWriteQuery( $sql );
1099 if ( $isWrite ) {
1100 $isNonTempWrite = !$this->registerTempTableOperation( $sql );
1101 } else {
1102 $isNonTempWrite = false;
1103 }
1104
1105 if ( $isWrite ) {
1106 if ( $this->getLBInfo( 'replica' ) === true ) {
1107 throw new DBError(
1108 $this,
1109 'Write operations are not allowed on replica database connections.'
1110 );
1111 }
1112 # In theory, non-persistent writes are allowed in read-only mode, but due to things
1113 # like https://bugs.mysql.com/bug.php?id=33669 that might not work anyway...
1114 $reason = $this->getReadOnlyReason();
1115 if ( $reason !== false ) {
1116 throw new DBReadOnlyError( $this, "Database is read-only: $reason" );
1117 }
1118 # Set a flag indicating that writes have been done
1119 $this->lastWriteTime = microtime( true );
1120 }
1121
1122 # Add trace comment to the begin of the sql string, right after the operator.
1123 # Or, for one-word queries (like "BEGIN" or COMMIT") add it to the end (T44598)
1124 $commentedSql = preg_replace( '/\s|$/', " /* $fname {$this->agent} */ ", $sql, 1 );
1125
1126 # Start implicit transactions that wrap the request if DBO_TRX is enabled
1127 if ( !$this->trxLevel && $this->getFlag( self::DBO_TRX )
1128 && $this->isTransactableQuery( $sql )
1129 ) {
1130 $this->begin( __METHOD__ . " ($fname)", self::TRANSACTION_INTERNAL );
1131 $this->trxAutomatic = true;
1132 }
1133
1134 # Keep track of whether the transaction has write queries pending
1135 if ( $this->trxLevel && !$this->trxDoneWrites && $isWrite ) {
1136 $this->trxDoneWrites = true;
1137 $this->trxProfiler->transactionWritingIn(
1138 $this->server, $this->dbName, $this->trxShortId );
1139 }
1140
1141 if ( $this->getFlag( self::DBO_DEBUG ) ) {
1142 $this->queryLogger->debug( "{$this->dbName} {$commentedSql}" );
1143 }
1144
1145 # Send the query to the server and fetch any corresponding errors
1146 $ret = $this->doProfiledQuery( $sql, $commentedSql, $isNonTempWrite, $fname );
1147 $lastError = $this->lastError();
1148 $lastErrno = $this->lastErrno();
1149
1150 # Try reconnecting if the connection was lost
1151 if ( $ret === false && $this->wasConnectionLoss() ) {
1152 # Check if any meaningful session state was lost
1153 $recoverable = $this->canRecoverFromDisconnect( $sql, $priorWritesPending );
1154 # Update session state tracking and try to restore the connection
1155 $reconnected = $this->replaceLostConnection( __METHOD__ );
1156 # Silently resend the query to the server if it is safe and possible
1157 if ( $reconnected && $recoverable ) {
1158 $ret = $this->doProfiledQuery( $sql, $commentedSql, $isNonTempWrite, $fname );
1159 $lastError = $this->lastError();
1160 $lastErrno = $this->lastErrno();
1161
1162 if ( $ret === false && $this->wasConnectionLoss() ) {
1163 # Query probably causes disconnects; reconnect and do not re-run it
1164 $this->replaceLostConnection( __METHOD__ );
1165 }
1166 }
1167 }
1168
1169 if ( $ret === false ) {
1170 if ( $this->trxLevel ) {
1171 if ( !$this->wasKnownStatementRollbackError() ) {
1172 # Either the query was aborted or all queries after BEGIN where aborted.
1173 if ( $this->explicitTrxActive() || $priorWritesPending ) {
1174 # In the first case, the only options going forward are (a) ROLLBACK, or
1175 # (b) ROLLBACK TO SAVEPOINT (if one was set). If the later case, the only
1176 # option is ROLLBACK, since the snapshots would have been released.
1177 $this->trxStatus = self::STATUS_TRX_ERROR;
1178 $this->trxStatusCause =
1179 $this->makeQueryException( $lastError, $lastErrno, $sql, $fname );
1180 $tempIgnore = false; // cannot recover
1181 } else {
1182 # Nothing prior was there to lose from the transaction,
1183 # so just roll it back.
1184 $this->doRollback( __METHOD__ . " ($fname)" );
1185 $this->trxStatus = self::STATUS_TRX_OK;
1186 }
1187 $this->trxStatusIgnoredCause = null;
1188 } else {
1189 # We're ignoring an error that caused just the current query to be aborted.
1190 # But log the cause so we can log a deprecation notice if a
1191 # caller actually does ignore it.
1192 $this->trxStatusIgnoredCause = [ $lastError, $lastErrno, $fname ];
1193 }
1194 }
1195
1196 $this->reportQueryError( $lastError, $lastErrno, $sql, $fname, $tempIgnore );
1197 }
1198
1199 return $this->resultObject( $ret );
1200 }
1201
1202 /**
1203 * Wrapper for query() that also handles profiling, logging, and affected row count updates
1204 *
1205 * @param string $sql Original SQL query
1206 * @param string $commentedSql SQL query with debugging/trace comment
1207 * @param bool $isWrite Whether the query is a (non-temporary) write operation
1208 * @param string $fname Name of the calling function
1209 * @return bool|ResultWrapper True for a successful write query, ResultWrapper
1210 * object for a successful read query, or false on failure
1211 */
1212 private function doProfiledQuery( $sql, $commentedSql, $isWrite, $fname ) {
1213 $isMaster = !is_null( $this->getLBInfo( 'master' ) );
1214 # generalizeSQL() will probably cut down the query to reasonable
1215 # logging size most of the time. The substr is really just a sanity check.
1216 if ( $isMaster ) {
1217 $queryProf = 'query-m: ' . substr( self::generalizeSQL( $sql ), 0, 255 );
1218 } else {
1219 $queryProf = 'query: ' . substr( self::generalizeSQL( $sql ), 0, 255 );
1220 }
1221
1222 # Include query transaction state
1223 $queryProf .= $this->trxShortId ? " [TRX#{$this->trxShortId}]" : "";
1224
1225 $startTime = microtime( true );
1226 if ( $this->profiler ) {
1227 call_user_func( [ $this->profiler, 'profileIn' ], $queryProf );
1228 }
1229 $this->affectedRowCount = null;
1230 $ret = $this->doQuery( $commentedSql );
1231 $this->affectedRowCount = $this->affectedRows();
1232 if ( $this->profiler ) {
1233 call_user_func( [ $this->profiler, 'profileOut' ], $queryProf );
1234 }
1235 $queryRuntime = max( microtime( true ) - $startTime, 0.0 );
1236
1237 unset( $queryProfSection ); // profile out (if set)
1238
1239 if ( $ret !== false ) {
1240 $this->lastPing = $startTime;
1241 if ( $isWrite && $this->trxLevel ) {
1242 $this->updateTrxWriteQueryTime( $sql, $queryRuntime, $this->affectedRows() );
1243 $this->trxWriteCallers[] = $fname;
1244 }
1245 }
1246
1247 if ( $sql === self::PING_QUERY ) {
1248 $this->rttEstimate = $queryRuntime;
1249 }
1250
1251 $this->trxProfiler->recordQueryCompletion(
1252 $queryProf, $startTime, $isWrite, $this->affectedRows()
1253 );
1254 $this->queryLogger->debug( $sql, [
1255 'method' => $fname,
1256 'master' => $isMaster,
1257 'runtime' => $queryRuntime,
1258 ] );
1259
1260 return $ret;
1261 }
1262
1263 /**
1264 * Update the estimated run-time of a query, not counting large row lock times
1265 *
1266 * LoadBalancer can be set to rollback transactions that will create huge replication
1267 * lag. It bases this estimate off of pendingWriteQueryDuration(). Certain simple
1268 * queries, like inserting a row can take a long time due to row locking. This method
1269 * uses some simple heuristics to discount those cases.
1270 *
1271 * @param string $sql A SQL write query
1272 * @param float $runtime Total runtime, including RTT
1273 * @param int $affected Affected row count
1274 */
1275 private function updateTrxWriteQueryTime( $sql, $runtime, $affected ) {
1276 // Whether this is indicative of replica DB runtime (except for RBR or ws_repl)
1277 $indicativeOfReplicaRuntime = true;
1278 if ( $runtime > self::SLOW_WRITE_SEC ) {
1279 $verb = $this->getQueryVerb( $sql );
1280 // insert(), upsert(), replace() are fast unless bulky in size or blocked on locks
1281 if ( $verb === 'INSERT' ) {
1282 $indicativeOfReplicaRuntime = $this->affectedRows() > self::SMALL_WRITE_ROWS;
1283 } elseif ( $verb === 'REPLACE' ) {
1284 $indicativeOfReplicaRuntime = $this->affectedRows() > self::SMALL_WRITE_ROWS / 2;
1285 }
1286 }
1287
1288 $this->trxWriteDuration += $runtime;
1289 $this->trxWriteQueryCount += 1;
1290 $this->trxWriteAffectedRows += $affected;
1291 if ( $indicativeOfReplicaRuntime ) {
1292 $this->trxWriteAdjDuration += $runtime;
1293 $this->trxWriteAdjQueryCount += 1;
1294 }
1295 }
1296
1297 /**
1298 * @param string $sql
1299 * @param string $fname
1300 * @throws DBTransactionStateError
1301 */
1302 private function assertTransactionStatus( $sql, $fname ) {
1303 if ( $this->getQueryVerb( $sql ) === 'ROLLBACK' ) { // transaction/savepoint
1304 return;
1305 }
1306
1307 if ( $this->trxStatus < self::STATUS_TRX_OK ) {
1308 throw new DBTransactionStateError(
1309 $this,
1310 "Cannot execute query from $fname while transaction status is ERROR. ",
1311 [],
1312 $this->trxStatusCause
1313 );
1314 } elseif ( $this->trxStatus === self::STATUS_TRX_OK && $this->trxStatusIgnoredCause ) {
1315 list( $iLastError, $iLastErrno, $iFname ) = $this->trxStatusIgnoredCause;
1316 call_user_func( $this->deprecationLogger,
1317 "Caller from $fname ignored an error originally raised from $iFname: " .
1318 "[$iLastErrno] $iLastError"
1319 );
1320 $this->trxStatusIgnoredCause = null;
1321 }
1322 }
1323
1324 /**
1325 * Determine whether or not it is safe to retry queries after a database
1326 * connection is lost
1327 *
1328 * @param string $sql SQL query
1329 * @param bool $priorWritesPending Whether there is a transaction open with
1330 * possible write queries or transaction pre-commit/idle callbacks
1331 * waiting on it to finish.
1332 * @return bool True if it is safe to retry the query, false otherwise
1333 */
1334 private function canRecoverFromDisconnect( $sql, $priorWritesPending ) {
1335 # Transaction dropped; this can mean lost writes, or REPEATABLE-READ snapshots.
1336 # Dropped connections also mean that named locks are automatically released.
1337 # Only allow error suppression in autocommit mode or when the lost transaction
1338 # didn't matter anyway (aside from DBO_TRX snapshot loss).
1339 if ( $this->namedLocksHeld ) {
1340 return false; // possible critical section violation
1341 } elseif ( $this->sessionTempTables ) {
1342 return false; // tables might be queried latter
1343 } elseif ( $sql === 'COMMIT' ) {
1344 return !$priorWritesPending; // nothing written anyway? (T127428)
1345 } elseif ( $sql === 'ROLLBACK' ) {
1346 return true; // transaction lost...which is also what was requested :)
1347 } elseif ( $this->explicitTrxActive() ) {
1348 return false; // don't drop atomocity and explicit snapshots
1349 } elseif ( $priorWritesPending ) {
1350 return false; // prior writes lost from implicit transaction
1351 }
1352
1353 return true;
1354 }
1355
1356 /**
1357 * Clean things up after session (and thus transaction) loss
1358 */
1359 private function handleSessionLoss() {
1360 // Clean up tracking of session-level things...
1361 // https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html
1362 // https://www.postgresql.org/docs/9.2/static/sql-createtable.html (ignoring ON COMMIT)
1363 $this->sessionTempTables = [];
1364 // https://dev.mysql.com/doc/refman/5.7/en/miscellaneous-functions.html#function_get-lock
1365 // https://www.postgresql.org/docs/9.4/static/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS
1366 $this->namedLocksHeld = [];
1367 // Session loss implies transaction loss
1368 $this->handleTransactionLoss();
1369 }
1370
1371 /**
1372 * Clean things up after transaction loss
1373 */
1374 private function handleTransactionLoss() {
1375 $this->trxLevel = 0;
1376 $this->trxAtomicCounter = 0;
1377 $this->trxIdleCallbacks = []; // T67263; transaction already lost
1378 $this->trxPreCommitCallbacks = []; // T67263; transaction already lost
1379 try {
1380 // Handle callbacks in trxEndCallbacks, e.g. onTransactionResolution().
1381 // If callback suppression is set then the array will remain unhandled.
1382 $this->runOnTransactionIdleCallbacks( self::TRIGGER_ROLLBACK );
1383 } catch ( Exception $ex ) {
1384 // Already logged; move on...
1385 }
1386 try {
1387 // Handle callbacks in trxRecurringCallbacks, e.g. setTransactionListener()
1388 $this->runTransactionListenerCallbacks( self::TRIGGER_ROLLBACK );
1389 } catch ( Exception $ex ) {
1390 // Already logged; move on...
1391 }
1392 }
1393
1394 /**
1395 * Checks whether the cause of the error is detected to be a timeout.
1396 *
1397 * It returns false by default, and not all engines support detecting this yet.
1398 * If this returns false, it will be treated as a generic query error.
1399 *
1400 * @param string $error Error text
1401 * @param int $errno Error number
1402 * @return bool
1403 */
1404 protected function wasQueryTimeout( $error, $errno ) {
1405 return false;
1406 }
1407
1408 /**
1409 * Report a query error. Log the error, and if neither the object ignore
1410 * flag nor the $tempIgnore flag is set, throw a DBQueryError.
1411 *
1412 * @param string $error
1413 * @param int $errno
1414 * @param string $sql
1415 * @param string $fname
1416 * @param bool $tempIgnore
1417 * @throws DBQueryError
1418 */
1419 public function reportQueryError( $error, $errno, $sql, $fname, $tempIgnore = false ) {
1420 if ( $tempIgnore ) {
1421 $this->queryLogger->debug( "SQL ERROR (ignored): $error\n" );
1422 } else {
1423 $exception = $this->makeQueryException( $error, $errno, $sql, $fname );
1424
1425 throw $exception;
1426 }
1427 }
1428
1429 /**
1430 * @param string $error
1431 * @param string|int $errno
1432 * @param string $sql
1433 * @param string $fname
1434 * @return DBError
1435 */
1436 private function makeQueryException( $error, $errno, $sql, $fname ) {
1437 $sql1line = mb_substr( str_replace( "\n", "\\n", $sql ), 0, 5 * 1024 );
1438 $this->queryLogger->error(
1439 "{fname}\t{db_server}\t{errno}\t{error}\t{sql1line}",
1440 $this->getLogContext( [
1441 'method' => __METHOD__,
1442 'errno' => $errno,
1443 'error' => $error,
1444 'sql1line' => $sql1line,
1445 'fname' => $fname,
1446 ] )
1447 );
1448 $this->queryLogger->debug( "SQL ERROR: " . $error . "\n" );
1449 $wasQueryTimeout = $this->wasQueryTimeout( $error, $errno );
1450 if ( $wasQueryTimeout ) {
1451 $e = new DBQueryTimeoutError( $this, $error, $errno, $sql, $fname );
1452 } else {
1453 $e = new DBQueryError( $this, $error, $errno, $sql, $fname );
1454 }
1455
1456 return $e;
1457 }
1458
1459 public function freeResult( $res ) {
1460 }
1461
1462 public function selectField(
1463 $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
1464 ) {
1465 if ( $var === '*' ) { // sanity
1466 throw new DBUnexpectedError( $this, "Cannot use a * field: got '$var'" );
1467 }
1468
1469 if ( !is_array( $options ) ) {
1470 $options = [ $options ];
1471 }
1472
1473 $options['LIMIT'] = 1;
1474
1475 $res = $this->select( $table, $var, $cond, $fname, $options, $join_conds );
1476 if ( $res === false || !$this->numRows( $res ) ) {
1477 return false;
1478 }
1479
1480 $row = $this->fetchRow( $res );
1481
1482 if ( $row !== false ) {
1483 return reset( $row );
1484 } else {
1485 return false;
1486 }
1487 }
1488
1489 public function selectFieldValues(
1490 $table, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = []
1491 ) {
1492 if ( $var === '*' ) { // sanity
1493 throw new DBUnexpectedError( $this, "Cannot use a * field" );
1494 } elseif ( !is_string( $var ) ) { // sanity
1495 throw new DBUnexpectedError( $this, "Cannot use an array of fields" );
1496 }
1497
1498 if ( !is_array( $options ) ) {
1499 $options = [ $options ];
1500 }
1501
1502 $res = $this->select( $table, $var, $cond, $fname, $options, $join_conds );
1503 if ( $res === false ) {
1504 return false;
1505 }
1506
1507 $values = [];
1508 foreach ( $res as $row ) {
1509 $values[] = $row->$var;
1510 }
1511
1512 return $values;
1513 }
1514
1515 /**
1516 * Returns an optional USE INDEX clause to go after the table, and a
1517 * string to go at the end of the query.
1518 *
1519 * @param array $options Associative array of options to be turned into
1520 * an SQL query, valid keys are listed in the function.
1521 * @return array
1522 * @see Database::select()
1523 */
1524 protected function makeSelectOptions( $options ) {
1525 $preLimitTail = $postLimitTail = '';
1526 $startOpts = '';
1527
1528 $noKeyOptions = [];
1529
1530 foreach ( $options as $key => $option ) {
1531 if ( is_numeric( $key ) ) {
1532 $noKeyOptions[$option] = true;
1533 }
1534 }
1535
1536 $preLimitTail .= $this->makeGroupByWithHaving( $options );
1537
1538 $preLimitTail .= $this->makeOrderBy( $options );
1539
1540 if ( isset( $noKeyOptions['FOR UPDATE'] ) ) {
1541 $postLimitTail .= ' FOR UPDATE';
1542 }
1543
1544 if ( isset( $noKeyOptions['LOCK IN SHARE MODE'] ) ) {
1545 $postLimitTail .= ' LOCK IN SHARE MODE';
1546 }
1547
1548 if ( isset( $noKeyOptions['DISTINCT'] ) || isset( $noKeyOptions['DISTINCTROW'] ) ) {
1549 $startOpts .= 'DISTINCT';
1550 }
1551
1552 # Various MySQL extensions
1553 if ( isset( $noKeyOptions['STRAIGHT_JOIN'] ) ) {
1554 $startOpts .= ' /*! STRAIGHT_JOIN */';
1555 }
1556
1557 if ( isset( $noKeyOptions['HIGH_PRIORITY'] ) ) {
1558 $startOpts .= ' HIGH_PRIORITY';
1559 }
1560
1561 if ( isset( $noKeyOptions['SQL_BIG_RESULT'] ) ) {
1562 $startOpts .= ' SQL_BIG_RESULT';
1563 }
1564
1565 if ( isset( $noKeyOptions['SQL_BUFFER_RESULT'] ) ) {
1566 $startOpts .= ' SQL_BUFFER_RESULT';
1567 }
1568
1569 if ( isset( $noKeyOptions['SQL_SMALL_RESULT'] ) ) {
1570 $startOpts .= ' SQL_SMALL_RESULT';
1571 }
1572
1573 if ( isset( $noKeyOptions['SQL_CALC_FOUND_ROWS'] ) ) {
1574 $startOpts .= ' SQL_CALC_FOUND_ROWS';
1575 }
1576
1577 if ( isset( $noKeyOptions['SQL_CACHE'] ) ) {
1578 $startOpts .= ' SQL_CACHE';
1579 }
1580
1581 if ( isset( $noKeyOptions['SQL_NO_CACHE'] ) ) {
1582 $startOpts .= ' SQL_NO_CACHE';
1583 }
1584
1585 if ( isset( $options['USE INDEX'] ) && is_string( $options['USE INDEX'] ) ) {
1586 $useIndex = $this->useIndexClause( $options['USE INDEX'] );
1587 } else {
1588 $useIndex = '';
1589 }
1590 if ( isset( $options['IGNORE INDEX'] ) && is_string( $options['IGNORE INDEX'] ) ) {
1591 $ignoreIndex = $this->ignoreIndexClause( $options['IGNORE INDEX'] );
1592 } else {
1593 $ignoreIndex = '';
1594 }
1595
1596 return [ $startOpts, $useIndex, $preLimitTail, $postLimitTail, $ignoreIndex ];
1597 }
1598
1599 /**
1600 * Returns an optional GROUP BY with an optional HAVING
1601 *
1602 * @param array $options Associative array of options
1603 * @return string
1604 * @see Database::select()
1605 * @since 1.21
1606 */
1607 protected function makeGroupByWithHaving( $options ) {
1608 $sql = '';
1609 if ( isset( $options['GROUP BY'] ) ) {
1610 $gb = is_array( $options['GROUP BY'] )
1611 ? implode( ',', $options['GROUP BY'] )
1612 : $options['GROUP BY'];
1613 $sql .= ' GROUP BY ' . $gb;
1614 }
1615 if ( isset( $options['HAVING'] ) ) {
1616 $having = is_array( $options['HAVING'] )
1617 ? $this->makeList( $options['HAVING'], self::LIST_AND )
1618 : $options['HAVING'];
1619 $sql .= ' HAVING ' . $having;
1620 }
1621
1622 return $sql;
1623 }
1624
1625 /**
1626 * Returns an optional ORDER BY
1627 *
1628 * @param array $options Associative array of options
1629 * @return string
1630 * @see Database::select()
1631 * @since 1.21
1632 */
1633 protected function makeOrderBy( $options ) {
1634 if ( isset( $options['ORDER BY'] ) ) {
1635 $ob = is_array( $options['ORDER BY'] )
1636 ? implode( ',', $options['ORDER BY'] )
1637 : $options['ORDER BY'];
1638
1639 return ' ORDER BY ' . $ob;
1640 }
1641
1642 return '';
1643 }
1644
1645 public function select( $table, $vars, $conds = '', $fname = __METHOD__,
1646 $options = [], $join_conds = [] ) {
1647 $sql = $this->selectSQLText( $table, $vars, $conds, $fname, $options, $join_conds );
1648
1649 return $this->query( $sql, $fname );
1650 }
1651
1652 public function selectSQLText( $table, $vars, $conds = '', $fname = __METHOD__,
1653 $options = [], $join_conds = []
1654 ) {
1655 if ( is_array( $vars ) ) {
1656 $vars = implode( ',', $this->fieldNamesWithAlias( $vars ) );
1657 }
1658
1659 $options = (array)$options;
1660 $useIndexes = ( isset( $options['USE INDEX'] ) && is_array( $options['USE INDEX'] ) )
1661 ? $options['USE INDEX']
1662 : [];
1663 $ignoreIndexes = (
1664 isset( $options['IGNORE INDEX'] ) &&
1665 is_array( $options['IGNORE INDEX'] )
1666 )
1667 ? $options['IGNORE INDEX']
1668 : [];
1669
1670 if ( is_array( $table ) ) {
1671 $from = ' FROM ' .
1672 $this->tableNamesWithIndexClauseOrJOIN(
1673 $table, $useIndexes, $ignoreIndexes, $join_conds );
1674 } elseif ( $table != '' ) {
1675 $from = ' FROM ' .
1676 $this->tableNamesWithIndexClauseOrJOIN(
1677 [ $table ], $useIndexes, $ignoreIndexes, [] );
1678 } else {
1679 $from = '';
1680 }
1681
1682 list( $startOpts, $useIndex, $preLimitTail, $postLimitTail, $ignoreIndex ) =
1683 $this->makeSelectOptions( $options );
1684
1685 if ( is_array( $conds ) ) {
1686 $conds = $this->makeList( $conds, self::LIST_AND );
1687 }
1688
1689 if ( $conds === null || $conds === false ) {
1690 $this->queryLogger->warning(
1691 __METHOD__
1692 . ' called from '
1693 . $fname
1694 . ' with incorrect parameters: $conds must be a string or an array'
1695 );
1696 $conds = '';
1697 }
1698
1699 if ( $conds === '' ) {
1700 $sql = "SELECT $startOpts $vars $from $useIndex $ignoreIndex $preLimitTail";
1701 } elseif ( is_string( $conds ) ) {
1702 $sql = "SELECT $startOpts $vars $from $useIndex $ignoreIndex " .
1703 "WHERE $conds $preLimitTail";
1704 } else {
1705 throw new DBUnexpectedError( $this, __METHOD__ . ' called with incorrect parameters' );
1706 }
1707
1708 if ( isset( $options['LIMIT'] ) ) {
1709 $sql = $this->limitResult( $sql, $options['LIMIT'],
1710 isset( $options['OFFSET'] ) ? $options['OFFSET'] : false );
1711 }
1712 $sql = "$sql $postLimitTail";
1713
1714 if ( isset( $options['EXPLAIN'] ) ) {
1715 $sql = 'EXPLAIN ' . $sql;
1716 }
1717
1718 return $sql;
1719 }
1720
1721 public function selectRow( $table, $vars, $conds, $fname = __METHOD__,
1722 $options = [], $join_conds = []
1723 ) {
1724 $options = (array)$options;
1725 $options['LIMIT'] = 1;
1726 $res = $this->select( $table, $vars, $conds, $fname, $options, $join_conds );
1727
1728 if ( $res === false ) {
1729 return false;
1730 }
1731
1732 if ( !$this->numRows( $res ) ) {
1733 return false;
1734 }
1735
1736 $obj = $this->fetchObject( $res );
1737
1738 return $obj;
1739 }
1740
1741 public function estimateRowCount(
1742 $table, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
1743 ) {
1744 $conds = $this->normalizeConditions( $conds, $fname );
1745 $column = $this->extractSingleFieldFromList( $var );
1746 if ( is_string( $column ) && !in_array( $column, [ '*', '1' ] ) ) {
1747 $conds[] = "$column IS NOT NULL";
1748 }
1749
1750 $res = $this->select(
1751 $table, [ 'rowcount' => 'COUNT(*)' ], $conds, $fname, $options, $join_conds
1752 );
1753 $row = $res ? $this->fetchRow( $res ) : [];
1754
1755 return isset( $row['rowcount'] ) ? (int)$row['rowcount'] : 0;
1756 }
1757
1758 public function selectRowCount(
1759 $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
1760 ) {
1761 $conds = $this->normalizeConditions( $conds, $fname );
1762 $column = $this->extractSingleFieldFromList( $var );
1763 if ( is_string( $column ) && !in_array( $column, [ '*', '1' ] ) ) {
1764 $conds[] = "$column IS NOT NULL";
1765 }
1766
1767 $res = $this->select(
1768 [
1769 'tmp_count' => $this->buildSelectSubquery(
1770 $tables,
1771 '1',
1772 $conds,
1773 $fname,
1774 $options,
1775 $join_conds
1776 )
1777 ],
1778 [ 'rowcount' => 'COUNT(*)' ],
1779 [],
1780 $fname
1781 );
1782 $row = $res ? $this->fetchRow( $res ) : [];
1783
1784 return isset( $row['rowcount'] ) ? (int)$row['rowcount'] : 0;
1785 }
1786
1787 /**
1788 * @param array|string $conds
1789 * @param string $fname
1790 * @return array
1791 */
1792 final protected function normalizeConditions( $conds, $fname ) {
1793 if ( $conds === null || $conds === false ) {
1794 $this->queryLogger->warning(
1795 __METHOD__
1796 . ' called from '
1797 . $fname
1798 . ' with incorrect parameters: $conds must be a string or an array'
1799 );
1800 $conds = '';
1801 }
1802
1803 if ( !is_array( $conds ) ) {
1804 $conds = ( $conds === '' ) ? [] : [ $conds ];
1805 }
1806
1807 return $conds;
1808 }
1809
1810 /**
1811 * @param array|string $var Field parameter in the style of select()
1812 * @return string|null Column name or null; ignores aliases
1813 * @throws DBUnexpectedError Errors out if multiple columns are given
1814 */
1815 final protected function extractSingleFieldFromList( $var ) {
1816 if ( is_array( $var ) ) {
1817 if ( !$var ) {
1818 $column = null;
1819 } elseif ( count( $var ) == 1 ) {
1820 $column = isset( $var[0] ) ? $var[0] : reset( $var );
1821 } else {
1822 throw new DBUnexpectedError( $this, __METHOD__ . ': got multiple columns.' );
1823 }
1824 } else {
1825 $column = $var;
1826 }
1827
1828 return $column;
1829 }
1830
1831 /**
1832 * Removes most variables from an SQL query and replaces them with X or N for numbers.
1833 * It's only slightly flawed. Don't use for anything important.
1834 *
1835 * @param string $sql A SQL Query
1836 *
1837 * @return string
1838 */
1839 protected static function generalizeSQL( $sql ) {
1840 # This does the same as the regexp below would do, but in such a way
1841 # as to avoid crashing php on some large strings.
1842 # $sql = preg_replace( "/'([^\\\\']|\\\\.)*'|\"([^\\\\\"]|\\\\.)*\"/", "'X'", $sql );
1843
1844 $sql = str_replace( "\\\\", '', $sql );
1845 $sql = str_replace( "\\'", '', $sql );
1846 $sql = str_replace( "\\\"", '', $sql );
1847 $sql = preg_replace( "/'.*'/s", "'X'", $sql );
1848 $sql = preg_replace( '/".*"/s', "'X'", $sql );
1849
1850 # All newlines, tabs, etc replaced by single space
1851 $sql = preg_replace( '/\s+/', ' ', $sql );
1852
1853 # All numbers => N,
1854 # except the ones surrounded by characters, e.g. l10n
1855 $sql = preg_replace( '/-?\d+(,-?\d+)+/s', 'N,...,N', $sql );
1856 $sql = preg_replace( '/(?<![a-zA-Z])-?\d+(?![a-zA-Z])/s', 'N', $sql );
1857
1858 return $sql;
1859 }
1860
1861 public function fieldExists( $table, $field, $fname = __METHOD__ ) {
1862 $info = $this->fieldInfo( $table, $field );
1863
1864 return (bool)$info;
1865 }
1866
1867 public function indexExists( $table, $index, $fname = __METHOD__ ) {
1868 if ( !$this->tableExists( $table ) ) {
1869 return null;
1870 }
1871
1872 $info = $this->indexInfo( $table, $index, $fname );
1873 if ( is_null( $info ) ) {
1874 return null;
1875 } else {
1876 return $info !== false;
1877 }
1878 }
1879
1880 public function tableExists( $table, $fname = __METHOD__ ) {
1881 $tableRaw = $this->tableName( $table, 'raw' );
1882 if ( isset( $this->sessionTempTables[$tableRaw] ) ) {
1883 return true; // already known to exist
1884 }
1885
1886 $table = $this->tableName( $table );
1887 $ignoreErrors = true;
1888 $res = $this->query( "SELECT 1 FROM $table LIMIT 1", $fname, $ignoreErrors );
1889
1890 return (bool)$res;
1891 }
1892
1893 public function indexUnique( $table, $index ) {
1894 $indexInfo = $this->indexInfo( $table, $index );
1895
1896 if ( !$indexInfo ) {
1897 return null;
1898 }
1899
1900 return !$indexInfo[0]->Non_unique;
1901 }
1902
1903 /**
1904 * Helper for Database::insert().
1905 *
1906 * @param array $options
1907 * @return string
1908 */
1909 protected function makeInsertOptions( $options ) {
1910 return implode( ' ', $options );
1911 }
1912
1913 public function insert( $table, $a, $fname = __METHOD__, $options = [] ) {
1914 # No rows to insert, easy just return now
1915 if ( !count( $a ) ) {
1916 return true;
1917 }
1918
1919 $table = $this->tableName( $table );
1920
1921 if ( !is_array( $options ) ) {
1922 $options = [ $options ];
1923 }
1924
1925 $fh = null;
1926 if ( isset( $options['fileHandle'] ) ) {
1927 $fh = $options['fileHandle'];
1928 }
1929 $options = $this->makeInsertOptions( $options );
1930
1931 if ( isset( $a[0] ) && is_array( $a[0] ) ) {
1932 $multi = true;
1933 $keys = array_keys( $a[0] );
1934 } else {
1935 $multi = false;
1936 $keys = array_keys( $a );
1937 }
1938
1939 $sql = 'INSERT ' . $options .
1940 " INTO $table (" . implode( ',', $keys ) . ') VALUES ';
1941
1942 if ( $multi ) {
1943 $first = true;
1944 foreach ( $a as $row ) {
1945 if ( $first ) {
1946 $first = false;
1947 } else {
1948 $sql .= ',';
1949 }
1950 $sql .= '(' . $this->makeList( $row ) . ')';
1951 }
1952 } else {
1953 $sql .= '(' . $this->makeList( $a ) . ')';
1954 }
1955
1956 if ( $fh !== null && false === fwrite( $fh, $sql ) ) {
1957 return false;
1958 } elseif ( $fh !== null ) {
1959 return true;
1960 }
1961
1962 return (bool)$this->query( $sql, $fname );
1963 }
1964
1965 /**
1966 * Make UPDATE options array for Database::makeUpdateOptions
1967 *
1968 * @param array $options
1969 * @return array
1970 */
1971 protected function makeUpdateOptionsArray( $options ) {
1972 if ( !is_array( $options ) ) {
1973 $options = [ $options ];
1974 }
1975
1976 $opts = [];
1977
1978 if ( in_array( 'IGNORE', $options ) ) {
1979 $opts[] = 'IGNORE';
1980 }
1981
1982 return $opts;
1983 }
1984
1985 /**
1986 * Make UPDATE options for the Database::update function
1987 *
1988 * @param array $options The options passed to Database::update
1989 * @return string
1990 */
1991 protected function makeUpdateOptions( $options ) {
1992 $opts = $this->makeUpdateOptionsArray( $options );
1993
1994 return implode( ' ', $opts );
1995 }
1996
1997 public function update( $table, $values, $conds, $fname = __METHOD__, $options = [] ) {
1998 $table = $this->tableName( $table );
1999 $opts = $this->makeUpdateOptions( $options );
2000 $sql = "UPDATE $opts $table SET " . $this->makeList( $values, self::LIST_SET );
2001
2002 if ( $conds !== [] && $conds !== '*' ) {
2003 $sql .= " WHERE " . $this->makeList( $conds, self::LIST_AND );
2004 }
2005
2006 return (bool)$this->query( $sql, $fname );
2007 }
2008
2009 public function makeList( $a, $mode = self::LIST_COMMA ) {
2010 if ( !is_array( $a ) ) {
2011 throw new DBUnexpectedError( $this, __METHOD__ . ' called with incorrect parameters' );
2012 }
2013
2014 $first = true;
2015 $list = '';
2016
2017 foreach ( $a as $field => $value ) {
2018 if ( !$first ) {
2019 if ( $mode == self::LIST_AND ) {
2020 $list .= ' AND ';
2021 } elseif ( $mode == self::LIST_OR ) {
2022 $list .= ' OR ';
2023 } else {
2024 $list .= ',';
2025 }
2026 } else {
2027 $first = false;
2028 }
2029
2030 if ( ( $mode == self::LIST_AND || $mode == self::LIST_OR ) && is_numeric( $field ) ) {
2031 $list .= "($value)";
2032 } elseif ( $mode == self::LIST_SET && is_numeric( $field ) ) {
2033 $list .= "$value";
2034 } elseif (
2035 ( $mode == self::LIST_AND || $mode == self::LIST_OR ) && is_array( $value )
2036 ) {
2037 // Remove null from array to be handled separately if found
2038 $includeNull = false;
2039 foreach ( array_keys( $value, null, true ) as $nullKey ) {
2040 $includeNull = true;
2041 unset( $value[$nullKey] );
2042 }
2043 if ( count( $value ) == 0 && !$includeNull ) {
2044 throw new InvalidArgumentException(
2045 __METHOD__ . ": empty input for field $field" );
2046 } elseif ( count( $value ) == 0 ) {
2047 // only check if $field is null
2048 $list .= "$field IS NULL";
2049 } else {
2050 // IN clause contains at least one valid element
2051 if ( $includeNull ) {
2052 // Group subconditions to ensure correct precedence
2053 $list .= '(';
2054 }
2055 if ( count( $value ) == 1 ) {
2056 // Special-case single values, as IN isn't terribly efficient
2057 // Don't necessarily assume the single key is 0; we don't
2058 // enforce linear numeric ordering on other arrays here.
2059 $value = array_values( $value )[0];
2060 $list .= $field . " = " . $this->addQuotes( $value );
2061 } else {
2062 $list .= $field . " IN (" . $this->makeList( $value ) . ") ";
2063 }
2064 // if null present in array, append IS NULL
2065 if ( $includeNull ) {
2066 $list .= " OR $field IS NULL)";
2067 }
2068 }
2069 } elseif ( $value === null ) {
2070 if ( $mode == self::LIST_AND || $mode == self::LIST_OR ) {
2071 $list .= "$field IS ";
2072 } elseif ( $mode == self::LIST_SET ) {
2073 $list .= "$field = ";
2074 }
2075 $list .= 'NULL';
2076 } else {
2077 if (
2078 $mode == self::LIST_AND || $mode == self::LIST_OR || $mode == self::LIST_SET
2079 ) {
2080 $list .= "$field = ";
2081 }
2082 $list .= $mode == self::LIST_NAMES ? $value : $this->addQuotes( $value );
2083 }
2084 }
2085
2086 return $list;
2087 }
2088
2089 public function makeWhereFrom2d( $data, $baseKey, $subKey ) {
2090 $conds = [];
2091
2092 foreach ( $data as $base => $sub ) {
2093 if ( count( $sub ) ) {
2094 $conds[] = $this->makeList(
2095 [ $baseKey => $base, $subKey => array_keys( $sub ) ],
2096 self::LIST_AND );
2097 }
2098 }
2099
2100 if ( $conds ) {
2101 return $this->makeList( $conds, self::LIST_OR );
2102 } else {
2103 // Nothing to search for...
2104 return false;
2105 }
2106 }
2107
2108 public function aggregateValue( $valuedata, $valuename = 'value' ) {
2109 return $valuename;
2110 }
2111
2112 public function bitNot( $field ) {
2113 return "(~$field)";
2114 }
2115
2116 public function bitAnd( $fieldLeft, $fieldRight ) {
2117 return "($fieldLeft & $fieldRight)";
2118 }
2119
2120 public function bitOr( $fieldLeft, $fieldRight ) {
2121 return "($fieldLeft | $fieldRight)";
2122 }
2123
2124 public function buildConcat( $stringList ) {
2125 return 'CONCAT(' . implode( ',', $stringList ) . ')';
2126 }
2127
2128 public function buildGroupConcatField(
2129 $delim, $table, $field, $conds = '', $join_conds = []
2130 ) {
2131 $fld = "GROUP_CONCAT($field SEPARATOR " . $this->addQuotes( $delim ) . ')';
2132
2133 return '(' . $this->selectSQLText( $table, $fld, $conds, null, [], $join_conds ) . ')';
2134 }
2135
2136 public function buildSubstring( $input, $startPosition, $length = null ) {
2137 $this->assertBuildSubstringParams( $startPosition, $length );
2138 $functionBody = "$input FROM $startPosition";
2139 if ( $length !== null ) {
2140 $functionBody .= " FOR $length";
2141 }
2142 return 'SUBSTRING(' . $functionBody . ')';
2143 }
2144
2145 /**
2146 * Check type and bounds for parameters to self::buildSubstring()
2147 *
2148 * All supported databases have substring functions that behave the same for
2149 * positive $startPosition and non-negative $length, but behaviors differ when
2150 * given 0 or negative $startPosition or negative $length. The simplest
2151 * solution to that is to just forbid those values.
2152 *
2153 * @param int $startPosition
2154 * @param int|null $length
2155 * @since 1.31
2156 */
2157 protected function assertBuildSubstringParams( $startPosition, $length ) {
2158 if ( !is_int( $startPosition ) || $startPosition <= 0 ) {
2159 throw new InvalidArgumentException(
2160 '$startPosition must be a positive integer'
2161 );
2162 }
2163 if ( !( is_int( $length ) && $length >= 0 || $length === null ) ) {
2164 throw new InvalidArgumentException(
2165 '$length must be null or an integer greater than or equal to 0'
2166 );
2167 }
2168 }
2169
2170 public function buildStringCast( $field ) {
2171 return $field;
2172 }
2173
2174 public function buildIntegerCast( $field ) {
2175 return 'CAST( ' . $field . ' AS INTEGER )';
2176 }
2177
2178 public function buildSelectSubquery(
2179 $table, $vars, $conds = '', $fname = __METHOD__,
2180 $options = [], $join_conds = []
2181 ) {
2182 return new Subquery(
2183 $this->selectSQLText( $table, $vars, $conds, $fname, $options, $join_conds )
2184 );
2185 }
2186
2187 public function databasesAreIndependent() {
2188 return false;
2189 }
2190
2191 public function selectDB( $db ) {
2192 # Stub. Shouldn't cause serious problems if it's not overridden, but
2193 # if your database engine supports a concept similar to MySQL's
2194 # databases you may as well.
2195 $this->dbName = $db;
2196
2197 return true;
2198 }
2199
2200 public function getDBname() {
2201 return $this->dbName;
2202 }
2203
2204 public function getServer() {
2205 return $this->server;
2206 }
2207
2208 public function tableName( $name, $format = 'quoted' ) {
2209 if ( $name instanceof Subquery ) {
2210 throw new DBUnexpectedError(
2211 $this,
2212 __METHOD__ . ': got Subquery instance when expecting a string.'
2213 );
2214 }
2215
2216 # Skip the entire process when we have a string quoted on both ends.
2217 # Note that we check the end so that we will still quote any use of
2218 # use of `database`.table. But won't break things if someone wants
2219 # to query a database table with a dot in the name.
2220 if ( $this->isQuotedIdentifier( $name ) ) {
2221 return $name;
2222 }
2223
2224 # Lets test for any bits of text that should never show up in a table
2225 # name. Basically anything like JOIN or ON which are actually part of
2226 # SQL queries, but may end up inside of the table value to combine
2227 # sql. Such as how the API is doing.
2228 # Note that we use a whitespace test rather than a \b test to avoid
2229 # any remote case where a word like on may be inside of a table name
2230 # surrounded by symbols which may be considered word breaks.
2231 if ( preg_match( '/(^|\s)(DISTINCT|JOIN|ON|AS)(\s|$)/i', $name ) !== 0 ) {
2232 $this->queryLogger->warning(
2233 __METHOD__ . ": use of subqueries is not supported this way.",
2234 [ 'trace' => ( new RuntimeException() )->getTraceAsString() ]
2235 );
2236
2237 return $name;
2238 }
2239
2240 # Split database and table into proper variables.
2241 list( $database, $schema, $prefix, $table ) = $this->qualifiedTableComponents( $name );
2242
2243 # Quote $table and apply the prefix if not quoted.
2244 # $tableName might be empty if this is called from Database::replaceVars()
2245 $tableName = "{$prefix}{$table}";
2246 if ( $format === 'quoted'
2247 && !$this->isQuotedIdentifier( $tableName )
2248 && $tableName !== ''
2249 ) {
2250 $tableName = $this->addIdentifierQuotes( $tableName );
2251 }
2252
2253 # Quote $schema and $database and merge them with the table name if needed
2254 $tableName = $this->prependDatabaseOrSchema( $schema, $tableName, $format );
2255 $tableName = $this->prependDatabaseOrSchema( $database, $tableName, $format );
2256
2257 return $tableName;
2258 }
2259
2260 /**
2261 * Get the table components needed for a query given the currently selected database
2262 *
2263 * @param string $name Table name in the form of db.schema.table, db.table, or table
2264 * @return array (DB name or "" for default, schema name, table prefix, table name)
2265 */
2266 protected function qualifiedTableComponents( $name ) {
2267 # We reverse the explode so that database.table and table both output the correct table.
2268 $dbDetails = explode( '.', $name, 3 );
2269 if ( count( $dbDetails ) == 3 ) {
2270 list( $database, $schema, $table ) = $dbDetails;
2271 # We don't want any prefix added in this case
2272 $prefix = '';
2273 } elseif ( count( $dbDetails ) == 2 ) {
2274 list( $database, $table ) = $dbDetails;
2275 # We don't want any prefix added in this case
2276 $prefix = '';
2277 # In dbs that support it, $database may actually be the schema
2278 # but that doesn't affect any of the functionality here
2279 $schema = '';
2280 } else {
2281 list( $table ) = $dbDetails;
2282 if ( isset( $this->tableAliases[$table] ) ) {
2283 $database = $this->tableAliases[$table]['dbname'];
2284 $schema = is_string( $this->tableAliases[$table]['schema'] )
2285 ? $this->tableAliases[$table]['schema']
2286 : $this->schema;
2287 $prefix = is_string( $this->tableAliases[$table]['prefix'] )
2288 ? $this->tableAliases[$table]['prefix']
2289 : $this->tablePrefix;
2290 } else {
2291 $database = '';
2292 $schema = $this->schema; # Default schema
2293 $prefix = $this->tablePrefix; # Default prefix
2294 }
2295 }
2296
2297 return [ $database, $schema, $prefix, $table ];
2298 }
2299
2300 /**
2301 * @param string|null $namespace Database or schema
2302 * @param string $relation Name of table, view, sequence, etc...
2303 * @param string $format One of (raw, quoted)
2304 * @return string Relation name with quoted and merged $namespace as needed
2305 */
2306 private function prependDatabaseOrSchema( $namespace, $relation, $format ) {
2307 if ( strlen( $namespace ) ) {
2308 if ( $format === 'quoted' && !$this->isQuotedIdentifier( $namespace ) ) {
2309 $namespace = $this->addIdentifierQuotes( $namespace );
2310 }
2311 $relation = $namespace . '.' . $relation;
2312 }
2313
2314 return $relation;
2315 }
2316
2317 public function tableNames() {
2318 $inArray = func_get_args();
2319 $retVal = [];
2320
2321 foreach ( $inArray as $name ) {
2322 $retVal[$name] = $this->tableName( $name );
2323 }
2324
2325 return $retVal;
2326 }
2327
2328 public function tableNamesN() {
2329 $inArray = func_get_args();
2330 $retVal = [];
2331
2332 foreach ( $inArray as $name ) {
2333 $retVal[] = $this->tableName( $name );
2334 }
2335
2336 return $retVal;
2337 }
2338
2339 /**
2340 * Get an aliased table name
2341 *
2342 * This returns strings like "tableName AS newTableName" for aliased tables
2343 * and "(SELECT * from tableA) newTablename" for subqueries (e.g. derived tables)
2344 *
2345 * @see Database::tableName()
2346 * @param string|Subquery $table Table name or object with a 'sql' field
2347 * @param string|bool $alias Table alias (optional)
2348 * @return string SQL name for aliased table. Will not alias a table to its own name
2349 */
2350 protected function tableNameWithAlias( $table, $alias = false ) {
2351 if ( is_string( $table ) ) {
2352 $quotedTable = $this->tableName( $table );
2353 } elseif ( $table instanceof Subquery ) {
2354 $quotedTable = (string)$table;
2355 } else {
2356 throw new InvalidArgumentException( "Table must be a string or Subquery." );
2357 }
2358
2359 if ( !strlen( $alias ) || $alias === $table ) {
2360 if ( $table instanceof Subquery ) {
2361 throw new InvalidArgumentException( "Subquery table missing alias." );
2362 }
2363
2364 return $quotedTable;
2365 } else {
2366 return $quotedTable . ' ' . $this->addIdentifierQuotes( $alias );
2367 }
2368 }
2369
2370 /**
2371 * Gets an array of aliased table names
2372 *
2373 * @param array $tables [ [alias] => table ]
2374 * @return string[] See tableNameWithAlias()
2375 */
2376 protected function tableNamesWithAlias( $tables ) {
2377 $retval = [];
2378 foreach ( $tables as $alias => $table ) {
2379 if ( is_numeric( $alias ) ) {
2380 $alias = $table;
2381 }
2382 $retval[] = $this->tableNameWithAlias( $table, $alias );
2383 }
2384
2385 return $retval;
2386 }
2387
2388 /**
2389 * Get an aliased field name
2390 * e.g. fieldName AS newFieldName
2391 *
2392 * @param string $name Field name
2393 * @param string|bool $alias Alias (optional)
2394 * @return string SQL name for aliased field. Will not alias a field to its own name
2395 */
2396 protected function fieldNameWithAlias( $name, $alias = false ) {
2397 if ( !$alias || (string)$alias === (string)$name ) {
2398 return $name;
2399 } else {
2400 return $name . ' AS ' . $this->addIdentifierQuotes( $alias ); // PostgreSQL needs AS
2401 }
2402 }
2403
2404 /**
2405 * Gets an array of aliased field names
2406 *
2407 * @param array $fields [ [alias] => field ]
2408 * @return string[] See fieldNameWithAlias()
2409 */
2410 protected function fieldNamesWithAlias( $fields ) {
2411 $retval = [];
2412 foreach ( $fields as $alias => $field ) {
2413 if ( is_numeric( $alias ) ) {
2414 $alias = $field;
2415 }
2416 $retval[] = $this->fieldNameWithAlias( $field, $alias );
2417 }
2418
2419 return $retval;
2420 }
2421
2422 /**
2423 * Get the aliased table name clause for a FROM clause
2424 * which might have a JOIN and/or USE INDEX or IGNORE INDEX clause
2425 *
2426 * @param array $tables ( [alias] => table )
2427 * @param array $use_index Same as for select()
2428 * @param array $ignore_index Same as for select()
2429 * @param array $join_conds Same as for select()
2430 * @return string
2431 */
2432 protected function tableNamesWithIndexClauseOrJOIN(
2433 $tables, $use_index = [], $ignore_index = [], $join_conds = []
2434 ) {
2435 $ret = [];
2436 $retJOIN = [];
2437 $use_index = (array)$use_index;
2438 $ignore_index = (array)$ignore_index;
2439 $join_conds = (array)$join_conds;
2440
2441 foreach ( $tables as $alias => $table ) {
2442 if ( !is_string( $alias ) ) {
2443 // No alias? Set it equal to the table name
2444 $alias = $table;
2445 }
2446
2447 if ( is_array( $table ) ) {
2448 // A parenthesized group
2449 if ( count( $table ) > 1 ) {
2450 $joinedTable = '(' .
2451 $this->tableNamesWithIndexClauseOrJOIN(
2452 $table, $use_index, $ignore_index, $join_conds ) . ')';
2453 } else {
2454 // Degenerate case
2455 $innerTable = reset( $table );
2456 $innerAlias = key( $table );
2457 $joinedTable = $this->tableNameWithAlias(
2458 $innerTable,
2459 is_string( $innerAlias ) ? $innerAlias : $innerTable
2460 );
2461 }
2462 } else {
2463 $joinedTable = $this->tableNameWithAlias( $table, $alias );
2464 }
2465
2466 // Is there a JOIN clause for this table?
2467 if ( isset( $join_conds[$alias] ) ) {
2468 list( $joinType, $conds ) = $join_conds[$alias];
2469 $tableClause = $joinType;
2470 $tableClause .= ' ' . $joinedTable;
2471 if ( isset( $use_index[$alias] ) ) { // has USE INDEX?
2472 $use = $this->useIndexClause( implode( ',', (array)$use_index[$alias] ) );
2473 if ( $use != '' ) {
2474 $tableClause .= ' ' . $use;
2475 }
2476 }
2477 if ( isset( $ignore_index[$alias] ) ) { // has IGNORE INDEX?
2478 $ignore = $this->ignoreIndexClause(
2479 implode( ',', (array)$ignore_index[$alias] ) );
2480 if ( $ignore != '' ) {
2481 $tableClause .= ' ' . $ignore;
2482 }
2483 }
2484 $on = $this->makeList( (array)$conds, self::LIST_AND );
2485 if ( $on != '' ) {
2486 $tableClause .= ' ON (' . $on . ')';
2487 }
2488
2489 $retJOIN[] = $tableClause;
2490 } elseif ( isset( $use_index[$alias] ) ) {
2491 // Is there an INDEX clause for this table?
2492 $tableClause = $joinedTable;
2493 $tableClause .= ' ' . $this->useIndexClause(
2494 implode( ',', (array)$use_index[$alias] )
2495 );
2496
2497 $ret[] = $tableClause;
2498 } elseif ( isset( $ignore_index[$alias] ) ) {
2499 // Is there an INDEX clause for this table?
2500 $tableClause = $joinedTable;
2501 $tableClause .= ' ' . $this->ignoreIndexClause(
2502 implode( ',', (array)$ignore_index[$alias] )
2503 );
2504
2505 $ret[] = $tableClause;
2506 } else {
2507 $tableClause = $joinedTable;
2508
2509 $ret[] = $tableClause;
2510 }
2511 }
2512
2513 // We can't separate explicit JOIN clauses with ',', use ' ' for those
2514 $implicitJoins = $ret ? implode( ',', $ret ) : "";
2515 $explicitJoins = $retJOIN ? implode( ' ', $retJOIN ) : "";
2516
2517 // Compile our final table clause
2518 return implode( ' ', [ $implicitJoins, $explicitJoins ] );
2519 }
2520
2521 /**
2522 * Allows for index remapping in queries where this is not consistent across DBMS
2523 *
2524 * @param string $index
2525 * @return string
2526 */
2527 protected function indexName( $index ) {
2528 return isset( $this->indexAliases[$index] )
2529 ? $this->indexAliases[$index]
2530 : $index;
2531 }
2532
2533 public function addQuotes( $s ) {
2534 if ( $s instanceof Blob ) {
2535 $s = $s->fetch();
2536 }
2537 if ( $s === null ) {
2538 return 'NULL';
2539 } elseif ( is_bool( $s ) ) {
2540 return (int)$s;
2541 } else {
2542 # This will also quote numeric values. This should be harmless,
2543 # and protects against weird problems that occur when they really
2544 # _are_ strings such as article titles and string->number->string
2545 # conversion is not 1:1.
2546 return "'" . $this->strencode( $s ) . "'";
2547 }
2548 }
2549
2550 /**
2551 * Quotes an identifier using `backticks` or "double quotes" depending on the database type.
2552 * MySQL uses `backticks` while basically everything else uses double quotes.
2553 * Since MySQL is the odd one out here the double quotes are our generic
2554 * and we implement backticks in DatabaseMysqlBase.
2555 *
2556 * @param string $s
2557 * @return string
2558 */
2559 public function addIdentifierQuotes( $s ) {
2560 return '"' . str_replace( '"', '""', $s ) . '"';
2561 }
2562
2563 /**
2564 * Returns if the given identifier looks quoted or not according to
2565 * the database convention for quoting identifiers .
2566 *
2567 * @note Do not use this to determine if untrusted input is safe.
2568 * A malicious user can trick this function.
2569 * @param string $name
2570 * @return bool
2571 */
2572 public function isQuotedIdentifier( $name ) {
2573 return $name[0] == '"' && substr( $name, -1, 1 ) == '"';
2574 }
2575
2576 /**
2577 * @param string $s
2578 * @param string $escapeChar
2579 * @return string
2580 */
2581 protected function escapeLikeInternal( $s, $escapeChar = '`' ) {
2582 return str_replace( [ $escapeChar, '%', '_' ],
2583 [ "{$escapeChar}{$escapeChar}", "{$escapeChar}%", "{$escapeChar}_" ],
2584 $s );
2585 }
2586
2587 public function buildLike() {
2588 $params = func_get_args();
2589
2590 if ( count( $params ) > 0 && is_array( $params[0] ) ) {
2591 $params = $params[0];
2592 }
2593
2594 $s = '';
2595
2596 // We use ` instead of \ as the default LIKE escape character, since addQuotes()
2597 // may escape backslashes, creating problems of double escaping. The `
2598 // character has good cross-DBMS compatibility, avoiding special operators
2599 // in MS SQL like ^ and %
2600 $escapeChar = '`';
2601
2602 foreach ( $params as $value ) {
2603 if ( $value instanceof LikeMatch ) {
2604 $s .= $value->toString();
2605 } else {
2606 $s .= $this->escapeLikeInternal( $value, $escapeChar );
2607 }
2608 }
2609
2610 return ' LIKE ' .
2611 $this->addQuotes( $s ) . ' ESCAPE ' . $this->addQuotes( $escapeChar ) . ' ';
2612 }
2613
2614 public function anyChar() {
2615 return new LikeMatch( '_' );
2616 }
2617
2618 public function anyString() {
2619 return new LikeMatch( '%' );
2620 }
2621
2622 public function nextSequenceValue( $seqName ) {
2623 return null;
2624 }
2625
2626 /**
2627 * USE INDEX clause. Unlikely to be useful for anything but MySQL. This
2628 * is only needed because a) MySQL must be as efficient as possible due to
2629 * its use on Wikipedia, and b) MySQL 4.0 is kind of dumb sometimes about
2630 * which index to pick. Anyway, other databases might have different
2631 * indexes on a given table. So don't bother overriding this unless you're
2632 * MySQL.
2633 * @param string $index
2634 * @return string
2635 */
2636 public function useIndexClause( $index ) {
2637 return '';
2638 }
2639
2640 /**
2641 * IGNORE INDEX clause. Unlikely to be useful for anything but MySQL. This
2642 * is only needed because a) MySQL must be as efficient as possible due to
2643 * its use on Wikipedia, and b) MySQL 4.0 is kind of dumb sometimes about
2644 * which index to pick. Anyway, other databases might have different
2645 * indexes on a given table. So don't bother overriding this unless you're
2646 * MySQL.
2647 * @param string $index
2648 * @return string
2649 */
2650 public function ignoreIndexClause( $index ) {
2651 return '';
2652 }
2653
2654 public function replace( $table, $uniqueIndexes, $rows, $fname = __METHOD__ ) {
2655 if ( count( $rows ) == 0 ) {
2656 return;
2657 }
2658
2659 // Single row case
2660 if ( !is_array( reset( $rows ) ) ) {
2661 $rows = [ $rows ];
2662 }
2663
2664 try {
2665 $this->startAtomic( $fname, self::ATOMIC_CANCELABLE );
2666 $affectedRowCount = 0;
2667 foreach ( $rows as $row ) {
2668 // Delete rows which collide with this one
2669 $indexWhereClauses = [];
2670 foreach ( $uniqueIndexes as $index ) {
2671 $indexColumns = (array)$index;
2672 $indexRowValues = array_intersect_key( $row, array_flip( $indexColumns ) );
2673 if ( count( $indexRowValues ) != count( $indexColumns ) ) {
2674 throw new DBUnexpectedError(
2675 $this,
2676 'New record does not provide all values for unique key (' .
2677 implode( ', ', $indexColumns ) . ')'
2678 );
2679 } elseif ( in_array( null, $indexRowValues, true ) ) {
2680 throw new DBUnexpectedError(
2681 $this,
2682 'New record has a null value for unique key (' .
2683 implode( ', ', $indexColumns ) . ')'
2684 );
2685 }
2686 $indexWhereClauses[] = $this->makeList( $indexRowValues, LIST_AND );
2687 }
2688
2689 if ( $indexWhereClauses ) {
2690 $this->delete( $table, $this->makeList( $indexWhereClauses, LIST_OR ), $fname );
2691 $affectedRowCount += $this->affectedRows();
2692 }
2693
2694 // Now insert the row
2695 $this->insert( $table, $row, $fname );
2696 $affectedRowCount += $this->affectedRows();
2697 }
2698 $this->endAtomic( $fname );
2699 $this->affectedRowCount = $affectedRowCount;
2700 } catch ( Exception $e ) {
2701 $this->cancelAtomic( $fname );
2702 throw $e;
2703 }
2704 }
2705
2706 /**
2707 * REPLACE query wrapper for MySQL and SQLite, which have a native REPLACE
2708 * statement.
2709 *
2710 * @param string $table Table name
2711 * @param array|string $rows Row(s) to insert
2712 * @param string $fname Caller function name
2713 *
2714 * @return ResultWrapper
2715 */
2716 protected function nativeReplace( $table, $rows, $fname ) {
2717 $table = $this->tableName( $table );
2718
2719 # Single row case
2720 if ( !is_array( reset( $rows ) ) ) {
2721 $rows = [ $rows ];
2722 }
2723
2724 $sql = "REPLACE INTO $table (" . implode( ',', array_keys( $rows[0] ) ) . ') VALUES ';
2725 $first = true;
2726
2727 foreach ( $rows as $row ) {
2728 if ( $first ) {
2729 $first = false;
2730 } else {
2731 $sql .= ',';
2732 }
2733
2734 $sql .= '(' . $this->makeList( $row ) . ')';
2735 }
2736
2737 return $this->query( $sql, $fname );
2738 }
2739
2740 public function upsert( $table, array $rows, array $uniqueIndexes, array $set,
2741 $fname = __METHOD__
2742 ) {
2743 if ( !count( $rows ) ) {
2744 return true; // nothing to do
2745 }
2746
2747 if ( !is_array( reset( $rows ) ) ) {
2748 $rows = [ $rows ];
2749 }
2750
2751 if ( count( $uniqueIndexes ) ) {
2752 $clauses = []; // list WHERE clauses that each identify a single row
2753 foreach ( $rows as $row ) {
2754 foreach ( $uniqueIndexes as $index ) {
2755 $index = is_array( $index ) ? $index : [ $index ]; // columns
2756 $rowKey = []; // unique key to this row
2757 foreach ( $index as $column ) {
2758 $rowKey[$column] = $row[$column];
2759 }
2760 $clauses[] = $this->makeList( $rowKey, self::LIST_AND );
2761 }
2762 }
2763 $where = [ $this->makeList( $clauses, self::LIST_OR ) ];
2764 } else {
2765 $where = false;
2766 }
2767
2768 $affectedRowCount = 0;
2769 try {
2770 $this->startAtomic( $fname, self::ATOMIC_CANCELABLE );
2771 # Update any existing conflicting row(s)
2772 if ( $where !== false ) {
2773 $ok = $this->update( $table, $set, $where, $fname );
2774 $affectedRowCount += $this->affectedRows();
2775 } else {
2776 $ok = true;
2777 }
2778 # Now insert any non-conflicting row(s)
2779 $ok = $this->insert( $table, $rows, $fname, [ 'IGNORE' ] ) && $ok;
2780 $affectedRowCount += $this->affectedRows();
2781 $this->endAtomic( $fname );
2782 $this->affectedRowCount = $affectedRowCount;
2783 } catch ( Exception $e ) {
2784 $this->cancelAtomic( $fname );
2785 throw $e;
2786 }
2787
2788 return $ok;
2789 }
2790
2791 public function deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds,
2792 $fname = __METHOD__
2793 ) {
2794 if ( !$conds ) {
2795 throw new DBUnexpectedError( $this, __METHOD__ . ' called with empty $conds' );
2796 }
2797
2798 $delTable = $this->tableName( $delTable );
2799 $joinTable = $this->tableName( $joinTable );
2800 $sql = "DELETE FROM $delTable WHERE $delVar IN (SELECT $joinVar FROM $joinTable ";
2801 if ( $conds != '*' ) {
2802 $sql .= 'WHERE ' . $this->makeList( $conds, self::LIST_AND );
2803 }
2804 $sql .= ')';
2805
2806 $this->query( $sql, $fname );
2807 }
2808
2809 public function textFieldSize( $table, $field ) {
2810 $table = $this->tableName( $table );
2811 $sql = "SHOW COLUMNS FROM $table LIKE \"$field\";";
2812 $res = $this->query( $sql, __METHOD__ );
2813 $row = $this->fetchObject( $res );
2814
2815 $m = [];
2816
2817 if ( preg_match( '/\((.*)\)/', $row->Type, $m ) ) {
2818 $size = $m[1];
2819 } else {
2820 $size = -1;
2821 }
2822
2823 return $size;
2824 }
2825
2826 public function delete( $table, $conds, $fname = __METHOD__ ) {
2827 if ( !$conds ) {
2828 throw new DBUnexpectedError( $this, __METHOD__ . ' called with no conditions' );
2829 }
2830
2831 $table = $this->tableName( $table );
2832 $sql = "DELETE FROM $table";
2833
2834 if ( $conds != '*' ) {
2835 if ( is_array( $conds ) ) {
2836 $conds = $this->makeList( $conds, self::LIST_AND );
2837 }
2838 $sql .= ' WHERE ' . $conds;
2839 }
2840
2841 return $this->query( $sql, $fname );
2842 }
2843
2844 final public function insertSelect(
2845 $destTable, $srcTable, $varMap, $conds,
2846 $fname = __METHOD__, $insertOptions = [], $selectOptions = [], $selectJoinConds = []
2847 ) {
2848 static $hints = [ 'NO_AUTO_COLUMNS' ];
2849
2850 $insertOptions = (array)$insertOptions;
2851 $selectOptions = (array)$selectOptions;
2852
2853 if ( $this->cliMode && $this->isInsertSelectSafe( $insertOptions, $selectOptions ) ) {
2854 // For massive migrations with downtime, we don't want to select everything
2855 // into memory and OOM, so do all this native on the server side if possible.
2856 return $this->nativeInsertSelect(
2857 $destTable,
2858 $srcTable,
2859 $varMap,
2860 $conds,
2861 $fname,
2862 array_diff( $insertOptions, $hints ),
2863 $selectOptions,
2864 $selectJoinConds
2865 );
2866 }
2867
2868 return $this->nonNativeInsertSelect(
2869 $destTable,
2870 $srcTable,
2871 $varMap,
2872 $conds,
2873 $fname,
2874 array_diff( $insertOptions, $hints ),
2875 $selectOptions,
2876 $selectJoinConds
2877 );
2878 }
2879
2880 /**
2881 * @param array $insertOptions INSERT options
2882 * @param array $selectOptions SELECT options
2883 * @return bool Whether an INSERT SELECT with these options will be replication safe
2884 * @since 1.31
2885 */
2886 protected function isInsertSelectSafe( array $insertOptions, array $selectOptions ) {
2887 return true;
2888 }
2889
2890 /**
2891 * Implementation of insertSelect() based on select() and insert()
2892 *
2893 * @see IDatabase::insertSelect()
2894 * @since 1.30
2895 * @param string $destTable
2896 * @param string|array $srcTable
2897 * @param array $varMap
2898 * @param array $conds
2899 * @param string $fname
2900 * @param array $insertOptions
2901 * @param array $selectOptions
2902 * @param array $selectJoinConds
2903 * @return bool
2904 */
2905 protected function nonNativeInsertSelect( $destTable, $srcTable, $varMap, $conds,
2906 $fname = __METHOD__,
2907 $insertOptions = [], $selectOptions = [], $selectJoinConds = []
2908 ) {
2909 // For web requests, do a locking SELECT and then INSERT. This puts the SELECT burden
2910 // on only the master (without needing row-based-replication). It also makes it easy to
2911 // know how big the INSERT is going to be.
2912 $fields = [];
2913 foreach ( $varMap as $dstColumn => $sourceColumnOrSql ) {
2914 $fields[] = $this->fieldNameWithAlias( $sourceColumnOrSql, $dstColumn );
2915 }
2916 $selectOptions[] = 'FOR UPDATE';
2917 $res = $this->select(
2918 $srcTable, implode( ',', $fields ), $conds, $fname, $selectOptions, $selectJoinConds
2919 );
2920 if ( !$res ) {
2921 return false;
2922 }
2923
2924 try {
2925 $affectedRowCount = 0;
2926 $this->startAtomic( $fname, self::ATOMIC_CANCELABLE );
2927 $rows = [];
2928 $ok = true;
2929 foreach ( $res as $row ) {
2930 $rows[] = (array)$row;
2931
2932 // Avoid inserts that are too huge
2933 if ( count( $rows ) >= $this->nonNativeInsertSelectBatchSize ) {
2934 $ok = $this->insert( $destTable, $rows, $fname, $insertOptions );
2935 if ( !$ok ) {
2936 break;
2937 }
2938 $affectedRowCount += $this->affectedRows();
2939 $rows = [];
2940 }
2941 }
2942 if ( $rows && $ok ) {
2943 $ok = $this->insert( $destTable, $rows, $fname, $insertOptions );
2944 if ( $ok ) {
2945 $affectedRowCount += $this->affectedRows();
2946 }
2947 }
2948 if ( $ok ) {
2949 $this->endAtomic( $fname );
2950 $this->affectedRowCount = $affectedRowCount;
2951 } else {
2952 $this->cancelAtomic( $fname );
2953 }
2954 return $ok;
2955 } catch ( Exception $e ) {
2956 $this->cancelAtomic( $fname );
2957 throw $e;
2958 }
2959 }
2960
2961 /**
2962 * Native server-side implementation of insertSelect() for situations where
2963 * we don't want to select everything into memory
2964 *
2965 * @see IDatabase::insertSelect()
2966 * @param string $destTable
2967 * @param string|array $srcTable
2968 * @param array $varMap
2969 * @param array $conds
2970 * @param string $fname
2971 * @param array $insertOptions
2972 * @param array $selectOptions
2973 * @param array $selectJoinConds
2974 * @return bool
2975 */
2976 protected function nativeInsertSelect( $destTable, $srcTable, $varMap, $conds,
2977 $fname = __METHOD__,
2978 $insertOptions = [], $selectOptions = [], $selectJoinConds = []
2979 ) {
2980 $destTable = $this->tableName( $destTable );
2981
2982 if ( !is_array( $insertOptions ) ) {
2983 $insertOptions = [ $insertOptions ];
2984 }
2985
2986 $insertOptions = $this->makeInsertOptions( $insertOptions );
2987
2988 $selectSql = $this->selectSQLText(
2989 $srcTable,
2990 array_values( $varMap ),
2991 $conds,
2992 $fname,
2993 $selectOptions,
2994 $selectJoinConds
2995 );
2996
2997 $sql = "INSERT $insertOptions" .
2998 " INTO $destTable (" . implode( ',', array_keys( $varMap ) ) . ') ' .
2999 $selectSql;
3000
3001 return $this->query( $sql, $fname );
3002 }
3003
3004 /**
3005 * Construct a LIMIT query with optional offset. This is used for query
3006 * pages. The SQL should be adjusted so that only the first $limit rows
3007 * are returned. If $offset is provided as well, then the first $offset
3008 * rows should be discarded, and the next $limit rows should be returned.
3009 * If the result of the query is not ordered, then the rows to be returned
3010 * are theoretically arbitrary.
3011 *
3012 * $sql is expected to be a SELECT, if that makes a difference.
3013 *
3014 * The version provided by default works in MySQL and SQLite. It will very
3015 * likely need to be overridden for most other DBMSes.
3016 *
3017 * @param string $sql SQL query we will append the limit too
3018 * @param int $limit The SQL limit
3019 * @param int|bool $offset The SQL offset (default false)
3020 * @throws DBUnexpectedError
3021 * @return string
3022 */
3023 public function limitResult( $sql, $limit, $offset = false ) {
3024 if ( !is_numeric( $limit ) ) {
3025 throw new DBUnexpectedError( $this,
3026 "Invalid non-numeric limit passed to limitResult()\n" );
3027 }
3028
3029 return "$sql LIMIT "
3030 . ( ( is_numeric( $offset ) && $offset != 0 ) ? "{$offset}," : "" )
3031 . "{$limit} ";
3032 }
3033
3034 public function unionSupportsOrderAndLimit() {
3035 return true; // True for almost every DB supported
3036 }
3037
3038 public function unionQueries( $sqls, $all ) {
3039 $glue = $all ? ') UNION ALL (' : ') UNION (';
3040
3041 return '(' . implode( $glue, $sqls ) . ')';
3042 }
3043
3044 public function unionConditionPermutations(
3045 $table, $vars, array $permute_conds, $extra_conds = '', $fname = __METHOD__,
3046 $options = [], $join_conds = []
3047 ) {
3048 // First, build the Cartesian product of $permute_conds
3049 $conds = [ [] ];
3050 foreach ( $permute_conds as $field => $values ) {
3051 if ( !$values ) {
3052 // Skip empty $values
3053 continue;
3054 }
3055 $values = array_unique( $values ); // For sanity
3056 $newConds = [];
3057 foreach ( $conds as $cond ) {
3058 foreach ( $values as $value ) {
3059 $cond[$field] = $value;
3060 $newConds[] = $cond; // Arrays are by-value, not by-reference, so this works
3061 }
3062 }
3063 $conds = $newConds;
3064 }
3065
3066 $extra_conds = $extra_conds === '' ? [] : (array)$extra_conds;
3067
3068 // If there's just one condition and no subordering, hand off to
3069 // selectSQLText directly.
3070 if ( count( $conds ) === 1 &&
3071 ( !isset( $options['INNER ORDER BY'] ) || !$this->unionSupportsOrderAndLimit() )
3072 ) {
3073 return $this->selectSQLText(
3074 $table, $vars, $conds[0] + $extra_conds, $fname, $options, $join_conds
3075 );
3076 }
3077
3078 // Otherwise, we need to pull out the order and limit to apply after
3079 // the union. Then build the SQL queries for each set of conditions in
3080 // $conds. Then union them together (using UNION ALL, because the
3081 // product *should* already be distinct).
3082 $orderBy = $this->makeOrderBy( $options );
3083 $limit = isset( $options['LIMIT'] ) ? $options['LIMIT'] : null;
3084 $offset = isset( $options['OFFSET'] ) ? $options['OFFSET'] : false;
3085 $all = empty( $options['NOTALL'] ) && !in_array( 'NOTALL', $options );
3086 if ( !$this->unionSupportsOrderAndLimit() ) {
3087 unset( $options['ORDER BY'], $options['LIMIT'], $options['OFFSET'] );
3088 } else {
3089 if ( array_key_exists( 'INNER ORDER BY', $options ) ) {
3090 $options['ORDER BY'] = $options['INNER ORDER BY'];
3091 }
3092 if ( $limit !== null && is_numeric( $offset ) && $offset != 0 ) {
3093 // We need to increase the limit by the offset rather than
3094 // using the offset directly, otherwise it'll skip incorrectly
3095 // in the subqueries.
3096 $options['LIMIT'] = $limit + $offset;
3097 unset( $options['OFFSET'] );
3098 }
3099 }
3100
3101 $sqls = [];
3102 foreach ( $conds as $cond ) {
3103 $sqls[] = $this->selectSQLText(
3104 $table, $vars, $cond + $extra_conds, $fname, $options, $join_conds
3105 );
3106 }
3107 $sql = $this->unionQueries( $sqls, $all ) . $orderBy;
3108 if ( $limit !== null ) {
3109 $sql = $this->limitResult( $sql, $limit, $offset );
3110 }
3111
3112 return $sql;
3113 }
3114
3115 public function conditional( $cond, $trueVal, $falseVal ) {
3116 if ( is_array( $cond ) ) {
3117 $cond = $this->makeList( $cond, self::LIST_AND );
3118 }
3119
3120 return " (CASE WHEN $cond THEN $trueVal ELSE $falseVal END) ";
3121 }
3122
3123 public function strreplace( $orig, $old, $new ) {
3124 return "REPLACE({$orig}, {$old}, {$new})";
3125 }
3126
3127 public function getServerUptime() {
3128 return 0;
3129 }
3130
3131 public function wasDeadlock() {
3132 return false;
3133 }
3134
3135 public function wasLockTimeout() {
3136 return false;
3137 }
3138
3139 public function wasConnectionLoss() {
3140 return $this->wasConnectionError( $this->lastErrno() );
3141 }
3142
3143 public function wasReadOnlyError() {
3144 return false;
3145 }
3146
3147 public function wasErrorReissuable() {
3148 return (
3149 $this->wasDeadlock() ||
3150 $this->wasLockTimeout() ||
3151 $this->wasConnectionLoss()
3152 );
3153 }
3154
3155 /**
3156 * Do not use this method outside of Database/DBError classes
3157 *
3158 * @param int|string $errno
3159 * @return bool Whether the given query error was a connection drop
3160 */
3161 public function wasConnectionError( $errno ) {
3162 return false;
3163 }
3164
3165 /**
3166 * @return bool Whether it is safe to assume the given error only caused statement rollback
3167 * @note This is for backwards compatibility for callers catching DBError exceptions in
3168 * order to ignore problems like duplicate key errors or foriegn key violations
3169 * @since 1.31
3170 */
3171 protected function wasKnownStatementRollbackError() {
3172 return false; // don't know; it could have caused a transaction rollback
3173 }
3174
3175 public function deadlockLoop() {
3176 $args = func_get_args();
3177 $function = array_shift( $args );
3178 $tries = self::DEADLOCK_TRIES;
3179
3180 $this->begin( __METHOD__ );
3181
3182 $retVal = null;
3183 /** @var Exception $e */
3184 $e = null;
3185 do {
3186 try {
3187 $retVal = call_user_func_array( $function, $args );
3188 break;
3189 } catch ( DBQueryError $e ) {
3190 if ( $this->wasDeadlock() ) {
3191 // Retry after a randomized delay
3192 usleep( mt_rand( self::DEADLOCK_DELAY_MIN, self::DEADLOCK_DELAY_MAX ) );
3193 } else {
3194 // Throw the error back up
3195 throw $e;
3196 }
3197 }
3198 } while ( --$tries > 0 );
3199
3200 if ( $tries <= 0 ) {
3201 // Too many deadlocks; give up
3202 $this->rollback( __METHOD__ );
3203 throw $e;
3204 } else {
3205 $this->commit( __METHOD__ );
3206
3207 return $retVal;
3208 }
3209 }
3210
3211 public function masterPosWait( DBMasterPos $pos, $timeout ) {
3212 # Real waits are implemented in the subclass.
3213 return 0;
3214 }
3215
3216 public function getReplicaPos() {
3217 # Stub
3218 return false;
3219 }
3220
3221 public function getMasterPos() {
3222 # Stub
3223 return false;
3224 }
3225
3226 public function serverIsReadOnly() {
3227 return false;
3228 }
3229
3230 final public function onTransactionResolution( callable $callback, $fname = __METHOD__ ) {
3231 if ( !$this->trxLevel ) {
3232 throw new DBUnexpectedError( $this, "No transaction is active." );
3233 }
3234 $this->trxEndCallbacks[] = [ $callback, $fname ];
3235 }
3236
3237 final public function onTransactionIdle( callable $callback, $fname = __METHOD__ ) {
3238 if ( !$this->trxLevel && $this->getTransactionRoundId() ) {
3239 // Start an implicit transaction similar to how query() does
3240 $this->begin( __METHOD__, self::TRANSACTION_INTERNAL );
3241 $this->trxAutomatic = true;
3242 }
3243
3244 $this->trxIdleCallbacks[] = [ $callback, $fname ];
3245 if ( !$this->trxLevel ) {
3246 $this->runOnTransactionIdleCallbacks( self::TRIGGER_IDLE );
3247 }
3248 }
3249
3250 final public function onTransactionPreCommitOrIdle( callable $callback, $fname = __METHOD__ ) {
3251 if ( !$this->trxLevel && $this->getTransactionRoundId() ) {
3252 // Start an implicit transaction similar to how query() does
3253 $this->begin( __METHOD__, self::TRANSACTION_INTERNAL );
3254 $this->trxAutomatic = true;
3255 }
3256
3257 if ( $this->trxLevel ) {
3258 $this->trxPreCommitCallbacks[] = [ $callback, $fname ];
3259 } else {
3260 // No transaction is active nor will start implicitly, so make one for this callback
3261 $this->startAtomic( __METHOD__, self::ATOMIC_CANCELABLE );
3262 try {
3263 call_user_func( $callback );
3264 $this->endAtomic( __METHOD__ );
3265 } catch ( Exception $e ) {
3266 $this->cancelAtomic( __METHOD__ );
3267 throw $e;
3268 }
3269 }
3270 }
3271
3272 final public function setTransactionListener( $name, callable $callback = null ) {
3273 if ( $callback ) {
3274 $this->trxRecurringCallbacks[$name] = $callback;
3275 } else {
3276 unset( $this->trxRecurringCallbacks[$name] );
3277 }
3278 }
3279
3280 /**
3281 * Whether to disable running of post-COMMIT/ROLLBACK callbacks
3282 *
3283 * This method should not be used outside of Database/LoadBalancer
3284 *
3285 * @param bool $suppress
3286 * @since 1.28
3287 */
3288 final public function setTrxEndCallbackSuppression( $suppress ) {
3289 $this->trxEndCallbacksSuppressed = $suppress;
3290 }
3291
3292 /**
3293 * Actually run and consume any "on transaction idle/resolution" callbacks.
3294 *
3295 * This method should not be used outside of Database/LoadBalancer
3296 *
3297 * @param int $trigger IDatabase::TRIGGER_* constant
3298 * @since 1.20
3299 * @throws Exception
3300 */
3301 public function runOnTransactionIdleCallbacks( $trigger ) {
3302 if ( $this->trxEndCallbacksSuppressed ) {
3303 return;
3304 }
3305
3306 $autoTrx = $this->getFlag( self::DBO_TRX ); // automatic begin() enabled?
3307 /** @var Exception $e */
3308 $e = null; // first exception
3309 do { // callbacks may add callbacks :)
3310 $callbacks = array_merge(
3311 $this->trxIdleCallbacks,
3312 $this->trxEndCallbacks // include "transaction resolution" callbacks
3313 );
3314 $this->trxIdleCallbacks = []; // consumed (and recursion guard)
3315 $this->trxEndCallbacks = []; // consumed (recursion guard)
3316 foreach ( $callbacks as $callback ) {
3317 try {
3318 list( $phpCallback ) = $callback;
3319 $this->clearFlag( self::DBO_TRX ); // make each query its own transaction
3320 call_user_func_array( $phpCallback, [ $trigger ] );
3321 if ( $autoTrx ) {
3322 $this->setFlag( self::DBO_TRX ); // restore automatic begin()
3323 } else {
3324 $this->clearFlag( self::DBO_TRX ); // restore auto-commit
3325 }
3326 } catch ( Exception $ex ) {
3327 call_user_func( $this->errorLogger, $ex );
3328 $e = $e ?: $ex;
3329 // Some callbacks may use startAtomic/endAtomic, so make sure
3330 // their transactions are ended so other callbacks don't fail
3331 if ( $this->trxLevel() ) {
3332 $this->rollback( __METHOD__, self::FLUSHING_INTERNAL );
3333 }
3334 }
3335 }
3336 } while ( count( $this->trxIdleCallbacks ) );
3337
3338 if ( $e instanceof Exception ) {
3339 throw $e; // re-throw any first exception
3340 }
3341 }
3342
3343 /**
3344 * Actually run and consume any "on transaction pre-commit" callbacks.
3345 *
3346 * This method should not be used outside of Database/LoadBalancer
3347 *
3348 * @since 1.22
3349 * @throws Exception
3350 */
3351 public function runOnTransactionPreCommitCallbacks() {
3352 $e = null; // first exception
3353 do { // callbacks may add callbacks :)
3354 $callbacks = $this->trxPreCommitCallbacks;
3355 $this->trxPreCommitCallbacks = []; // consumed (and recursion guard)
3356 foreach ( $callbacks as $callback ) {
3357 try {
3358 list( $phpCallback ) = $callback;
3359 call_user_func( $phpCallback );
3360 } catch ( Exception $ex ) {
3361 call_user_func( $this->errorLogger, $ex );
3362 $e = $e ?: $ex;
3363 }
3364 }
3365 } while ( count( $this->trxPreCommitCallbacks ) );
3366
3367 if ( $e instanceof Exception ) {
3368 throw $e; // re-throw any first exception
3369 }
3370 }
3371
3372 /**
3373 * Actually run any "transaction listener" callbacks.
3374 *
3375 * This method should not be used outside of Database/LoadBalancer
3376 *
3377 * @param int $trigger IDatabase::TRIGGER_* constant
3378 * @throws Exception
3379 * @since 1.20
3380 */
3381 public function runTransactionListenerCallbacks( $trigger ) {
3382 if ( $this->trxEndCallbacksSuppressed ) {
3383 return;
3384 }
3385
3386 /** @var Exception $e */
3387 $e = null; // first exception
3388
3389 foreach ( $this->trxRecurringCallbacks as $phpCallback ) {
3390 try {
3391 $phpCallback( $trigger, $this );
3392 } catch ( Exception $ex ) {
3393 call_user_func( $this->errorLogger, $ex );
3394 $e = $e ?: $ex;
3395 }
3396 }
3397
3398 if ( $e instanceof Exception ) {
3399 throw $e; // re-throw any first exception
3400 }
3401 }
3402
3403 /**
3404 * Create a savepoint
3405 *
3406 * This is used internally to implement atomic sections. It should not be
3407 * used otherwise.
3408 *
3409 * @since 1.31
3410 * @param string $identifier Identifier for the savepoint
3411 * @param string $fname Calling function name
3412 */
3413 protected function doSavepoint( $identifier, $fname ) {
3414 $this->query( 'SAVEPOINT ' . $this->addIdentifierQuotes( $identifier ), $fname );
3415 }
3416
3417 /**
3418 * Release a savepoint
3419 *
3420 * This is used internally to implement atomic sections. It should not be
3421 * used otherwise.
3422 *
3423 * @since 1.31
3424 * @param string $identifier Identifier for the savepoint
3425 * @param string $fname Calling function name
3426 */
3427 protected function doReleaseSavepoint( $identifier, $fname ) {
3428 $this->query( 'RELEASE SAVEPOINT ' . $this->addIdentifierQuotes( $identifier ), $fname );
3429 }
3430
3431 /**
3432 * Rollback to a savepoint
3433 *
3434 * This is used internally to implement atomic sections. It should not be
3435 * used otherwise.
3436 *
3437 * @since 1.31
3438 * @param string $identifier Identifier for the savepoint
3439 * @param string $fname Calling function name
3440 */
3441 protected function doRollbackToSavepoint( $identifier, $fname ) {
3442 $this->query( 'ROLLBACK TO SAVEPOINT ' . $this->addIdentifierQuotes( $identifier ), $fname );
3443 }
3444
3445 final public function startAtomic(
3446 $fname = __METHOD__, $cancelable = self::ATOMIC_NOT_CANCELABLE
3447 ) {
3448 $savepointId = $cancelable === self::ATOMIC_CANCELABLE ? 'n/a' : null;
3449 if ( !$this->trxLevel ) {
3450 $this->begin( $fname, self::TRANSACTION_INTERNAL );
3451 // If DBO_TRX is set, a series of startAtomic/endAtomic pairs will result
3452 // in all changes being in one transaction to keep requests transactional.
3453 if ( !$this->getFlag( self::DBO_TRX ) ) {
3454 $this->trxAutomaticAtomic = true;
3455 }
3456 } elseif ( $cancelable === self::ATOMIC_CANCELABLE ) {
3457 $savepointId = 'wikimedia_rdbms_atomic' . ++$this->trxAtomicCounter;
3458 if ( strlen( $savepointId ) > 30 ) { // 30 == Oracle's identifier length limit (pre 12c)
3459 $this->queryLogger->warning(
3460 'There have been an excessively large number of atomic sections in a transaction'
3461 . " started by $this->trxFname, reusing IDs (at $fname)",
3462 [ 'trace' => ( new RuntimeException() )->getTraceAsString() ]
3463 );
3464 $this->trxAtomicCounter = 0;
3465 $savepointId = 'wikimedia_rdbms_atomic' . ++$this->trxAtomicCounter;
3466 }
3467 $this->doSavepoint( $savepointId, $fname );
3468 }
3469
3470 $this->trxAtomicLevels[] = [ $fname, $savepointId ];
3471 }
3472
3473 final public function endAtomic( $fname = __METHOD__ ) {
3474 if ( !$this->trxLevel ) {
3475 throw new DBUnexpectedError( $this, "No atomic transaction is open (got $fname)." );
3476 }
3477
3478 list( $savedFname, $savepointId ) = $this->trxAtomicLevels
3479 ? array_pop( $this->trxAtomicLevels ) : [ null, null ];
3480 if ( $savedFname !== $fname ) {
3481 throw new DBUnexpectedError( $this, "Invalid atomic section ended (got $fname)." );
3482 }
3483
3484 if ( !$this->trxAtomicLevels && $this->trxAutomaticAtomic ) {
3485 $this->commit( $fname, self::FLUSHING_INTERNAL );
3486 } elseif ( $savepointId && $savepointId !== 'n/a' ) {
3487 $this->doReleaseSavepoint( $savepointId, $fname );
3488 }
3489 }
3490
3491 final public function cancelAtomic( $fname = __METHOD__ ) {
3492 if ( !$this->trxLevel ) {
3493 throw new DBUnexpectedError( $this, "No atomic transaction is open (got $fname)." );
3494 }
3495
3496 list( $savedFname, $savepointId ) = $this->trxAtomicLevels
3497 ? array_pop( $this->trxAtomicLevels ) : [ null, null ];
3498 if ( $savedFname !== $fname ) {
3499 throw new DBUnexpectedError( $this, "Invalid atomic section ended (got $fname)." );
3500 }
3501 if ( !$savepointId ) {
3502 throw new DBUnexpectedError( $this, "Uncancelable atomic section canceled (got $fname)." );
3503 }
3504
3505 if ( !$this->trxAtomicLevels && $this->trxAutomaticAtomic ) {
3506 $this->rollback( $fname, self::FLUSHING_INTERNAL );
3507 } elseif ( $savepointId !== 'n/a' ) {
3508 $this->doRollbackToSavepoint( $savepointId, $fname );
3509 $this->trxStatus = self::STATUS_TRX_OK; // no exception; recovered
3510 $this->trxStatusIgnoredCause = null;
3511 }
3512
3513 $this->affectedRowCount = 0; // for the sake of consistency
3514 }
3515
3516 final public function doAtomicSection( $fname, callable $callback ) {
3517 $this->startAtomic( $fname, self::ATOMIC_CANCELABLE );
3518 try {
3519 $res = call_user_func_array( $callback, [ $this, $fname ] );
3520 } catch ( Exception $e ) {
3521 $this->cancelAtomic( $fname );
3522 throw $e;
3523 }
3524 $this->endAtomic( $fname );
3525
3526 return $res;
3527 }
3528
3529 final public function begin( $fname = __METHOD__, $mode = self::TRANSACTION_EXPLICIT ) {
3530 static $modes = [ self::TRANSACTION_EXPLICIT, self::TRANSACTION_INTERNAL ];
3531 if ( !in_array( $mode, $modes, true ) ) {
3532 throw new DBUnexpectedError( $this, "$fname: invalid mode parameter '$mode'." );
3533 }
3534
3535 // Protect against mismatched atomic section, transaction nesting, and snapshot loss
3536 if ( $this->trxLevel ) {
3537 if ( $this->trxAtomicLevels ) {
3538 $levels = $this->flatAtomicSectionList();
3539 $msg = "$fname: Got explicit BEGIN while atomic section(s) $levels are open.";
3540 throw new DBUnexpectedError( $this, $msg );
3541 } elseif ( !$this->trxAutomatic ) {
3542 $msg = "$fname: Explicit transaction already active (from {$this->trxFname}).";
3543 throw new DBUnexpectedError( $this, $msg );
3544 } else {
3545 $msg = "$fname: Implicit transaction already active (from {$this->trxFname}).";
3546 throw new DBUnexpectedError( $this, $msg );
3547 }
3548 } elseif ( $this->getFlag( self::DBO_TRX ) && $mode !== self::TRANSACTION_INTERNAL ) {
3549 $msg = "$fname: Implicit transaction expected (DBO_TRX set).";
3550 throw new DBUnexpectedError( $this, $msg );
3551 }
3552
3553 // Avoid fatals if close() was called
3554 $this->assertOpen();
3555
3556 $this->doBegin( $fname );
3557 $this->trxStatus = self::STATUS_TRX_OK;
3558 $this->trxStatusIgnoredCause = null;
3559 $this->trxAtomicCounter = 0;
3560 $this->trxTimestamp = microtime( true );
3561 $this->trxFname = $fname;
3562 $this->trxDoneWrites = false;
3563 $this->trxAutomaticAtomic = false;
3564 $this->trxAtomicLevels = [];
3565 $this->trxShortId = sprintf( '%06x', mt_rand( 0, 0xffffff ) );
3566 $this->trxWriteDuration = 0.0;
3567 $this->trxWriteQueryCount = 0;
3568 $this->trxWriteAffectedRows = 0;
3569 $this->trxWriteAdjDuration = 0.0;
3570 $this->trxWriteAdjQueryCount = 0;
3571 $this->trxWriteCallers = [];
3572 // First SELECT after BEGIN will establish the snapshot in REPEATABLE-READ.
3573 // Get an estimate of the replication lag before any such queries.
3574 $this->trxReplicaLag = null; // clear cached value first
3575 $this->trxReplicaLag = $this->getApproximateLagStatus()['lag'];
3576 // T147697: make explicitTrxActive() return true until begin() finishes. This way, no
3577 // caller will think its OK to muck around with the transaction just because startAtomic()
3578 // has not yet completed (e.g. setting trxAtomicLevels).
3579 $this->trxAutomatic = ( $mode === self::TRANSACTION_INTERNAL );
3580 }
3581
3582 /**
3583 * Issues the BEGIN command to the database server.
3584 *
3585 * @see Database::begin()
3586 * @param string $fname
3587 */
3588 protected function doBegin( $fname ) {
3589 $this->query( 'BEGIN', $fname );
3590 $this->trxLevel = 1;
3591 }
3592
3593 final public function commit( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) {
3594 static $modes = [ self::FLUSHING_ONE, self::FLUSHING_ALL_PEERS, self::FLUSHING_INTERNAL ];
3595 if ( !in_array( $flush, $modes, true ) ) {
3596 throw new DBUnexpectedError( $this, "$fname: invalid flush parameter '$flush'." );
3597 }
3598
3599 if ( $this->trxLevel && $this->trxAtomicLevels ) {
3600 // There are still atomic sections open; this cannot be ignored
3601 $levels = $this->flatAtomicSectionList();
3602 throw new DBUnexpectedError(
3603 $this,
3604 "$fname: Got COMMIT while atomic sections $levels are still open."
3605 );
3606 }
3607
3608 if ( $flush === self::FLUSHING_INTERNAL || $flush === self::FLUSHING_ALL_PEERS ) {
3609 if ( !$this->trxLevel ) {
3610 return; // nothing to do
3611 } elseif ( !$this->trxAutomatic ) {
3612 throw new DBUnexpectedError(
3613 $this,
3614 "$fname: Flushing an explicit transaction, getting out of sync."
3615 );
3616 }
3617 } else {
3618 if ( !$this->trxLevel ) {
3619 $this->queryLogger->error(
3620 "$fname: No transaction to commit, something got out of sync." );
3621 return; // nothing to do
3622 } elseif ( $this->trxAutomatic ) {
3623 throw new DBUnexpectedError(
3624 $this,
3625 "$fname: Expected mass commit of all peer transactions (DBO_TRX set)."
3626 );
3627 }
3628 }
3629
3630 // Avoid fatals if close() was called
3631 $this->assertOpen();
3632
3633 $this->runOnTransactionPreCommitCallbacks();
3634 $writeTime = $this->pendingWriteQueryDuration( self::ESTIMATE_DB_APPLY );
3635 $this->doCommit( $fname );
3636 $this->trxStatus = self::STATUS_TRX_NONE;
3637 if ( $this->trxDoneWrites ) {
3638 $this->lastWriteTime = microtime( true );
3639 $this->trxProfiler->transactionWritingOut(
3640 $this->server,
3641 $this->dbName,
3642 $this->trxShortId,
3643 $writeTime,
3644 $this->trxWriteAffectedRows
3645 );
3646 }
3647
3648 $this->runOnTransactionIdleCallbacks( self::TRIGGER_COMMIT );
3649 $this->runTransactionListenerCallbacks( self::TRIGGER_COMMIT );
3650 }
3651
3652 /**
3653 * Issues the COMMIT command to the database server.
3654 *
3655 * @see Database::commit()
3656 * @param string $fname
3657 */
3658 protected function doCommit( $fname ) {
3659 if ( $this->trxLevel ) {
3660 $this->query( 'COMMIT', $fname );
3661 $this->trxLevel = 0;
3662 }
3663 }
3664
3665 final public function rollback( $fname = __METHOD__, $flush = '' ) {
3666 $trxActive = $this->trxLevel;
3667
3668 if ( $flush !== self::FLUSHING_INTERNAL && $flush !== self::FLUSHING_ALL_PEERS ) {
3669 if ( $this->getFlag( self::DBO_TRX ) ) {
3670 throw new DBUnexpectedError(
3671 $this,
3672 "$fname: Expected mass rollback of all peer transactions (DBO_TRX set)."
3673 );
3674 }
3675 }
3676
3677 if ( $trxActive ) {
3678 // Avoid fatals if close() was called
3679 $this->assertOpen();
3680
3681 $this->doRollback( $fname );
3682 $this->trxStatus = self::STATUS_TRX_NONE;
3683 $this->trxAtomicLevels = [];
3684 if ( $this->trxDoneWrites ) {
3685 $this->trxProfiler->transactionWritingOut(
3686 $this->server,
3687 $this->dbName,
3688 $this->trxShortId
3689 );
3690 }
3691 }
3692
3693 // Clear any commit-dependant callbacks. They might even be present
3694 // only due to transaction rounds, with no SQL transaction being active
3695 $this->trxIdleCallbacks = [];
3696 $this->trxPreCommitCallbacks = [];
3697
3698 if ( $trxActive ) {
3699 try {
3700 $this->runOnTransactionIdleCallbacks( self::TRIGGER_ROLLBACK );
3701 } catch ( Exception $e ) {
3702 // already logged; finish and let LoadBalancer move on during mass-rollback
3703 }
3704 try {
3705 $this->runTransactionListenerCallbacks( self::TRIGGER_ROLLBACK );
3706 } catch ( Exception $e ) {
3707 // already logged; let LoadBalancer move on during mass-rollback
3708 }
3709
3710 $this->affectedRowCount = 0; // for the sake of consistency
3711 }
3712 }
3713
3714 /**
3715 * Issues the ROLLBACK command to the database server.
3716 *
3717 * @see Database::rollback()
3718 * @param string $fname
3719 */
3720 protected function doRollback( $fname ) {
3721 if ( $this->trxLevel ) {
3722 # Disconnects cause rollback anyway, so ignore those errors
3723 $ignoreErrors = true;
3724 $this->query( 'ROLLBACK', $fname, $ignoreErrors );
3725 $this->trxLevel = 0;
3726 }
3727 }
3728
3729 public function flushSnapshot( $fname = __METHOD__ ) {
3730 if ( $this->writesOrCallbacksPending() || $this->explicitTrxActive() ) {
3731 // This only flushes transactions to clear snapshots, not to write data
3732 $fnames = implode( ', ', $this->pendingWriteAndCallbackCallers() );
3733 throw new DBUnexpectedError(
3734 $this,
3735 "$fname: Cannot flush snapshot because writes are pending ($fnames)."
3736 );
3737 }
3738
3739 $this->commit( $fname, self::FLUSHING_INTERNAL );
3740 }
3741
3742 public function explicitTrxActive() {
3743 return $this->trxLevel && ( $this->trxAtomicLevels || !$this->trxAutomatic );
3744 }
3745
3746 public function duplicateTableStructure(
3747 $oldName, $newName, $temporary = false, $fname = __METHOD__
3748 ) {
3749 throw new RuntimeException( __METHOD__ . ' is not implemented in descendant class' );
3750 }
3751
3752 public function listTables( $prefix = null, $fname = __METHOD__ ) {
3753 throw new RuntimeException( __METHOD__ . ' is not implemented in descendant class' );
3754 }
3755
3756 public function listViews( $prefix = null, $fname = __METHOD__ ) {
3757 throw new RuntimeException( __METHOD__ . ' is not implemented in descendant class' );
3758 }
3759
3760 public function timestamp( $ts = 0 ) {
3761 $t = new ConvertibleTimestamp( $ts );
3762 // Let errors bubble up to avoid putting garbage in the DB
3763 return $t->getTimestamp( TS_MW );
3764 }
3765
3766 public function timestampOrNull( $ts = null ) {
3767 if ( is_null( $ts ) ) {
3768 return null;
3769 } else {
3770 return $this->timestamp( $ts );
3771 }
3772 }
3773
3774 public function affectedRows() {
3775 return ( $this->affectedRowCount === null )
3776 ? $this->fetchAffectedRowCount() // default to driver value
3777 : $this->affectedRowCount;
3778 }
3779
3780 /**
3781 * @return int Number of retrieved rows according to the driver
3782 */
3783 abstract protected function fetchAffectedRowCount();
3784
3785 /**
3786 * Take the result from a query, and wrap it in a ResultWrapper if
3787 * necessary. Boolean values are passed through as is, to indicate success
3788 * of write queries or failure.
3789 *
3790 * Once upon a time, Database::query() returned a bare MySQL result
3791 * resource, and it was necessary to call this function to convert it to
3792 * a wrapper. Nowadays, raw database objects are never exposed to external
3793 * callers, so this is unnecessary in external code.
3794 *
3795 * @param bool|ResultWrapper|resource|object $result
3796 * @return bool|ResultWrapper
3797 */
3798 protected function resultObject( $result ) {
3799 if ( !$result ) {
3800 return false;
3801 } elseif ( $result instanceof ResultWrapper ) {
3802 return $result;
3803 } elseif ( $result === true ) {
3804 // Successful write query
3805 return $result;
3806 } else {
3807 return new ResultWrapper( $this, $result );
3808 }
3809 }
3810
3811 public function ping( &$rtt = null ) {
3812 // Avoid hitting the server if it was hit recently
3813 if ( $this->isOpen() && ( microtime( true ) - $this->lastPing ) < self::PING_TTL ) {
3814 if ( !func_num_args() || $this->rttEstimate > 0 ) {
3815 $rtt = $this->rttEstimate;
3816 return true; // don't care about $rtt
3817 }
3818 }
3819
3820 // This will reconnect if possible or return false if not
3821 $this->clearFlag( self::DBO_TRX, self::REMEMBER_PRIOR );
3822 $ok = ( $this->query( self::PING_QUERY, __METHOD__, true ) !== false );
3823 $this->restoreFlags( self::RESTORE_PRIOR );
3824
3825 if ( $ok ) {
3826 $rtt = $this->rttEstimate;
3827 }
3828
3829 return $ok;
3830 }
3831
3832 /**
3833 * Close any existing (dead) database connection and open a new connection
3834 *
3835 * @param string $fname
3836 * @return bool True if new connection is opened successfully, false if error
3837 */
3838 protected function replaceLostConnection( $fname ) {
3839 $this->closeConnection();
3840 $this->opened = false;
3841 $this->conn = false;
3842 try {
3843 $this->open( $this->server, $this->user, $this->password, $this->dbName );
3844 $this->lastPing = microtime( true );
3845 $ok = true;
3846
3847 $this->connLogger->warning(
3848 $fname . ': lost connection to {dbserver}; reconnected',
3849 [
3850 'dbserver' => $this->getServer(),
3851 'trace' => ( new RuntimeException() )->getTraceAsString()
3852 ]
3853 );
3854 } catch ( DBConnectionError $e ) {
3855 $ok = false;
3856
3857 $this->connLogger->error(
3858 $fname . ': lost connection to {dbserver} permanently',
3859 [ 'dbserver' => $this->getServer() ]
3860 );
3861 }
3862
3863 $this->handleSessionLoss();
3864
3865 return $ok;
3866 }
3867
3868 public function getSessionLagStatus() {
3869 return $this->getRecordedTransactionLagStatus() ?: $this->getApproximateLagStatus();
3870 }
3871
3872 /**
3873 * Get the replica DB lag when the current transaction started
3874 *
3875 * This is useful when transactions might use snapshot isolation
3876 * (e.g. REPEATABLE-READ in innodb), so the "real" lag of that data
3877 * is this lag plus transaction duration. If they don't, it is still
3878 * safe to be pessimistic. This returns null if there is no transaction.
3879 *
3880 * This returns null if the lag status for this transaction was not yet recorded.
3881 *
3882 * @return array|null ('lag': seconds or false on error, 'since': UNIX timestamp of BEGIN)
3883 * @since 1.27
3884 */
3885 final protected function getRecordedTransactionLagStatus() {
3886 return ( $this->trxLevel && $this->trxReplicaLag !== null )
3887 ? [ 'lag' => $this->trxReplicaLag, 'since' => $this->trxTimestamp() ]
3888 : null;
3889 }
3890
3891 /**
3892 * Get a replica DB lag estimate for this server
3893 *
3894 * @return array ('lag': seconds or false on error, 'since': UNIX timestamp of estimate)
3895 * @since 1.27
3896 */
3897 protected function getApproximateLagStatus() {
3898 return [
3899 'lag' => $this->getLBInfo( 'replica' ) ? $this->getLag() : 0,
3900 'since' => microtime( true )
3901 ];
3902 }
3903
3904 /**
3905 * Merge the result of getSessionLagStatus() for several DBs
3906 * using the most pessimistic values to estimate the lag of
3907 * any data derived from them in combination
3908 *
3909 * This is information is useful for caching modules
3910 *
3911 * @see WANObjectCache::set()
3912 * @see WANObjectCache::getWithSetCallback()
3913 *
3914 * @param IDatabase $db1
3915 * @param IDatabase $db2 [optional]
3916 * @return array Map of values:
3917 * - lag: highest lag of any of the DBs or false on error (e.g. replication stopped)
3918 * - since: oldest UNIX timestamp of any of the DB lag estimates
3919 * - pending: whether any of the DBs have uncommitted changes
3920 * @throws DBError
3921 * @since 1.27
3922 */
3923 public static function getCacheSetOptions( IDatabase $db1, IDatabase $db2 = null ) {
3924 $res = [ 'lag' => 0, 'since' => INF, 'pending' => false ];
3925 foreach ( func_get_args() as $db ) {
3926 /** @var IDatabase $db */
3927 $status = $db->getSessionLagStatus();
3928 if ( $status['lag'] === false ) {
3929 $res['lag'] = false;
3930 } elseif ( $res['lag'] !== false ) {
3931 $res['lag'] = max( $res['lag'], $status['lag'] );
3932 }
3933 $res['since'] = min( $res['since'], $status['since'] );
3934 $res['pending'] = $res['pending'] ?: $db->writesPending();
3935 }
3936
3937 return $res;
3938 }
3939
3940 public function getLag() {
3941 return 0;
3942 }
3943
3944 public function maxListLen() {
3945 return 0;
3946 }
3947
3948 public function encodeBlob( $b ) {
3949 return $b;
3950 }
3951
3952 public function decodeBlob( $b ) {
3953 if ( $b instanceof Blob ) {
3954 $b = $b->fetch();
3955 }
3956 return $b;
3957 }
3958
3959 public function setSessionOptions( array $options ) {
3960 }
3961
3962 public function sourceFile(
3963 $filename,
3964 callable $lineCallback = null,
3965 callable $resultCallback = null,
3966 $fname = false,
3967 callable $inputCallback = null
3968 ) {
3969 Wikimedia\suppressWarnings();
3970 $fp = fopen( $filename, 'r' );
3971 Wikimedia\restoreWarnings();
3972
3973 if ( false === $fp ) {
3974 throw new RuntimeException( "Could not open \"{$filename}\".\n" );
3975 }
3976
3977 if ( !$fname ) {
3978 $fname = __METHOD__ . "( $filename )";
3979 }
3980
3981 try {
3982 $error = $this->sourceStream(
3983 $fp, $lineCallback, $resultCallback, $fname, $inputCallback );
3984 } catch ( Exception $e ) {
3985 fclose( $fp );
3986 throw $e;
3987 }
3988
3989 fclose( $fp );
3990
3991 return $error;
3992 }
3993
3994 public function setSchemaVars( $vars ) {
3995 $this->schemaVars = $vars;
3996 }
3997
3998 public function sourceStream(
3999 $fp,
4000 callable $lineCallback = null,
4001 callable $resultCallback = null,
4002 $fname = __METHOD__,
4003 callable $inputCallback = null
4004 ) {
4005 $delimiterReset = new ScopedCallback(
4006 function ( $delimiter ) {
4007 $this->delimiter = $delimiter;
4008 },
4009 [ $this->delimiter ]
4010 );
4011 $cmd = '';
4012
4013 while ( !feof( $fp ) ) {
4014 if ( $lineCallback ) {
4015 call_user_func( $lineCallback );
4016 }
4017
4018 $line = trim( fgets( $fp ) );
4019
4020 if ( $line == '' ) {
4021 continue;
4022 }
4023
4024 if ( '-' == $line[0] && '-' == $line[1] ) {
4025 continue;
4026 }
4027
4028 if ( $cmd != '' ) {
4029 $cmd .= ' ';
4030 }
4031
4032 $done = $this->streamStatementEnd( $cmd, $line );
4033
4034 $cmd .= "$line\n";
4035
4036 if ( $done || feof( $fp ) ) {
4037 $cmd = $this->replaceVars( $cmd );
4038
4039 if ( $inputCallback ) {
4040 $callbackResult = call_user_func( $inputCallback, $cmd );
4041
4042 if ( is_string( $callbackResult ) || !$callbackResult ) {
4043 $cmd = $callbackResult;
4044 }
4045 }
4046
4047 if ( $cmd ) {
4048 $res = $this->query( $cmd, $fname );
4049
4050 if ( $resultCallback ) {
4051 call_user_func( $resultCallback, $res, $this );
4052 }
4053
4054 if ( false === $res ) {
4055 $err = $this->lastError();
4056
4057 return "Query \"{$cmd}\" failed with error code \"$err\".\n";
4058 }
4059 }
4060 $cmd = '';
4061 }
4062 }
4063
4064 ScopedCallback::consume( $delimiterReset );
4065 return true;
4066 }
4067
4068 /**
4069 * Called by sourceStream() to check if we've reached a statement end
4070 *
4071 * @param string &$sql SQL assembled so far
4072 * @param string &$newLine New line about to be added to $sql
4073 * @return bool Whether $newLine contains end of the statement
4074 */
4075 public function streamStatementEnd( &$sql, &$newLine ) {
4076 if ( $this->delimiter ) {
4077 $prev = $newLine;
4078 $newLine = preg_replace(
4079 '/' . preg_quote( $this->delimiter, '/' ) . '$/', '', $newLine );
4080 if ( $newLine != $prev ) {
4081 return true;
4082 }
4083 }
4084
4085 return false;
4086 }
4087
4088 /**
4089 * Database independent variable replacement. Replaces a set of variables
4090 * in an SQL statement with their contents as given by $this->getSchemaVars().
4091 *
4092 * Supports '{$var}' `{$var}` and / *$var* / (without the spaces) style variables.
4093 *
4094 * - '{$var}' should be used for text and is passed through the database's
4095 * addQuotes method.
4096 * - `{$var}` should be used for identifiers (e.g. table and database names).
4097 * It is passed through the database's addIdentifierQuotes method which
4098 * can be overridden if the database uses something other than backticks.
4099 * - / *_* / or / *$wgDBprefix* / passes the name that follows through the
4100 * database's tableName method.
4101 * - / *i* / passes the name that follows through the database's indexName method.
4102 * - In all other cases, / *$var* / is left unencoded. Except for table options,
4103 * its use should be avoided. In 1.24 and older, string encoding was applied.
4104 *
4105 * @param string $ins SQL statement to replace variables in
4106 * @return string The new SQL statement with variables replaced
4107 */
4108 protected function replaceVars( $ins ) {
4109 $vars = $this->getSchemaVars();
4110 return preg_replace_callback(
4111 '!
4112 /\* (\$wgDBprefix|[_i]) \*/ (\w*) | # 1-2. tableName, indexName
4113 \'\{\$ (\w+) }\' | # 3. addQuotes
4114 `\{\$ (\w+) }` | # 4. addIdentifierQuotes
4115 /\*\$ (\w+) \*/ # 5. leave unencoded
4116 !x',
4117 function ( $m ) use ( $vars ) {
4118 // Note: Because of <https://bugs.php.net/bug.php?id=51881>,
4119 // check for both nonexistent keys *and* the empty string.
4120 if ( isset( $m[1] ) && $m[1] !== '' ) {
4121 if ( $m[1] === 'i' ) {
4122 return $this->indexName( $m[2] );
4123 } else {
4124 return $this->tableName( $m[2] );
4125 }
4126 } elseif ( isset( $m[3] ) && $m[3] !== '' && array_key_exists( $m[3], $vars ) ) {
4127 return $this->addQuotes( $vars[$m[3]] );
4128 } elseif ( isset( $m[4] ) && $m[4] !== '' && array_key_exists( $m[4], $vars ) ) {
4129 return $this->addIdentifierQuotes( $vars[$m[4]] );
4130 } elseif ( isset( $m[5] ) && $m[5] !== '' && array_key_exists( $m[5], $vars ) ) {
4131 return $vars[$m[5]];
4132 } else {
4133 return $m[0];
4134 }
4135 },
4136 $ins
4137 );
4138 }
4139
4140 /**
4141 * Get schema variables. If none have been set via setSchemaVars(), then
4142 * use some defaults from the current object.
4143 *
4144 * @return array
4145 */
4146 protected function getSchemaVars() {
4147 if ( $this->schemaVars ) {
4148 return $this->schemaVars;
4149 } else {
4150 return $this->getDefaultSchemaVars();
4151 }
4152 }
4153
4154 /**
4155 * Get schema variables to use if none have been set via setSchemaVars().
4156 *
4157 * Override this in derived classes to provide variables for tables.sql
4158 * and SQL patch files.
4159 *
4160 * @return array
4161 */
4162 protected function getDefaultSchemaVars() {
4163 return [];
4164 }
4165
4166 public function lockIsFree( $lockName, $method ) {
4167 // RDBMs methods for checking named locks may or may not count this thread itself.
4168 // In MySQL, IS_FREE_LOCK() returns 0 if the thread already has the lock. This is
4169 // the behavior choosen by the interface for this method.
4170 return !isset( $this->namedLocksHeld[$lockName] );
4171 }
4172
4173 public function lock( $lockName, $method, $timeout = 5 ) {
4174 $this->namedLocksHeld[$lockName] = 1;
4175
4176 return true;
4177 }
4178
4179 public function unlock( $lockName, $method ) {
4180 unset( $this->namedLocksHeld[$lockName] );
4181
4182 return true;
4183 }
4184
4185 public function getScopedLockAndFlush( $lockKey, $fname, $timeout ) {
4186 if ( $this->writesOrCallbacksPending() ) {
4187 // This only flushes transactions to clear snapshots, not to write data
4188 $fnames = implode( ', ', $this->pendingWriteAndCallbackCallers() );
4189 throw new DBUnexpectedError(
4190 $this,
4191 "$fname: Cannot flush pre-lock snapshot because writes are pending ($fnames)."
4192 );
4193 }
4194
4195 if ( !$this->lock( $lockKey, $fname, $timeout ) ) {
4196 return null;
4197 }
4198
4199 $unlocker = new ScopedCallback( function () use ( $lockKey, $fname ) {
4200 if ( $this->trxLevel() ) {
4201 // There is a good chance an exception was thrown, causing any early return
4202 // from the caller. Let any error handler get a chance to issue rollback().
4203 // If there isn't one, let the error bubble up and trigger server-side rollback.
4204 $this->onTransactionResolution(
4205 function () use ( $lockKey, $fname ) {
4206 $this->unlock( $lockKey, $fname );
4207 },
4208 $fname
4209 );
4210 } else {
4211 $this->unlock( $lockKey, $fname );
4212 }
4213 } );
4214
4215 $this->commit( $fname, self::FLUSHING_INTERNAL );
4216
4217 return $unlocker;
4218 }
4219
4220 public function namedLocksEnqueue() {
4221 return false;
4222 }
4223
4224 public function tableLocksHaveTransactionScope() {
4225 return true;
4226 }
4227
4228 final public function lockTables( array $read, array $write, $method ) {
4229 if ( $this->writesOrCallbacksPending() ) {
4230 throw new DBUnexpectedError( $this, "Transaction writes or callbacks still pending." );
4231 }
4232
4233 if ( $this->tableLocksHaveTransactionScope() ) {
4234 $this->startAtomic( $method );
4235 }
4236
4237 return $this->doLockTables( $read, $write, $method );
4238 }
4239
4240 /**
4241 * Helper function for lockTables() that handles the actual table locking
4242 *
4243 * @param array $read Array of tables to lock for read access
4244 * @param array $write Array of tables to lock for write access
4245 * @param string $method Name of caller
4246 * @return true
4247 */
4248 protected function doLockTables( array $read, array $write, $method ) {
4249 return true;
4250 }
4251
4252 final public function unlockTables( $method ) {
4253 if ( $this->tableLocksHaveTransactionScope() ) {
4254 $this->endAtomic( $method );
4255
4256 return true; // locks released on COMMIT/ROLLBACK
4257 }
4258
4259 return $this->doUnlockTables( $method );
4260 }
4261
4262 /**
4263 * Helper function for unlockTables() that handles the actual table unlocking
4264 *
4265 * @param string $method Name of caller
4266 * @return true
4267 */
4268 protected function doUnlockTables( $method ) {
4269 return true;
4270 }
4271
4272 /**
4273 * Delete a table
4274 * @param string $tableName
4275 * @param string $fName
4276 * @return bool|ResultWrapper
4277 * @since 1.18
4278 */
4279 public function dropTable( $tableName, $fName = __METHOD__ ) {
4280 if ( !$this->tableExists( $tableName, $fName ) ) {
4281 return false;
4282 }
4283 $sql = "DROP TABLE " . $this->tableName( $tableName ) . " CASCADE";
4284
4285 return $this->query( $sql, $fName );
4286 }
4287
4288 public function getInfinity() {
4289 return 'infinity';
4290 }
4291
4292 public function encodeExpiry( $expiry ) {
4293 return ( $expiry == '' || $expiry == 'infinity' || $expiry == $this->getInfinity() )
4294 ? $this->getInfinity()
4295 : $this->timestamp( $expiry );
4296 }
4297
4298 public function decodeExpiry( $expiry, $format = TS_MW ) {
4299 if ( $expiry == '' || $expiry == 'infinity' || $expiry == $this->getInfinity() ) {
4300 return 'infinity';
4301 }
4302
4303 return ConvertibleTimestamp::convert( $format, $expiry );
4304 }
4305
4306 public function setBigSelects( $value = true ) {
4307 // no-op
4308 }
4309
4310 public function isReadOnly() {
4311 return ( $this->getReadOnlyReason() !== false );
4312 }
4313
4314 /**
4315 * @return string|bool Reason this DB is read-only or false if it is not
4316 */
4317 protected function getReadOnlyReason() {
4318 $reason = $this->getLBInfo( 'readOnlyReason' );
4319
4320 return is_string( $reason ) ? $reason : false;
4321 }
4322
4323 public function setTableAliases( array $aliases ) {
4324 $this->tableAliases = $aliases;
4325 }
4326
4327 public function setIndexAliases( array $aliases ) {
4328 $this->indexAliases = $aliases;
4329 }
4330
4331 /**
4332 * Get the underlying binding connection handle
4333 *
4334 * Makes sure the connection resource is set (disconnects and ping() failure can unset it).
4335 * This catches broken callers than catch and ignore disconnection exceptions.
4336 * Unlike checking isOpen(), this is safe to call inside of open().
4337 *
4338 * @return mixed
4339 * @throws DBUnexpectedError
4340 * @since 1.26
4341 */
4342 protected function getBindingHandle() {
4343 if ( !$this->conn ) {
4344 throw new DBUnexpectedError(
4345 $this,
4346 'DB connection was already closed or the connection dropped.'
4347 );
4348 }
4349
4350 return $this->conn;
4351 }
4352
4353 /**
4354 * @since 1.19
4355 * @return string
4356 */
4357 public function __toString() {
4358 return (string)$this->conn;
4359 }
4360
4361 /**
4362 * Make sure that copies do not share the same client binding handle
4363 * @throws DBConnectionError
4364 */
4365 public function __clone() {
4366 $this->connLogger->warning(
4367 "Cloning " . static::class . " is not recomended; forking connection:\n" .
4368 ( new RuntimeException() )->getTraceAsString()
4369 );
4370
4371 if ( $this->isOpen() ) {
4372 // Open a new connection resource without messing with the old one
4373 $this->opened = false;
4374 $this->conn = false;
4375 $this->trxEndCallbacks = []; // don't copy
4376 $this->handleSessionLoss(); // no trx or locks anymore
4377 $this->open( $this->server, $this->user, $this->password, $this->dbName );
4378 $this->lastPing = microtime( true );
4379 }
4380 }
4381
4382 /**
4383 * Called by serialize. Throw an exception when DB connection is serialized.
4384 * This causes problems on some database engines because the connection is
4385 * not restored on unserialize.
4386 */
4387 public function __sleep() {
4388 throw new RuntimeException( 'Database serialization may cause problems, since ' .
4389 'the connection is not restored on wakeup.' );
4390 }
4391
4392 /**
4393 * Run a few simple sanity checks and close dangling connections
4394 */
4395 public function __destruct() {
4396 if ( $this->trxLevel && $this->trxDoneWrites ) {
4397 trigger_error( "Uncommitted DB writes (transaction from {$this->trxFname})." );
4398 }
4399
4400 $danglingWriters = $this->pendingWriteAndCallbackCallers();
4401 if ( $danglingWriters ) {
4402 $fnames = implode( ', ', $danglingWriters );
4403 trigger_error( "DB transaction writes or callbacks still pending ($fnames)." );
4404 }
4405
4406 if ( $this->conn ) {
4407 // Avoid connection leaks for sanity. Normally, resources close at script completion.
4408 // The connection might already be closed in zend/hhvm by now, so suppress warnings.
4409 Wikimedia\suppressWarnings();
4410 $this->closeConnection();
4411 Wikimedia\restoreWarnings();
4412 $this->conn = false;
4413 $this->opened = false;
4414 }
4415 }
4416 }
4417
4418 class_alias( Database::class, 'DatabaseBase' ); // b/c for old name
4419 class_alias( Database::class, 'Database' ); // b/c global alias
Wiklou, le Wiki du Wiklou