includes/db/Database.php

   1 <?php
   2
   3 /**
   4  * @defgroup Database Database
   5  *
   6  * This file deals with database interface functions
   7  * and query specifics/optimisations.
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License along
  20  * with this program; if not, write to the Free Software Foundation, Inc.,
  21  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  22  * http://www.gnu.org/copyleft/gpl.html
  23  *
  24  * @file
  25  * @ingroup Database
  26  */
  27
  28 /**
  29  * Base interface for all DBMS-specific code. At a bare minimum, all of the
  30  * following must be implemented to support MediaWiki
  31  *
  32  * @file
  33  * @ingroup Database
  34  */
  35 interface DatabaseType {
  36         /**
  37          * Get the type of the DBMS, as it appears in $wgDBtype.
  38          *
  39          * @return string
  40          */
  41         function getType();
  42
  43         /**
  44          * Open a connection to the database. Usually aborts on failure
  45          *
  46          * @param string $server Database server host
  47          * @param string $user Database user name
  48          * @param string $password Database user password
  49          * @param string $dbName Database name
  50          * @return bool
  51          * @throws DBConnectionError
  52          */
  53         function open( $server, $user, $password, $dbName );
  54
  55         /**
  56          * Fetch the next row from the given result object, in object form.
  57          * Fields can be retrieved with $row->fieldname, with fields acting like
  58          * member variables.
  59          * If no more rows are available, false is returned.
  60          *
  61          * @param ResultWrapper|stdClass $res Object as returned from DatabaseBase::query(), etc.
  62          * @return stdClass|bool
  63          * @throws DBUnexpectedError Thrown if the database returns an error
  64          */
  65         function fetchObject( $res );
  66
  67         /**
  68          * Fetch the next row from the given result object, in associative array
  69          * form. Fields are retrieved with $row['fieldname'].
  70          * If no more rows are available, false is returned.
  71          *
  72          * @param ResultWrapper $res Result object as returned from DatabaseBase::query(), etc.
  73          * @return array|bool
  74          * @throws DBUnexpectedError Thrown if the database returns an error
  75          */
  76         function fetchRow( $res );
  77
  78         /**
  79          * Get the number of rows in a result object
  80          *
  81          * @param mixed $res A SQL result
  82          * @return int
  83          */
  84         function numRows( $res );
  85
  86         /**
  87          * Get the number of fields in a result object
  88          * @see http://www.php.net/mysql_num_fields
  89          *
  90          * @param mixed $res A SQL result
  91          * @return int
  92          */
  93         function numFields( $res );
  94
  95         /**
  96          * Get a field name in a result object
  97          * @see http://www.php.net/mysql_field_name
  98          *
  99          * @param mixed $res A SQL result
 100          * @param int $n
 101          * @return string
 102          */
 103         function fieldName( $res, $n );
 104
 105         /**
 106          * Get the inserted value of an auto-increment row
 107          *
 108          * The value inserted should be fetched from nextSequenceValue()
 109          *
 110          * Example:
 111          * $id = $dbw->nextSequenceValue( 'page_page_id_seq' );
 112          * $dbw->insert( 'page', array( 'page_id' => $id ) );
 113          * $id = $dbw->insertId();
 114          *
 115          * @return int
 116          */
 117         function insertId();
 118
 119         /**
 120          * Change the position of the cursor in a result object
 121          * @see http://www.php.net/mysql_data_seek
 122          *
 123          * @param mixed $res A SQL result
 124          * @param int $row
 125          */
 126         function dataSeek( $res, $row );
 127
 128         /**
 129          * Get the last error number
 130          * @see http://www.php.net/mysql_errno
 131          *
 132          * @return int
 133          */
 134         function lastErrno();
 135
 136         /**
 137          * Get a description of the last error
 138          * @see http://www.php.net/mysql_error
 139          *
 140          * @return string
 141          */
 142         function lastError();
 143
 144         /**
 145          * mysql_fetch_field() wrapper
 146          * Returns false if the field doesn't exist
 147          *
 148          * @param string $table Table name
 149          * @param string $field Field name
 150          *
 151          * @return Field
 152          */
 153         function fieldInfo( $table, $field );
 154
 155         /**
 156          * Get information about an index into an object
 157          * @param string $table Table name
 158          * @param string $index Index name
 159          * @param string $fname Calling function name
 160          * @return mixed Database-specific index description class or false if the index does not exist
 161          */
 162         function indexInfo( $table, $index, $fname = __METHOD__ );
 163
 164         /**
 165          * Get the number of rows affected by the last write query
 166          * @see http://www.php.net/mysql_affected_rows
 167          *
 168          * @return int
 169          */
 170         function affectedRows();
 171
 172         /**
 173          * Wrapper for addslashes()
 174          *
 175          * @param string $s String to be slashed.
 176          * @return string Slashed string.
 177          */
 178         function strencode( $s );
 179
 180         /**
 181          * Returns a wikitext link to the DB's website, e.g.,
 182          *   return "[http://www.mysql.com/ MySQL]";
 183          * Should at least contain plain text, if for some reason
 184          * your database has no website.
 185          *
 186          * @return string Wikitext of a link to the server software's web site
 187          */
 188         function getSoftwareLink();
 189
 190         /**
 191          * A string describing the current software version, like from
 192          * mysql_get_server_info().
 193          *
 194          * @return string Version information from the database server.
 195          */
 196         function getServerVersion();
 197
 198         /**
 199          * A string describing the current software version, and possibly
 200          * other details in a user-friendly way. Will be listed on Special:Version, etc.
 201          * Use getServerVersion() to get machine-friendly information.
 202          *
 203          * @return string Version information from the database server
 204          */
 205         function getServerInfo();
 206 }
 207
 208 /**
 209  * Interface for classes that implement or wrap DatabaseBase
 210  * @ingroup Database
 211  */
 212 interface IDatabase {
 213 }
 214
 215 /**
 216  * Database abstraction object
 217  * @ingroup Database
 218  */
 219 abstract class DatabaseBase implements IDatabase, DatabaseType {
 220         /** Number of times to re-try an operation in case of deadlock */
 221         const DEADLOCK_TRIES = 4;
 222
 223         /** Minimum time to wait before retry, in microseconds */
 224         const DEADLOCK_DELAY_MIN = 500000;
 225
 226         /** Maximum time to wait before retry */
 227         const DEADLOCK_DELAY_MAX = 1500000;
 228
 229 # ------------------------------------------------------------------------------
 230 # Variables
 231 # ------------------------------------------------------------------------------
 232
 233         protected $mLastQuery = '';
 234         protected $mDoneWrites = false;
 235         protected $mPHPError = false;
 236
 237         protected $mServer, $mUser, $mPassword, $mDBname;
 238
 239         /** @var resource Database connection */
 240         protected $mConn = null;
 241         protected $mOpened = false;
 242
 243         /** @var callable[] */
 244         protected $mTrxIdleCallbacks = array();
 245         /** @var callable[] */
 246         protected $mTrxPreCommitCallbacks = array();
 247
 248         protected $mTablePrefix;
 249         protected $mSchema;
 250         protected $mFlags;
 251         protected $mForeign;
 252         protected $mErrorCount = 0;
 253         protected $mLBInfo = array();
 254         protected $mDefaultBigSelects = null;
 255         protected $mSchemaVars = false;
 256
 257         protected $preparedArgs;
 258
 259         protected $htmlErrors;
 260
 261         protected $delimiter = ';';
 262
 263         /**
 264          * Either 1 if a transaction is active or 0 otherwise.
 265          * The other Trx fields may not be meaningfull if this is 0.
 266          *
 267          * @var int
 268          */
 269         protected $mTrxLevel = 0;
 270
 271         /**
 272          * Remembers the function name given for starting the most recent transaction via begin().
 273          * Used to provide additional context for error reporting.
 274          *
 275          * @var string
 276          * @see DatabaseBase::mTrxLevel
 277          */
 278         private $mTrxFname = null;
 279
 280         /**
 281          * Record if possible write queries were done in the last transaction started
 282          *
 283          * @var bool
 284          * @see DatabaseBase::mTrxLevel
 285          */
 286         private $mTrxDoneWrites = false;
 287
 288         /**
 289          * Record if the current transaction was started implicitly due to DBO_TRX being set.
 290          *
 291          * @var bool
 292          * @see DatabaseBase::mTrxLevel
 293          */
 294         private $mTrxAutomatic = false;
 295
 296         /**
 297          * Array of levels of atomicity within transactions
 298          *
 299          * @var SplStack
 300          */
 301         private $mTrxAtomicLevels;
 302
 303         /**
 304          * Record if the current transaction was started implicitly by DatabaseBase::startAtomic
 305          *
 306          * @var bool
 307          */
 308         private $mTrxAutomaticAtomic = false;
 309
 310         /**
 311          * @since 1.21
 312          * @var resource File handle for upgrade
 313          */
 314         protected $fileHandle = null;
 315
 316         /**
 317          * @since 1.22
 318          * @var string[] Process cache of VIEWs names in the database
 319          */
 320         protected $allViews = null;
 321
 322 # ------------------------------------------------------------------------------
 323 # Accessors
 324 # ------------------------------------------------------------------------------
 325         # These optionally set a variable and return the previous state
 326
 327         /**
 328          * A string describing the current software version, and possibly
 329          * other details in a user-friendly way. Will be listed on Special:Version, etc.
 330          * Use getServerVersion() to get machine-friendly information.
 331          *
 332          * @return string Version information from the database server
 333          */
 334         public function getServerInfo() {
 335                 return $this->getServerVersion();
 336         }
 337
 338         /**
 339          * @return string Command delimiter used by this database engine
 340          */
 341         public function getDelimiter() {
 342                 return $this->delimiter;
 343         }
 344
 345         /**
 346          * Boolean, controls output of large amounts of debug information.
 347          * @param bool|null $debug
 348          *   - true to enable debugging
 349          *   - false to disable debugging
 350          *   - omitted or null to do nothing
 351          *
 352          * @return bool|null Previous value of the flag
 353          */
 354         public function debug( $debug = null ) {
 355                 return wfSetBit( $this->mFlags, DBO_DEBUG, $debug );
 356         }
 357
 358         /**
 359          * Turns buffering of SQL result sets on (true) or off (false). Default is
 360          * "on".
 361          *
 362          * Unbuffered queries are very troublesome in MySQL:
 363          *
 364          *   - If another query is executed while the first query is being read
 365          *     out, the first query is killed. This means you can't call normal
 366          *     MediaWiki functions while you are reading an unbuffered query result
 367          *     from a normal wfGetDB() connection.
 368          *
 369          *   - Unbuffered queries cause the MySQL server to use large amounts of
 370          *     memory and to hold broad locks which block other queries.
 371          *
 372          * If you want to limit client-side memory, it's almost always better to
 373          * split up queries into batches using a LIMIT clause than to switch off
 374          * buffering.
 375          *
 376          * @param null|bool $buffer
 377          * @return null|bool The previous value of the flag
 378          */
 379         public function bufferResults( $buffer = null ) {
 380                 if ( is_null( $buffer ) ) {
 381                         return !(bool)( $this->mFlags & DBO_NOBUFFER );
 382                 } else {
 383                         return !wfSetBit( $this->mFlags, DBO_NOBUFFER, !$buffer );
 384                 }
 385         }
 386
 387         /**
 388          * Turns on (false) or off (true) the automatic generation and sending
 389          * of a "we're sorry, but there has been a database error" page on
 390          * database errors. Default is on (false). When turned off, the
 391          * code should use lastErrno() and lastError() to handle the
 392          * situation as appropriate.
 393          *
 394          * Do not use this function outside of the Database classes.
 395          *
 396          * @param null|bool $ignoreErrors
 397          * @return bool The previous value of the flag.
 398          */
 399         public function ignoreErrors( $ignoreErrors = null ) {
 400                 return wfSetBit( $this->mFlags, DBO_IGNORE, $ignoreErrors );
 401         }
 402
 403         /**
 404          * Gets the current transaction level.
 405          *
 406          * Historically, transactions were allowed to be "nested". This is no
 407          * longer supported, so this function really only returns a boolean.
 408          *
 409          * @return int The previous value
 410          */
 411         public function trxLevel() {
 412                 return $this->mTrxLevel;
 413         }
 414
 415         /**
 416          * Get/set the number of errors logged. Only useful when errors are ignored
 417          * @param int $count The count to set, or omitted to leave it unchanged.
 418          * @return int The error count
 419          */
 420         public function errorCount( $count = null ) {
 421                 return wfSetVar( $this->mErrorCount, $count );
 422         }
 423
 424         /**
 425          * Get/set the table prefix.
 426          * @param string $prefix The table prefix to set, or omitted to leave it unchanged.
 427          * @return string The previous table prefix.
 428          */
 429         public function tablePrefix( $prefix = null ) {
 430                 return wfSetVar( $this->mTablePrefix, $prefix );
 431         }
 432
 433         /**
 434          * Get/set the db schema.
 435          * @param string $schema The database schema to set, or omitted to leave it unchanged.
 436          * @return string The previous db schema.
 437          */
 438         public function dbSchema( $schema = null ) {
 439                 return wfSetVar( $this->mSchema, $schema );
 440         }
 441
 442         /**
 443          * Set the filehandle to copy write statements to.
 444          *
 445          * @param resource $fh File handle
 446          */
 447         public function setFileHandle( $fh ) {
 448                 $this->fileHandle = $fh;
 449         }
 450
 451         /**
 452          * Get properties passed down from the server info array of the load
 453          * balancer.
 454          *
 455          * @param string $name The entry of the info array to get, or null to get the
 456          *   whole array
 457          *
 458          * @return array|mixed|null
 459          */
 460         public function getLBInfo( $name = null ) {
 461                 if ( is_null( $name ) ) {
 462                         return $this->mLBInfo;
 463                 } else {
 464                         if ( array_key_exists( $name, $this->mLBInfo ) ) {
 465                                 return $this->mLBInfo[$name];
 466                         } else {
 467                                 return null;
 468                         }
 469                 }
 470         }
 471
 472         /**
 473          * Set the LB info array, or a member of it. If called with one parameter,
 474          * the LB info array is set to that parameter. If it is called with two
 475          * parameters, the member with the given name is set to the given value.
 476          *
 477          * @param string $name
 478          * @param array $value
 479          */
 480         public function setLBInfo( $name, $value = null ) {
 481                 if ( is_null( $value ) ) {
 482                         $this->mLBInfo = $name;
 483                 } else {
 484                         $this->mLBInfo[$name] = $value;
 485                 }
 486         }
 487
 488         /**
 489          * Set lag time in seconds for a fake slave
 490          *
 491          * @param mixed $lag Valid values for this parameter are determined by the
 492          *   subclass, but should be a PHP scalar or array that would be sensible
 493          *   as part of $wgLBFactoryConf.
 494          */
 495         public function setFakeSlaveLag( $lag ) {
 496         }
 497
 498         /**
 499          * Make this connection a fake master
 500          *
 501          * @param bool $enabled
 502          */
 503         public function setFakeMaster( $enabled = true ) {
 504         }
 505
 506         /**
 507          * Returns true if this database supports (and uses) cascading deletes
 508          *
 509          * @return bool
 510          */
 511         public function cascadingDeletes() {
 512                 return false;
 513         }
 514
 515         /**
 516          * Returns true if this database supports (and uses) triggers (e.g. on the page table)
 517          *
 518          * @return bool
 519          */
 520         public function cleanupTriggers() {
 521                 return false;
 522         }
 523
 524         /**
 525          * Returns true if this database is strict about what can be put into an IP field.
 526          * Specifically, it uses a NULL value instead of an empty string.
 527          *
 528          * @return bool
 529          */
 530         public function strictIPs() {
 531                 return false;
 532         }
 533
 534         /**
 535          * Returns true if this database uses timestamps rather than integers
 536          *
 537          * @return bool
 538          */
 539         public function realTimestamps() {
 540                 return false;
 541         }
 542
 543         /**
 544          * Returns true if this database does an implicit sort when doing GROUP BY
 545          *
 546          * @return bool
 547          */
 548         public function implicitGroupby() {
 549                 return true;
 550         }
 551
 552         /**
 553          * Returns true if this database does an implicit order by when the column has an index
 554          * For example: SELECT page_title FROM page LIMIT 1
 555          *
 556          * @return bool
 557          */
 558         public function implicitOrderby() {
 559                 return true;
 560         }
 561
 562         /**
 563          * Returns true if this database can do a native search on IP columns
 564          * e.g. this works as expected: .. WHERE rc_ip = '127.42.12.102/32';
 565          *
 566          * @return bool
 567          */
 568         public function searchableIPs() {
 569                 return false;
 570         }
 571
 572         /**
 573          * Returns true if this database can use functional indexes
 574          *
 575          * @return bool
 576          */
 577         public function functionalIndexes() {
 578                 return false;
 579         }
 580
 581         /**
 582          * Return the last query that went through DatabaseBase::query()
 583          * @return string
 584          */
 585         public function lastQuery() {
 586                 return $this->mLastQuery;
 587         }
 588
 589         /**
 590          * Returns true if the connection may have been used for write queries.
 591          * Should return true if unsure.
 592          *
 593          * @return bool
 594          */
 595         public function doneWrites() {
 596                 return $this->mDoneWrites;
 597         }
 598
 599         /**
 600          * Returns true if there is a transaction open with possible write
 601          * queries or transaction pre-commit/idle callbacks waiting on it to finish.
 602          *
 603          * @return bool
 604          */
 605         public function writesOrCallbacksPending() {
 606                 return $this->mTrxLevel && (
 607                         $this->mTrxDoneWrites || $this->mTrxIdleCallbacks || $this->mTrxPreCommitCallbacks
 608                 );
 609         }
 610
 611         /**
 612          * Is a connection to the database open?
 613          * @return bool
 614          */
 615         public function isOpen() {
 616                 return $this->mOpened;
 617         }
 618
 619         /**
 620          * Set a flag for this connection
 621          *
 622          * @param int $flag DBO_* constants from Defines.php:
 623          *   - DBO_DEBUG: output some debug info (same as debug())
 624          *   - DBO_NOBUFFER: don't buffer results (inverse of bufferResults())
 625          *   - DBO_TRX: automatically start transactions
 626          *   - DBO_DEFAULT: automatically sets DBO_TRX if not in command line mode
 627          *       and removes it in command line mode
 628          *   - DBO_PERSISTENT: use persistant database connection
 629          */
 630         public function setFlag( $flag ) {
 631                 global $wgDebugDBTransactions;
 632                 $this->mFlags |= $flag;
 633                 if ( ( $flag & DBO_TRX ) && $wgDebugDBTransactions ) {
 634                         wfDebug( "Implicit transactions are now enabled.\n" );
 635                 }
 636         }
 637
 638         /**
 639          * Clear a flag for this connection
 640          *
 641          * @param int $flag DBO_* constants from Defines.php:
 642          *   - DBO_DEBUG: output some debug info (same as debug())
 643          *   - DBO_NOBUFFER: don't buffer results (inverse of bufferResults())
 644          *   - DBO_TRX: automatically start transactions
 645          *   - DBO_DEFAULT: automatically sets DBO_TRX if not in command line mode
 646          *       and removes it in command line mode
 647          *   - DBO_PERSISTENT: use persistant database connection
 648          */
 649         public function clearFlag( $flag ) {
 650                 global $wgDebugDBTransactions;
 651                 $this->mFlags &= ~$flag;
 652                 if ( ( $flag & DBO_TRX ) && $wgDebugDBTransactions ) {
 653                         wfDebug( "Implicit transactions are now disabled.\n" );
 654                 }
 655         }
 656
 657         /**
 658          * Returns a boolean whether the flag $flag is set for this connection
 659          *
 660          * @param int $flag DBO_* constants from Defines.php:
 661          *   - DBO_DEBUG: output some debug info (same as debug())
 662          *   - DBO_NOBUFFER: don't buffer results (inverse of bufferResults())
 663          *   - DBO_TRX: automatically start transactions
 664          *   - DBO_DEFAULT: automatically sets DBO_TRX if not in command line mode
 665          *       and removes it in command line mode
 666          *   - DBO_PERSISTENT: use persistant database connection
 667          * @return bool
 668          */
 669         public function getFlag( $flag ) {
 670                 return !!( $this->mFlags & $flag );
 671         }
 672
 673         /**
 674          * General read-only accessor
 675          *
 676          * @param string $name
 677          * @return string
 678          */
 679         public function getProperty( $name ) {
 680                 return $this->$name;
 681         }
 682
 683         /**
 684          * @return string
 685          */
 686         public function getWikiID() {
 687                 if ( $this->mTablePrefix ) {
 688                         return "{$this->mDBname}-{$this->mTablePrefix}";
 689                 } else {
 690                         return $this->mDBname;
 691                 }
 692         }
 693
 694         /**
 695          * Return a path to the DBMS-specific schema file, otherwise default to tables.sql
 696          *
 697          * @return string
 698          */
 699         public function getSchemaPath() {
 700                 global $IP;
 701                 if ( file_exists( "$IP/maintenance/" . $this->getType() . "/tables.sql" ) ) {
 702                         return "$IP/maintenance/" . $this->getType() . "/tables.sql";
 703                 } else {
 704                         return "$IP/maintenance/tables.sql";
 705                 }
 706         }
 707
 708 # ------------------------------------------------------------------------------
 709 # Other functions
 710 # ------------------------------------------------------------------------------
 711
 712         /**
 713          * Constructor.
 714          *
 715          * FIXME: It is possible to construct a Database object with no associated
 716          * connection object, by specifying no parameters to __construct(). This
 717          * feature is deprecated and should be removed.
 718          *
 719          * DatabaseBase subclasses should not be constructed directly in external
 720          * code. DatabaseBase::factory() should be used instead.
 721          *
 722          * @param array $params Parameters passed from DatabaseBase::factory()
 723          */
 724         function __construct( $params = null ) {
 725                 global $wgDBprefix, $wgDBmwschema, $wgCommandLineMode, $wgDebugDBTransactions;
 726
 727                 $this->mTrxAtomicLevels = new SplStack;
 728
 729                 if ( is_array( $params ) ) { // MW 1.22
 730                         $server = $params['host'];
 731                         $user = $params['user'];
 732                         $password = $params['password'];
 733                         $dbName = $params['dbname'];
 734                         $flags = $params['flags'];
 735                         $tablePrefix = $params['tablePrefix'];
 736                         $schema = $params['schema'];
 737                         $foreign = $params['foreign'];
 738                 } else { // legacy calling pattern
 739                         wfDeprecated( __METHOD__ . " method called without parameter array.", "1.23" );
 740                         $args = func_get_args();
 741                         $server = isset( $args[0] ) ? $args[0] : false;
 742                         $user = isset( $args[1] ) ? $args[1] : false;
 743                         $password = isset( $args[2] ) ? $args[2] : false;
 744                         $dbName = isset( $args[3] ) ? $args[3] : false;
 745                         $flags = isset( $args[4] ) ? $args[4] : 0;
 746                         $tablePrefix = isset( $args[5] ) ? $args[5] : 'get from global';
 747                         $schema = 'get from global';
 748                         $foreign = isset( $args[6] ) ? $args[6] : false;
 749                 }
 750
 751                 $this->mFlags = $flags;
 752                 if ( $this->mFlags & DBO_DEFAULT ) {
 753                         if ( $wgCommandLineMode ) {
 754                                 $this->mFlags &= ~DBO_TRX;
 755                                 if ( $wgDebugDBTransactions ) {
 756                                         wfDebug( "Implicit transaction open disabled.\n" );
 757                                 }
 758                         } else {
 759                                 $this->mFlags |= DBO_TRX;
 760                                 if ( $wgDebugDBTransactions ) {
 761                                         wfDebug( "Implicit transaction open enabled.\n" );
 762                                 }
 763                         }
 764                 }
 765
 766                 /** Get the default table prefix*/
 767                 if ( $tablePrefix == 'get from global' ) {
 768                         $this->mTablePrefix = $wgDBprefix;
 769                 } else {
 770                         $this->mTablePrefix = $tablePrefix;
 771                 }
 772
 773                 /** Get the database schema*/
 774                 if ( $schema == 'get from global' ) {
 775                         $this->mSchema = $wgDBmwschema;
 776                 } else {
 777                         $this->mSchema = $schema;
 778                 }
 779
 780                 $this->mForeign = $foreign;
 781
 782                 if ( $user ) {
 783                         $this->open( $server, $user, $password, $dbName );
 784                 }
 785         }
 786
 787         /**
 788          * Called by serialize. Throw an exception when DB connection is serialized.
 789          * This causes problems on some database engines because the connection is
 790          * not restored on unserialize.
 791          */
 792         public function __sleep() {
 793                 throw new MWException( 'Database serialization may cause problems, since ' .
 794                         'the connection is not restored on wakeup.' );
 795         }
 796
 797         /**
 798          * Given a DB type, construct the name of the appropriate child class of
 799          * DatabaseBase. This is designed to replace all of the manual stuff like:
 800          *    $class = 'Database' . ucfirst( strtolower( $dbType ) );
 801          * as well as validate against the canonical list of DB types we have
 802          *
 803          * This factory function is mostly useful for when you need to connect to a
 804          * database other than the MediaWiki default (such as for external auth,
 805          * an extension, et cetera). Do not use this to connect to the MediaWiki
 806          * database. Example uses in core:
 807          * @see LoadBalancer::reallyOpenConnection()
 808          * @see ForeignDBRepo::getMasterDB()
 809          * @see WebInstallerDBConnect::execute()
 810          *
 811          * @since 1.18
 812          *
 813          * @param string $dbType A possible DB type
 814          * @param array $p An array of options to pass to the constructor.
 815          *    Valid options are: host, user, password, dbname, flags, tablePrefix, schema, driver
 816          * @throws MWException If the database driver or extension cannot be found
 817          * @return DatabaseBase|null DatabaseBase subclass or null
 818          */
 819         final public static function factory( $dbType, $p = array() ) {
 820                 $canonicalDBTypes = array(
 821                         'mysql' => array( 'mysqli', 'mysql' ),
 822                         'postgres' => array(),
 823                         'sqlite' => array(),
 824                         'oracle' => array(),
 825                         'mssql' => array(),
 826                 );
 827
 828                 $driver = false;
 829                 $dbType = strtolower( $dbType );
 830                 if ( isset( $canonicalDBTypes[$dbType] ) && $canonicalDBTypes[$dbType] ) {
 831                         $possibleDrivers = $canonicalDBTypes[$dbType];
 832                         if ( !empty( $p['driver'] ) ) {
 833                                 if ( in_array( $p['driver'], $possibleDrivers ) ) {
 834                                         $driver = $p['driver'];
 835                                 } else {
 836                                         throw new MWException( __METHOD__ .
 837                                                 " cannot construct Database with type '$dbType' and driver '{$p['driver']}'" );
 838                                 }
 839                         } else {
 840                                 foreach ( $possibleDrivers as $posDriver ) {
 841                                         if ( extension_loaded( $posDriver ) ) {
 842                                                 $driver = $posDriver;
 843                                                 break;
 844                                         }
 845                                 }
 846                         }
 847                 } else {
 848                         $driver = $dbType;
 849                 }
 850                 if ( $driver === false ) {
 851                         throw new MWException( __METHOD__ .
 852                                 " no viable database extension found for type '$dbType'" );
 853                 }
 854
 855                 // Determine schema defaults. Currently Microsoft SQL Server uses $wgDBmwschema,
 856                 // and everything else doesn't use a schema (e.g. null)
 857                 // Although postgres and oracle support schemas, we don't use them (yet)
 858                 // to maintain backwards compatibility
 859                 $defaultSchemas = array(
 860                         'mysql' => null,
 861                         'postgres' => null,
 862                         'sqlite' => null,
 863                         'oracle' => null,
 864                         'mssql' => 'get from global',
 865                 );
 866
 867                 $class = 'Database' . ucfirst( $driver );
 868                 if ( class_exists( $class ) && is_subclass_of( $class, 'DatabaseBase' ) ) {
 869                         $params = array(
 870                                 'host' => isset( $p['host'] ) ? $p['host'] : false,
 871                                 'user' => isset( $p['user'] ) ? $p['user'] : false,
 872                                 'password' => isset( $p['password'] ) ? $p['password'] : false,
 873                                 'dbname' => isset( $p['dbname'] ) ? $p['dbname'] : false,
 874                                 'flags' => isset( $p['flags'] ) ? $p['flags'] : 0,
 875                                 'tablePrefix' => isset( $p['tablePrefix'] ) ? $p['tablePrefix'] : 'get from global',
 876                                 'schema' => isset( $p['schema'] ) ? $p['schema'] : $defaultSchemas[$dbType],
 877                                 'foreign' => isset( $p['foreign'] ) ? $p['foreign'] : false
 878                         );
 879
 880                         return new $class( $params );
 881                 } else {
 882                         return null;
 883                 }
 884         }
 885
 886         protected function installErrorHandler() {
 887                 $this->mPHPError = false;
 888                 $this->htmlErrors = ini_set( 'html_errors', '0' );
 889                 set_error_handler( array( $this, 'connectionErrorHandler' ) );
 890         }
 891
 892         /**
 893          * @return bool|string
 894          */
 895         protected function restoreErrorHandler() {
 896                 restore_error_handler();
 897                 if ( $this->htmlErrors !== false ) {
 898                         ini_set( 'html_errors', $this->htmlErrors );
 899                 }
 900                 if ( $this->mPHPError ) {
 901                         $error = preg_replace( '!\[<a.*</a>\]!', '', $this->mPHPError );
 902                         $error = preg_replace( '!^.*?:\s?(.*)$!', '$1', $error );
 903
 904                         return $error;
 905                 } else {
 906                         return false;
 907                 }
 908         }
 909
 910         /**
 911          * @param int $errno
 912          * @param string $errstr
 913          */
 914         public function connectionErrorHandler( $errno, $errstr ) {
 915                 $this->mPHPError = $errstr;
 916         }
 917
 918         /**
 919          * Closes a database connection.
 920          * if it is open : commits any open transactions
 921          *
 922          * @throws MWException
 923          * @return bool Operation success. true if already closed.
 924          */
 925         public function close() {
 926                 if ( count( $this->mTrxIdleCallbacks ) ) { // sanity
 927                         throw new MWException( "Transaction idle callbacks still pending." );
 928                 }
 929                 if ( $this->mConn ) {
 930                         if ( $this->trxLevel() ) {
 931                                 if ( !$this->mTrxAutomatic ) {
 932                                         wfWarn( "Transaction still in progress (from {$this->mTrxFname}), " .
 933                                                 " performing implicit commit before closing connection!" );
 934                                 }
 935
 936                                 $this->commit( __METHOD__, 'flush' );
 937                         }
 938
 939                         $closed = $this->closeConnection();
 940                         $this->mConn = false;
 941                 } else {
 942                         $closed = true;
 943                 }
 944                 $this->mOpened = false;
 945
 946                 return $closed;
 947         }
 948
 949         /**
 950          * Closes underlying database connection
 951          * @since 1.20
 952          * @return bool Whether connection was closed successfully
 953          */
 954         abstract protected function closeConnection();
 955
 956         /**
 957          * @param string $error Fallback error message, used if none is given by DB
 958          * @throws DBConnectionError
 959          */
 960         function reportConnectionError( $error = 'Unknown error' ) {
 961                 $myError = $this->lastError();
 962                 if ( $myError ) {
 963                         $error = $myError;
 964                 }
 965
 966                 # New method
 967                 throw new DBConnectionError( $this, $error );
 968         }
 969
 970         /**
 971          * The DBMS-dependent part of query()
 972          *
 973          * @param string $sql SQL query.
 974          * @return ResultWrapper|bool Result object to feed to fetchObject,
 975          *   fetchRow, ...; or false on failure
 976          */
 977         abstract protected function doQuery( $sql );
 978
 979         /**
 980          * Determine whether a query writes to the DB.
 981          * Should return true if unsure.
 982          *
 983          * @param string $sql
 984          * @return bool
 985          */
 986         public function isWriteQuery( $sql ) {
 987                 return !preg_match( '/^(?:SELECT|BEGIN|ROLLBACK|COMMIT|SET|SHOW|EXPLAIN|\(SELECT)\b/i', $sql );
 988         }
 989
 990         /**
 991          * Run an SQL query and return the result. Normally throws a DBQueryError
 992          * on failure. If errors are ignored, returns false instead.
 993          *
 994          * In new code, the query wrappers select(), insert(), update(), delete(),
 995          * etc. should be used where possible, since they give much better DBMS
 996          * independence and automatically quote or validate user input in a variety
 997          * of contexts. This function is generally only useful for queries which are
 998          * explicitly DBMS-dependent and are unsupported by the query wrappers, such
 999          * as CREATE TABLE.
1000          *
1001          * However, the query wrappers themselves should call this function.
1002          *
1003          * @param string $sql SQL query
1004          * @param string $fname Name of the calling function, for profiling/SHOW PROCESSLIST
1005          *     comment (you can use __METHOD__ or add some extra info)
1006          * @param bool $tempIgnore Whether to avoid throwing an exception on errors...
1007          *     maybe best to catch the exception instead?
1008          * @throws MWException
1009          * @return bool|ResultWrapper True for a successful write query, ResultWrapper object
1010          *     for a successful read query, or false on failure if $tempIgnore set
1011          */
1012         public function query( $sql, $fname = __METHOD__, $tempIgnore = false ) {
1013                 global $wgUser, $wgDebugDBTransactions;
1014
1015                 $this->mLastQuery = $sql;
1016                 if ( !$this->mDoneWrites && $this->isWriteQuery( $sql ) ) {
1017                         # Set a flag indicating that writes have been done
1018                         wfDebug( __METHOD__ . ": Writes done: $sql\n" );
1019                         $this->mDoneWrites = true;
1020                 }
1021
1022                 # Add a comment for easy SHOW PROCESSLIST interpretation
1023                 if ( is_object( $wgUser ) && $wgUser->isItemLoaded( 'name' ) ) {
1024                         $userName = $wgUser->getName();
1025                         if ( mb_strlen( $userName ) > 15 ) {
1026                                 $userName = mb_substr( $userName, 0, 15 ) . '...';
1027                         }
1028                         $userName = str_replace( '/', '', $userName );
1029                 } else {
1030                         $userName = '';
1031                 }
1032
1033                 // Add trace comment to the begin of the sql string, right after the operator.
1034                 // Or, for one-word queries (like "BEGIN" or COMMIT") add it to the end (bug 42598)
1035                 $commentedSql = preg_replace( '/\s|$/', " /* $fname $userName */ ", $sql, 1 );
1036
1037                 # If DBO_TRX is set, start a transaction
1038                 if ( ( $this->mFlags & DBO_TRX ) && !$this->mTrxLevel &&
1039                         $sql != 'BEGIN' && $sql != 'COMMIT' && $sql != 'ROLLBACK'
1040                 ) {
1041                         # Avoid establishing transactions for SHOW and SET statements too -
1042                         # that would delay transaction initializations to once connection
1043                         # is really used by application
1044                         $sqlstart = substr( $sql, 0, 10 ); // very much worth it, benchmark certified(tm)
1045                         if ( strpos( $sqlstart, "SHOW " ) !== 0 && strpos( $sqlstart, "SET " ) !== 0 ) {
1046                                 if ( $wgDebugDBTransactions ) {
1047                                         wfDebug( "Implicit transaction start.\n" );
1048                                 }
1049                                 $this->begin( __METHOD__ . " ($fname)" );
1050                                 $this->mTrxAutomatic = true;
1051                         }
1052                 }
1053
1054                 # Keep track of whether the transaction has write queries pending
1055                 if ( $this->mTrxLevel && !$this->mTrxDoneWrites && $this->isWriteQuery( $sql ) ) {
1056                         $this->mTrxDoneWrites = true;
1057                         $id = spl_object_hash( $this );
1058                         Profiler::instance()->transactionWritingIn( $this->mServer, $this->mDBname, $id );
1059                 }
1060
1061                 $queryProf = '';
1062                 $totalProf = '';
1063                 $isMaster = !is_null( $this->getLBInfo( 'master' ) );
1064
1065                 if ( !Profiler::instance()->isStub() ) {
1066                         # generalizeSQL will probably cut down the query to reasonable
1067                         # logging size most of the time. The substr is really just a sanity check.
1068                         if ( $isMaster ) {
1069                                 $queryProf = 'query-m: ' . substr( DatabaseBase::generalizeSQL( $sql ), 0, 255 );
1070                                 $totalProf = 'DatabaseBase::query-master';
1071                         } else {
1072                                 $queryProf = 'query: ' . substr( DatabaseBase::generalizeSQL( $sql ), 0, 255 );
1073                                 $totalProf = 'DatabaseBase::query';
1074                         }
1075                         wfProfileIn( $totalProf );
1076                         wfProfileIn( $queryProf );
1077                 }
1078
1079                 if ( $this->debug() ) {
1080                         static $cnt = 0;
1081
1082                         $cnt++;
1083                         $sqlx = substr( $commentedSql, 0, 500 );
1084                         $sqlx = strtr( $sqlx, "\t\n", '  ' );
1085
1086                         $master = $isMaster ? 'master' : 'slave';
1087                         wfDebug( "Query {$this->mDBname} ($cnt) ($master): $sqlx\n" );
1088                 }
1089
1090                 $queryId = MWDebug::query( $sql, $fname, $isMaster );
1091
1092                 # Avoid fatals if close() was called
1093                 if ( !$this->isOpen() ) {
1094                         throw new DBUnexpectedError( $this, "DB connection was already closed." );
1095                 }
1096
1097                 # Do the query and handle errors
1098                 $ret = $this->doQuery( $commentedSql );
1099
1100                 MWDebug::queryTime( $queryId );
1101
1102                 # Try reconnecting if the connection was lost
1103                 if ( false === $ret && $this->wasErrorReissuable() ) {
1104                         # Transaction is gone, like it or not
1105                         $hadTrx = $this->mTrxLevel; // possible lost transaction
1106                         $this->mTrxLevel = 0;
1107                         $this->mTrxIdleCallbacks = array(); // bug 65263
1108                         $this->mTrxPreCommitCallbacks = array(); // bug 65263
1109                         wfDebug( "Connection lost, reconnecting...\n" );
1110
1111                         if ( $this->ping() ) {
1112                                 global $wgRequestTime;
1113                                 wfDebug( "Reconnected\n" );
1114                                 $sqlx = substr( $commentedSql, 0, 500 );
1115                                 $sqlx = strtr( $sqlx, "\t\n", '  ' );
1116                                 $elapsed = round( microtime( true ) - $wgRequestTime, 3 );
1117                                 if ( $elapsed < 300 ) {
1118                                         # Not a database error to lose a transaction after a minute or two
1119                                         wfLogDBError( "Connection lost and reconnected after {$elapsed}s, query: $sqlx" );
1120                                 }
1121                                 if ( $hadTrx ) {
1122                                         # Leave $ret as false and let an error be reported.
1123                                         # Callers may catch the exception and continue to use the DB.
1124                                 } else {
1125                                         # Should be safe to silently retry (no trx and thus no callbacks)
1126                                         $ret = $this->doQuery( $commentedSql );
1127                                 }
1128                         } else {
1129                                 wfDebug( "Failed\n" );
1130                         }
1131                 }
1132
1133                 if ( false === $ret ) {
1134                         $this->reportQueryError( $this->lastError(), $this->lastErrno(), $sql, $fname, $tempIgnore );
1135                 }
1136
1137                 if ( !Profiler::instance()->isStub() ) {
1138                         wfProfileOut( $queryProf );
1139                         wfProfileOut( $totalProf );
1140                 }
1141
1142                 return $this->resultObject( $ret );
1143         }
1144
1145         /**
1146          * Report a query error. Log the error, and if neither the object ignore
1147          * flag nor the $tempIgnore flag is set, throw a DBQueryError.
1148          *
1149          * @param string $error
1150          * @param int $errno
1151          * @param string $sql
1152          * @param string $fname
1153          * @param bool $tempIgnore
1154          * @throws DBQueryError
1155          */
1156         public function reportQueryError( $error, $errno, $sql, $fname, $tempIgnore = false ) {
1157                 # Ignore errors during error handling to avoid infinite recursion
1158                 $ignore = $this->ignoreErrors( true );
1159                 ++$this->mErrorCount;
1160
1161                 if ( $ignore || $tempIgnore ) {
1162                         wfDebug( "SQL ERROR (ignored): $error\n" );
1163                         $this->ignoreErrors( $ignore );
1164                 } else {
1165                         $sql1line = mb_substr( str_replace( "\n", "\\n", $sql ), 0, 5 * 1024 );
1166                         wfLogDBError( "$fname\t{$this->mServer}\t$errno\t$error\t$sql1line" );
1167                         wfDebug( "SQL ERROR: " . $error . "\n" );
1168                         throw new DBQueryError( $this, $error, $errno, $sql, $fname );
1169                 }
1170         }
1171
1172         /**
1173          * Intended to be compatible with the PEAR::DB wrapper functions.
1174          * http://pear.php.net/manual/en/package.database.db.intro-execute.php
1175          *
1176          * ? = scalar value, quoted as necessary
1177          * ! = raw SQL bit (a function for instance)
1178          * & = filename; reads the file and inserts as a blob
1179          *     (we don't use this though...)
1180          *
1181          * @param string $sql
1182          * @param string $func
1183          *
1184          * @return array
1185          */
1186         protected function prepare( $sql, $func = 'DatabaseBase::prepare' ) {
1187                 /* MySQL doesn't support prepared statements (yet), so just
1188                  * pack up the query for reference. We'll manually replace
1189                  * the bits later.
1190                  */
1191                 return array( 'query' => $sql, 'func' => $func );
1192         }
1193
1194         /**
1195          * Free a prepared query, generated by prepare().
1196          * @param string $prepared
1197          */
1198         protected function freePrepared( $prepared ) {
1199                 /* No-op by default */
1200         }
1201
1202         /**
1203          * Execute a prepared query with the various arguments
1204          * @param string $prepared The prepared sql
1205          * @param mixed $args Either an array here, or put scalars as varargs
1206          *
1207          * @return ResultWrapper
1208          */
1209         public function execute( $prepared, $args = null ) {
1210                 if ( !is_array( $args ) ) {
1211                         # Pull the var args
1212                         $args = func_get_args();
1213                         array_shift( $args );
1214                 }
1215
1216                 $sql = $this->fillPrepared( $prepared['query'], $args );
1217
1218                 return $this->query( $sql, $prepared['func'] );
1219         }
1220
1221         /**
1222          * For faking prepared SQL statements on DBs that don't support it directly.
1223          *
1224          * @param string $preparedQuery A 'preparable' SQL statement
1225          * @param array $args Array of Arguments to fill it with
1226          * @return string Executable SQL
1227          */
1228         public function fillPrepared( $preparedQuery, $args ) {
1229                 reset( $args );
1230                 $this->preparedArgs =& $args;
1231
1232                 return preg_replace_callback( '/(\\\\[?!&]|[?!&])/',
1233                         array( &$this, 'fillPreparedArg' ), $preparedQuery );
1234         }
1235
1236         /**
1237          * preg_callback func for fillPrepared()
1238          * The arguments should be in $this->preparedArgs and must not be touched
1239          * while we're doing this.
1240          *
1241          * @param array $matches
1242          * @throws DBUnexpectedError
1243          * @return string
1244          */
1245         protected function fillPreparedArg( $matches ) {
1246                 switch ( $matches[1] ) {
1247                         case '\\?':
1248                                 return '?';
1249                         case '\\!':
1250                                 return '!';
1251                         case '\\&':
1252                                 return '&';
1253                 }
1254
1255                 list( /* $n */, $arg ) = each( $this->preparedArgs );
1256
1257                 switch ( $matches[1] ) {
1258                         case '?':
1259                                 return $this->addQuotes( $arg );
1260                         case '!':
1261                                 return $arg;
1262                         case '&':
1263                                 # return $this->addQuotes( file_get_contents( $arg ) );
1264                                 throw new DBUnexpectedError(
1265                                         $this,
1266                                         '& mode is not implemented. If it\'s really needed, uncomment the line above.'
1267                                 );
1268                         default:
1269                                 throw new DBUnexpectedError(
1270                                         $this,
1271                                         'Received invalid match. This should never happen!'
1272                                 );
1273                 }
1274         }
1275
1276         /**
1277          * Free a result object returned by query() or select(). It's usually not
1278          * necessary to call this, just use unset() or let the variable holding
1279          * the result object go out of scope.
1280          *
1281          * @param mixed $res A SQL result
1282          */
1283         public function freeResult( $res ) {
1284         }
1285
1286         /**
1287          * A SELECT wrapper which returns a single field from a single result row.
1288          *
1289          * Usually throws a DBQueryError on failure. If errors are explicitly
1290          * ignored, returns false on failure.
1291          *
1292          * If no result rows are returned from the query, false is returned.
1293          *
1294          * @param string|array $table Table name. See DatabaseBase::select() for details.
1295          * @param string $var The field name to select. This must be a valid SQL
1296          *   fragment: do not use unvalidated user input.
1297          * @param string|array $cond The condition array. See DatabaseBase::select() for details.
1298          * @param string $fname The function name of the caller.
1299          * @param string|array $options The query options. See DatabaseBase::select() for details.
1300          *
1301          * @return bool|mixed The value from the field, or false on failure.
1302          */
1303         public function selectField( $table, $var, $cond = '', $fname = __METHOD__,
1304                 $options = array()
1305         ) {
1306                 if ( !is_array( $options ) ) {
1307                         $options = array( $options );
1308                 }
1309
1310                 $options['LIMIT'] = 1;
1311
1312                 $res = $this->select( $table, $var, $cond, $fname, $options );
1313
1314                 if ( $res === false || !$this->numRows( $res ) ) {
1315                         return false;
1316                 }
1317
1318                 $row = $this->fetchRow( $res );
1319
1320                 if ( $row !== false ) {
1321                         return reset( $row );
1322                 } else {
1323                         return false;
1324                 }
1325         }
1326
1327         /**
1328          * Returns an optional USE INDEX clause to go after the table, and a
1329          * string to go at the end of the query.
1330          *
1331          * @param array $options Associative array of options to be turned into
1332          *   an SQL query, valid keys are listed in the function.
1333          * @return array
1334          * @see DatabaseBase::select()
1335          */
1336         public function makeSelectOptions( $options ) {
1337                 $preLimitTail = $postLimitTail = '';
1338                 $startOpts = '';
1339
1340                 $noKeyOptions = array();
1341
1342                 foreach ( $options as $key => $option ) {
1343                         if ( is_numeric( $key ) ) {
1344                                 $noKeyOptions[$option] = true;
1345                         }
1346                 }
1347
1348                 $preLimitTail .= $this->makeGroupByWithHaving( $options );
1349
1350                 $preLimitTail .= $this->makeOrderBy( $options );
1351
1352                 // if (isset($options['LIMIT'])) {
1353                 //      $tailOpts .= $this->limitResult('', $options['LIMIT'],
1354                 //              isset($options['OFFSET']) ? $options['OFFSET']
1355                 //              : false);
1356                 // }
1357
1358                 if ( isset( $noKeyOptions['FOR UPDATE'] ) ) {
1359                         $postLimitTail .= ' FOR UPDATE';
1360                 }
1361
1362                 if ( isset( $noKeyOptions['LOCK IN SHARE MODE'] ) ) {
1363                         $postLimitTail .= ' LOCK IN SHARE MODE';
1364                 }
1365
1366                 if ( isset( $noKeyOptions['DISTINCT'] ) || isset( $noKeyOptions['DISTINCTROW'] ) ) {
1367                         $startOpts .= 'DISTINCT';
1368                 }
1369
1370                 # Various MySQL extensions
1371                 if ( isset( $noKeyOptions['STRAIGHT_JOIN'] ) ) {
1372                         $startOpts .= ' /*! STRAIGHT_JOIN */';
1373                 }
1374
1375                 if ( isset( $noKeyOptions['HIGH_PRIORITY'] ) ) {
1376                         $startOpts .= ' HIGH_PRIORITY';
1377                 }
1378
1379                 if ( isset( $noKeyOptions['SQL_BIG_RESULT'] ) ) {
1380                         $startOpts .= ' SQL_BIG_RESULT';
1381                 }
1382
1383                 if ( isset( $noKeyOptions['SQL_BUFFER_RESULT'] ) ) {
1384                         $startOpts .= ' SQL_BUFFER_RESULT';
1385                 }
1386
1387                 if ( isset( $noKeyOptions['SQL_SMALL_RESULT'] ) ) {
1388                         $startOpts .= ' SQL_SMALL_RESULT';
1389                 }
1390
1391                 if ( isset( $noKeyOptions['SQL_CALC_FOUND_ROWS'] ) ) {
1392                         $startOpts .= ' SQL_CALC_FOUND_ROWS';
1393                 }
1394
1395                 if ( isset( $noKeyOptions['SQL_CACHE'] ) ) {
1396                         $startOpts .= ' SQL_CACHE';
1397                 }
1398
1399                 if ( isset( $noKeyOptions['SQL_NO_CACHE'] ) ) {
1400                         $startOpts .= ' SQL_NO_CACHE';
1401                 }
1402
1403                 if ( isset( $options['USE INDEX'] ) && is_string( $options['USE INDEX'] ) ) {
1404                         $useIndex = $this->useIndexClause( $options['USE INDEX'] );
1405                 } else {
1406                         $useIndex = '';
1407                 }
1408
1409                 return array( $startOpts, $useIndex, $preLimitTail, $postLimitTail );
1410         }
1411
1412         /**
1413          * Returns an optional GROUP BY with an optional HAVING
1414          *
1415          * @param array $options Associative array of options
1416          * @return string
1417          * @see DatabaseBase::select()
1418          * @since 1.21
1419          */
1420         public function makeGroupByWithHaving( $options ) {
1421                 $sql = '';
1422                 if ( isset( $options['GROUP BY'] ) ) {
1423                         $gb = is_array( $options['GROUP BY'] )
1424                                 ? implode( ',', $options['GROUP BY'] )
1425                                 : $options['GROUP BY'];
1426                         $sql .= ' GROUP BY ' . $gb;
1427                 }
1428                 if ( isset( $options['HAVING'] ) ) {
1429                         $having = is_array( $options['HAVING'] )
1430                                 ? $this->makeList( $options['HAVING'], LIST_AND )
1431                                 : $options['HAVING'];
1432                         $sql .= ' HAVING ' . $having;
1433                 }
1434
1435                 return $sql;
1436         }
1437
1438         /**
1439          * Returns an optional ORDER BY
1440          *
1441          * @param array $options Associative array of options
1442          * @return string
1443          * @see DatabaseBase::select()
1444          * @since 1.21
1445          */
1446         public function makeOrderBy( $options ) {
1447                 if ( isset( $options['ORDER BY'] ) ) {
1448                         $ob = is_array( $options['ORDER BY'] )
1449                                 ? implode( ',', $options['ORDER BY'] )
1450                                 : $options['ORDER BY'];
1451
1452                         return ' ORDER BY ' . $ob;
1453                 }
1454
1455                 return '';
1456         }
1457
1458         /**
1459          * Execute a SELECT query constructed using the various parameters provided.
1460          * See below for full details of the parameters.
1461          *
1462          * @param string|array $table Table name
1463          * @param string|array $vars Field names
1464          * @param string|array $conds Conditions
1465          * @param string $fname Caller function name
1466          * @param array $options Query options
1467          * @param array $join_conds Join conditions
1468          *
1469          * @param string|array $table
1470          *
1471          * May be either an array of table names, or a single string holding a table
1472          * name. If an array is given, table aliases can be specified, for example:
1473          *
1474          *    array( 'a' => 'user' )
1475          *
1476          * This includes the user table in the query, with the alias "a" available
1477          * for use in field names (e.g. a.user_name).
1478          *
1479          * All of the table names given here are automatically run through
1480          * DatabaseBase::tableName(), which causes the table prefix (if any) to be
1481          * added, and various other table name mappings to be performed.
1482          *
1483          *
1484          * @param string|array $vars
1485          *
1486          * May be either a field name or an array of field names. The field names
1487          * can be complete fragments of SQL, for direct inclusion into the SELECT
1488          * query. If an array is given, field aliases can be specified, for example:
1489          *
1490          *   array( 'maxrev' => 'MAX(rev_id)' )
1491          *
1492          * This includes an expression with the alias "maxrev" in the query.
1493          *
1494          * If an expression is given, care must be taken to ensure that it is
1495          * DBMS-independent.
1496          *
1497          *
1498          * @param string|array $conds
1499          *
1500          * May be either a string containing a single condition, or an array of
1501          * conditions. If an array is given, the conditions constructed from each
1502          * element are combined with AND.
1503          *
1504          * Array elements may take one of two forms:
1505          *
1506          *   - Elements with a numeric key are interpreted as raw SQL fragments.
1507          *   - Elements with a string key are interpreted as equality conditions,
1508          *     where the key is the field name.
1509          *     - If the value of such an array element is a scalar (such as a
1510          *       string), it will be treated as data and thus quoted appropriately.
1511          *       If it is null, an IS NULL clause will be added.
1512          *     - If the value is an array, an IN(...) clause will be constructed,
1513          *       such that the field name may match any of the elements in the
1514          *       array. The elements of the array will be quoted.
1515          *
1516          * Note that expressions are often DBMS-dependent in their syntax.
1517          * DBMS-independent wrappers are provided for constructing several types of
1518          * expression commonly used in condition queries. See:
1519          *    - DatabaseBase::buildLike()
1520          *    - DatabaseBase::conditional()
1521          *
1522          *
1523          * @param string|array $options
1524          *
1525          * Optional: Array of query options. Boolean options are specified by
1526          * including them in the array as a string value with a numeric key, for
1527          * example:
1528          *
1529          *    array( 'FOR UPDATE' )
1530          *
1531          * The supported options are:
1532          *
1533          *   - OFFSET: Skip this many rows at the start of the result set. OFFSET
1534          *     with LIMIT can theoretically be used for paging through a result set,
1535          *     but this is discouraged in MediaWiki for performance reasons.
1536          *
1537          *   - LIMIT: Integer: return at most this many rows. The rows are sorted
1538          *     and then the first rows are taken until the limit is reached. LIMIT
1539          *     is applied to a result set after OFFSET.
1540          *
1541          *   - FOR UPDATE: Boolean: lock the returned rows so that they can't be
1542          *     changed until the next COMMIT.
1543          *
1544          *   - DISTINCT: Boolean: return only unique result rows.
1545          *
1546          *   - GROUP BY: May be either an SQL fragment string naming a field or
1547          *     expression to group by, or an array of such SQL fragments.
1548          *
1549          *   - HAVING: May be either an string containing a HAVING clause or an array of
1550          *     conditions building the HAVING clause. If an array is given, the conditions
1551          *     constructed from each element are combined with AND.
1552          *
1553          *   - ORDER BY: May be either an SQL fragment giving a field name or
1554          *     expression to order by, or an array of such SQL fragments.
1555          *
1556          *   - USE INDEX: This may be either a string giving the index name to use
1557          *     for the query, or an array. If it is an associative array, each key
1558          *     gives the table name (or alias), each value gives the index name to
1559          *     use for that table. All strings are SQL fragments and so should be
1560          *     validated by the caller.
1561          *
1562          *   - EXPLAIN: In MySQL, this causes an EXPLAIN SELECT query to be run,
1563          *     instead of SELECT.
1564          *
1565          * And also the following boolean MySQL extensions, see the MySQL manual
1566          * for documentation:
1567          *
1568          *    - LOCK IN SHARE MODE
1569          *    - STRAIGHT_JOIN
1570          *    - HIGH_PRIORITY
1571          *    - SQL_BIG_RESULT
1572          *    - SQL_BUFFER_RESULT
1573          *    - SQL_SMALL_RESULT
1574          *    - SQL_CALC_FOUND_ROWS
1575          *    - SQL_CACHE
1576          *    - SQL_NO_CACHE
1577          *
1578          *
1579          * @param string|array $join_conds
1580          *
1581          * Optional associative array of table-specific join conditions. In the
1582          * most common case, this is unnecessary, since the join condition can be
1583          * in $conds. However, it is useful for doing a LEFT JOIN.
1584          *
1585          * The key of the array contains the table name or alias. The value is an
1586          * array with two elements, numbered 0 and 1. The first gives the type of
1587          * join, the second is an SQL fragment giving the join condition for that
1588          * table. For example:
1589          *
1590          *    array( 'page' => array( 'LEFT JOIN', 'page_latest=rev_id' ) )
1591          *
1592          * @return ResultWrapper|bool If the query returned no rows, a ResultWrapper
1593          *   with no rows in it will be returned. If there was a query error, a
1594          *   DBQueryError exception will be thrown, except if the "ignore errors"
1595          *   option was set, in which case false will be returned.
1596          */
1597         public function select( $table, $vars, $conds = '', $fname = __METHOD__,
1598                 $options = array(), $join_conds = array() ) {
1599                 $sql = $this->selectSQLText( $table, $vars, $conds, $fname, $options, $join_conds );
1600
1601                 return $this->query( $sql, $fname );
1602         }
1603
1604         /**
1605          * The equivalent of DatabaseBase::select() except that the constructed SQL
1606          * is returned, instead of being immediately executed. This can be useful for
1607          * doing UNION queries, where the SQL text of each query is needed. In general,
1608          * however, callers outside of Database classes should just use select().
1609          *
1610          * @param string|array $table Table name
1611          * @param string|array $vars Field names
1612          * @param string|array $conds Conditions
1613          * @param string $fname Caller function name
1614          * @param string|array $options Query options
1615          * @param string|array $join_conds Join conditions
1616          *
1617          * @return string SQL query string.
1618          * @see DatabaseBase::select()
1619          */
1620         public function selectSQLText( $table, $vars, $conds = '', $fname = __METHOD__,
1621                 $options = array(), $join_conds = array()
1622         ) {
1623                 if ( is_array( $vars ) ) {
1624                         $vars = implode( ',', $this->fieldNamesWithAlias( $vars ) );
1625                 }
1626
1627                 $options = (array)$options;
1628                 $useIndexes = ( isset( $options['USE INDEX'] ) && is_array( $options['USE INDEX'] ) )
1629                         ? $options['USE INDEX']
1630                         : array();
1631
1632                 if ( is_array( $table ) ) {
1633                         $from = ' FROM ' .
1634                                 $this->tableNamesWithUseIndexOrJOIN( $table, $useIndexes, $join_conds );
1635                 } elseif ( $table != '' ) {
1636                         if ( $table[0] == ' ' ) {
1637                                 $from = ' FROM ' . $table;
1638                         } else {
1639                                 $from = ' FROM ' .
1640                                         $this->tableNamesWithUseIndexOrJOIN( array( $table ), $useIndexes, array() );
1641                         }
1642                 } else {
1643                         $from = '';
1644                 }
1645
1646                 list( $startOpts, $useIndex, $preLimitTail, $postLimitTail ) =
1647                         $this->makeSelectOptions( $options );
1648
1649                 if ( !empty( $conds ) ) {
1650                         if ( is_array( $conds ) ) {
1651                                 $conds = $this->makeList( $conds, LIST_AND );
1652                         }
1653                         $sql = "SELECT $startOpts $vars $from $useIndex WHERE $conds $preLimitTail";
1654                 } else {
1655                         $sql = "SELECT $startOpts $vars $from $useIndex $preLimitTail";
1656                 }
1657
1658                 if ( isset( $options['LIMIT'] ) ) {
1659                         $sql = $this->limitResult( $sql, $options['LIMIT'],
1660                                 isset( $options['OFFSET'] ) ? $options['OFFSET'] : false );
1661                 }
1662                 $sql = "$sql $postLimitTail";
1663
1664                 if ( isset( $options['EXPLAIN'] ) ) {
1665                         $sql = 'EXPLAIN ' . $sql;
1666                 }
1667
1668                 return $sql;
1669         }
1670
1671         /**
1672          * Single row SELECT wrapper. Equivalent to DatabaseBase::select(), except
1673          * that a single row object is returned. If the query returns no rows,
1674          * false is returned.
1675          *
1676          * @param string|array $table Table name
1677          * @param string|array $vars Field names
1678          * @param array $conds Conditions
1679          * @param string $fname Caller function name
1680          * @param string|array $options Query options
1681          * @param array|string $join_conds Join conditions
1682          *
1683          * @return stdClass|bool
1684          */
1685         public function selectRow( $table, $vars, $conds, $fname = __METHOD__,
1686                 $options = array(), $join_conds = array()
1687         ) {
1688                 $options = (array)$options;
1689                 $options['LIMIT'] = 1;
1690                 $res = $this->select( $table, $vars, $conds, $fname, $options, $join_conds );
1691
1692                 if ( $res === false ) {
1693                         return false;
1694                 }
1695
1696                 if ( !$this->numRows( $res ) ) {
1697                         return false;
1698                 }
1699
1700                 $obj = $this->fetchObject( $res );
1701
1702                 return $obj;
1703         }
1704
1705         /**
1706          * Estimate rows in dataset.
1707          *
1708          * MySQL allows you to estimate the number of rows that would be returned
1709          * by a SELECT query, using EXPLAIN SELECT. The estimate is provided using
1710          * index cardinality statistics, and is notoriously inaccurate, especially
1711          * when large numbers of rows have recently been added or deleted.
1712          *
1713          * For DBMSs that don't support fast result size estimation, this function
1714          * will actually perform the SELECT COUNT(*).
1715          *
1716          * Takes the same arguments as DatabaseBase::select().
1717          *
1718          * @param string $table Table name
1719          * @param string $vars Unused
1720          * @param array|string $conds Filters on the table
1721          * @param string $fname Function name for profiling
1722          * @param array $options Options for select
1723          * @return int Row count
1724          */
1725         public function estimateRowCount( $table, $vars = '*', $conds = '',
1726                 $fname = __METHOD__, $options = array()
1727         ) {
1728                 $rows = 0;
1729                 $res = $this->select( $table, array( 'rowcount' => 'COUNT(*)' ), $conds, $fname, $options );
1730
1731                 if ( $res ) {
1732                         $row = $this->fetchRow( $res );
1733                         $rows = ( isset( $row['rowcount'] ) ) ? $row['rowcount'] : 0;
1734                 }
1735
1736                 return $rows;
1737         }
1738
1739         /**
1740          * Removes most variables from an SQL query and replaces them with X or N for numbers.
1741          * It's only slightly flawed. Don't use for anything important.
1742          *
1743          * @param string $sql A SQL Query
1744          *
1745          * @return string
1746          */
1747         static function generalizeSQL( $sql ) {
1748                 # This does the same as the regexp below would do, but in such a way
1749                 # as to avoid crashing php on some large strings.
1750                 # $sql = preg_replace( "/'([^\\\\']|\\\\.)*'|\"([^\\\\\"]|\\\\.)*\"/", "'X'", $sql );
1751
1752                 $sql = str_replace( "\\\\", '', $sql );
1753                 $sql = str_replace( "\\'", '', $sql );
1754                 $sql = str_replace( "\\\"", '', $sql );
1755                 $sql = preg_replace( "/'.*'/s", "'X'", $sql );
1756                 $sql = preg_replace( '/".*"/s', "'X'", $sql );
1757
1758                 # All newlines, tabs, etc replaced by single space
1759                 $sql = preg_replace( '/\s+/', ' ', $sql );
1760
1761                 # All numbers => N
1762                 $sql = preg_replace( '/-?\d+(,-?\d+)+/s', 'N,...,N', $sql );
1763                 $sql = preg_replace( '/-?\d+/s', 'N', $sql );
1764
1765                 return $sql;
1766         }
1767
1768         /**
1769          * Determines whether a field exists in a table
1770          *
1771          * @param string $table Table name
1772          * @param string $field Filed to check on that table
1773          * @param string $fname Calling function name (optional)
1774          * @return bool Whether $table has filed $field
1775          */
1776         public function fieldExists( $table, $field, $fname = __METHOD__ ) {
1777                 $info = $this->fieldInfo( $table, $field );
1778
1779                 return (bool)$info;
1780         }
1781
1782         /**
1783          * Determines whether an index exists
1784          * Usually throws a DBQueryError on failure
1785          * If errors are explicitly ignored, returns NULL on failure
1786          *
1787          * @param string $table
1788          * @param string $index
1789          * @param string $fname
1790          * @return bool|null
1791          */
1792         public function indexExists( $table, $index, $fname = __METHOD__ ) {
1793                 if ( !$this->tableExists( $table ) ) {
1794                         return null;
1795                 }
1796
1797                 $info = $this->indexInfo( $table, $index, $fname );
1798                 if ( is_null( $info ) ) {
1799                         return null;
1800                 } else {
1801                         return $info !== false;
1802                 }
1803         }
1804
1805         /**
1806          * Query whether a given table exists
1807          *
1808          * @param string $table
1809          * @param string $fname
1810          * @return bool
1811          */
1812         public function tableExists( $table, $fname = __METHOD__ ) {
1813                 $table = $this->tableName( $table );
1814                 $old = $this->ignoreErrors( true );
1815                 $res = $this->query( "SELECT 1 FROM $table LIMIT 1", $fname );
1816                 $this->ignoreErrors( $old );
1817
1818                 return (bool)$res;
1819         }
1820
1821         /**
1822          * Determines if a given index is unique
1823          *
1824          * @param string $table
1825          * @param string $index
1826          *
1827          * @return bool
1828          */
1829         public function indexUnique( $table, $index ) {
1830                 $indexInfo = $this->indexInfo( $table, $index );
1831
1832                 if ( !$indexInfo ) {
1833                         return null;
1834                 }
1835
1836                 return !$indexInfo[0]->Non_unique;
1837         }
1838
1839         /**
1840          * Helper for DatabaseBase::insert().
1841          *
1842          * @param array $options
1843          * @return string
1844          */
1845         protected function makeInsertOptions( $options ) {
1846                 return implode( ' ', $options );
1847         }
1848
1849         /**
1850          * INSERT wrapper, inserts an array into a table.
1851          *
1852          * $a may be either:
1853          *
1854          *   - A single associative array. The array keys are the field names, and
1855          *     the values are the values to insert. The values are treated as data
1856          *     and will be quoted appropriately. If NULL is inserted, this will be
1857          *     converted to a database NULL.
1858          *   - An array with numeric keys, holding a list of associative arrays.
1859          *     This causes a multi-row INSERT on DBMSs that support it. The keys in
1860          *     each subarray must be identical to each other, and in the same order.
1861          *
1862          * Usually throws a DBQueryError on failure. If errors are explicitly ignored,
1863          * returns success.
1864          *
1865          * $options is an array of options, with boolean options encoded as values
1866          * with numeric keys, in the same style as $options in
1867          * DatabaseBase::select(). Supported options are:
1868          *
1869          *   - IGNORE: Boolean: if present, duplicate key errors are ignored, and
1870          *     any rows which cause duplicate key errors are not inserted. It's
1871          *     possible to determine how many rows were successfully inserted using
1872          *     DatabaseBase::affectedRows().
1873          *
1874          * @param string $table Table name. This will be passed through
1875          *   DatabaseBase::tableName().
1876          * @param array $a Array of rows to insert
1877          * @param string $fname Calling function name (use __METHOD__) for logs/profiling
1878          * @param array $options of options
1879          *
1880          * @return bool
1881          */
1882         public function insert( $table, $a, $fname = __METHOD__, $options = array() ) {
1883                 # No rows to insert, easy just return now
1884                 if ( !count( $a ) ) {
1885                         return true;
1886                 }
1887
1888                 $table = $this->tableName( $table );
1889
1890                 if ( !is_array( $options ) ) {
1891                         $options = array( $options );
1892                 }
1893
1894                 $fh = null;
1895                 if ( isset( $options['fileHandle'] ) ) {
1896                         $fh = $options['fileHandle'];
1897                 }
1898                 $options = $this->makeInsertOptions( $options );
1899
1900                 if ( isset( $a[0] ) && is_array( $a[0] ) ) {
1901                         $multi = true;
1902                         $keys = array_keys( $a[0] );
1903                 } else {
1904                         $multi = false;
1905                         $keys = array_keys( $a );
1906                 }
1907
1908                 $sql = 'INSERT ' . $options .
1909                         " INTO $table (" . implode( ',', $keys ) . ') VALUES ';
1910
1911                 if ( $multi ) {
1912                         $first = true;
1913                         foreach ( $a as $row ) {
1914                                 if ( $first ) {
1915                                         $first = false;
1916                                 } else {
1917                                         $sql .= ',';
1918                                 }
1919                                 $sql .= '(' . $this->makeList( $row ) . ')';
1920                         }
1921                 } else {
1922                         $sql .= '(' . $this->makeList( $a ) . ')';
1923                 }
1924
1925                 if ( $fh !== null && false === fwrite( $fh, $sql ) ) {
1926                         return false;
1927                 } elseif ( $fh !== null ) {
1928                         return true;
1929                 }
1930
1931                 return (bool)$this->query( $sql, $fname );
1932         }
1933
1934         /**
1935          * Make UPDATE options array for DatabaseBase::makeUpdateOptions
1936          *
1937          * @param array $options
1938          * @return array
1939          */
1940         protected function makeUpdateOptionsArray( $options ) {
1941                 if ( !is_array( $options ) ) {
1942                         $options = array( $options );
1943                 }
1944
1945                 $opts = array();
1946
1947                 if ( in_array( 'LOW_PRIORITY', $options ) ) {
1948                         $opts[] = $this->lowPriorityOption();
1949                 }
1950
1951                 if ( in_array( 'IGNORE', $options ) ) {
1952                         $opts[] = 'IGNORE';
1953                 }
1954
1955                 return $opts;
1956         }
1957
1958         /**
1959          * Make UPDATE options for the DatabaseBase::update function
1960          *
1961          * @param array $options The options passed to DatabaseBase::update
1962          * @return string
1963          */
1964         protected function makeUpdateOptions( $options ) {
1965                 $opts = $this->makeUpdateOptionsArray( $options );
1966
1967                 return implode( ' ', $opts );
1968         }
1969
1970         /**
1971          * UPDATE wrapper. Takes a condition array and a SET array.
1972          *
1973          * @param string $table Name of the table to UPDATE. This will be passed through
1974          *   DatabaseBase::tableName().
1975          * @param array $values An array of values to SET. For each array element,
1976          *   the key gives the field name, and the value gives the data to set
1977          *   that field to. The data will be quoted by DatabaseBase::addQuotes().
1978          * @param array $conds An array of conditions (WHERE). See
1979          *   DatabaseBase::select() for the details of the format of condition
1980          *   arrays. Use '*' to update all rows.
1981          * @param string $fname The function name of the caller (from __METHOD__),
1982          *   for logging and profiling.
1983          * @param array $options An array of UPDATE options, can be:
1984          *   - IGNORE: Ignore unique key conflicts
1985          *   - LOW_PRIORITY: MySQL-specific, see MySQL manual.
1986          * @return bool
1987          */
1988         function update( $table, $values, $conds, $fname = __METHOD__, $options = array() ) {
1989                 $table = $this->tableName( $table );
1990                 $opts = $this->makeUpdateOptions( $options );
1991                 $sql = "UPDATE $opts $table SET " . $this->makeList( $values, LIST_SET );
1992
1993                 if ( $conds !== array() && $conds !== '*' ) {
1994                         $sql .= " WHERE " . $this->makeList( $conds, LIST_AND );
1995                 }
1996
1997                 return $this->query( $sql, $fname );
1998         }
1999
2000         /**
2001          * Makes an encoded list of strings from an array
2002          *
2003          * @param array $a Containing the data
2004          * @param int $mode Constant
2005          *    - LIST_COMMA: Comma separated, no field names
2006          *    - LIST_AND:   ANDed WHERE clause (without the WHERE). See the
2007          *      documentation for $conds in DatabaseBase::select().
2008          *    - LIST_OR:    ORed WHERE clause (without the WHERE)
2009          *    - LIST_SET:   Comma separated with field names, like a SET clause
2010          *    - LIST_NAMES: Comma separated field names
2011          * @throws MWException|DBUnexpectedError
2012          * @return string
2013          */
2014         public function makeList( $a, $mode = LIST_COMMA ) {
2015                 if ( !is_array( $a ) ) {
2016                         throw new DBUnexpectedError( $this, 'DatabaseBase::makeList called with incorrect parameters' );
2017                 }
2018
2019                 $first = true;
2020                 $list = '';
2021
2022                 foreach ( $a as $field => $value ) {
2023                         if ( !$first ) {
2024                                 if ( $mode == LIST_AND ) {
2025                                         $list .= ' AND ';
2026                                 } elseif ( $mode == LIST_OR ) {
2027                                         $list .= ' OR ';
2028                                 } else {
2029                                         $list .= ',';
2030                                 }
2031                         } else {
2032                                 $first = false;
2033                         }
2034
2035                         if ( ( $mode == LIST_AND || $mode == LIST_OR ) && is_numeric( $field ) ) {
2036                                 $list .= "($value)";
2037                         } elseif ( ( $mode == LIST_SET ) && is_numeric( $field ) ) {
2038                                 $list .= "$value";
2039                         } elseif ( ( $mode == LIST_AND || $mode == LIST_OR ) && is_array( $value ) ) {
2040                                 if ( count( $value ) == 0 ) {
2041                                         throw new MWException( __METHOD__ . ": empty input for field $field" );
2042                                 } elseif ( count( $value ) == 1 ) {
2043                                         // Special-case single values, as IN isn't terribly efficient
2044                                         // Don't necessarily assume the single key is 0; we don't
2045                                         // enforce linear numeric ordering on other arrays here.
2046                                         $value = array_values( $value );
2047                                         $list .= $field . " = " . $this->addQuotes( $value[0] );
2048                                 } else {
2049                                         $list .= $field . " IN (" . $this->makeList( $value ) . ") ";
2050                                 }
2051                         } elseif ( $value === null ) {
2052                                 if ( $mode == LIST_AND || $mode == LIST_OR ) {
2053                                         $list .= "$field IS ";
2054                                 } elseif ( $mode == LIST_SET ) {
2055                                         $list .= "$field = ";
2056                                 }
2057                                 $list .= 'NULL';
2058                         } else {
2059                                 if ( $mode == LIST_AND || $mode == LIST_OR || $mode == LIST_SET ) {
2060                                         $list .= "$field = ";
2061                                 }
2062                                 $list .= $mode == LIST_NAMES ? $value : $this->addQuotes( $value );
2063                         }
2064                 }
2065
2066                 return $list;
2067         }
2068
2069         /**
2070          * Build a partial where clause from a 2-d array such as used for LinkBatch.
2071          * The keys on each level may be either integers or strings.
2072          *
2073          * @param array $data organized as 2-d
2074          *    array(baseKeyVal => array(subKeyVal => [ignored], ...), ...)
2075          * @param string $baseKey Field name to match the base-level keys to (eg 'pl_namespace')
2076          * @param string $subKey Field name to match the sub-level keys to (eg 'pl_title')
2077          * @return string|bool string SQL fragment, or false if no items in array.
2078          */
2079         public function makeWhereFrom2d( $data, $baseKey, $subKey ) {
2080                 $conds = array();
2081
2082                 foreach ( $data as $base => $sub ) {
2083                         if ( count( $sub ) ) {
2084                                 $conds[] = $this->makeList(
2085                                         array( $baseKey => $base, $subKey => array_keys( $sub ) ),
2086                                         LIST_AND );
2087                         }
2088                 }
2089
2090                 if ( $conds ) {
2091                         return $this->makeList( $conds, LIST_OR );
2092                 } else {
2093                         // Nothing to search for...
2094                         return false;
2095                 }
2096         }
2097
2098         /**
2099          * Return aggregated value alias
2100          *
2101          * @param array $valuedata
2102          * @param string $valuename
2103          *
2104          * @return string
2105          */
2106         public function aggregateValue( $valuedata, $valuename = 'value' ) {
2107                 return $valuename;
2108         }
2109
2110         /**
2111          * @param string $field
2112          * @return string
2113          */
2114         public function bitNot( $field ) {
2115                 return "(~$field)";
2116         }
2117
2118         /**
2119          * @param string $fieldLeft
2120          * @param string $fieldRight
2121          * @return string
2122          */
2123         public function bitAnd( $fieldLeft, $fieldRight ) {
2124                 return "($fieldLeft & $fieldRight)";
2125         }
2126
2127         /**
2128          * @param string $fieldLeft
2129          * @param string $fieldRight
2130          * @return string
2131          */
2132         public function bitOr( $fieldLeft, $fieldRight ) {
2133                 return "($fieldLeft | $fieldRight)";
2134         }
2135
2136         /**
2137          * Build a concatenation list to feed into a SQL query
2138          * @param array $stringList List of raw SQL expressions; caller is
2139          *   responsible for any quoting
2140          * @return string
2141          */
2142         public function buildConcat( $stringList ) {
2143                 return 'CONCAT(' . implode( ',', $stringList ) . ')';
2144         }
2145
2146         /**
2147          * Build a GROUP_CONCAT or equivalent statement for a query.
2148          *
2149          * This is useful for combining a field for several rows into a single string.
2150          * NULL values will not appear in the output, duplicated values will appear,
2151          * and the resulting delimiter-separated values have no defined sort order.
2152          * Code using the results may need to use the PHP unique() or sort() methods.
2153          *
2154          * @param string $delim Glue to bind the results together
2155          * @param string|array $table Table name
2156          * @param string $field Field name
2157          * @param string|array $conds Conditions
2158          * @param string|array $join_conds Join conditions
2159          * @return string SQL text
2160          * @since 1.23
2161          */
2162         public function buildGroupConcatField(
2163                 $delim, $table, $field, $conds = '', $join_conds = array()
2164         ) {
2165                 $fld = "GROUP_CONCAT($field SEPARATOR " . $this->addQuotes( $delim ) . ')';
2166
2167                 return '(' . $this->selectSQLText( $table, $fld, $conds, null, array(), $join_conds ) . ')';
2168         }
2169
2170         /**
2171          * Change the current database
2172          *
2173          * @todo Explain what exactly will fail if this is not overridden.
2174          *
2175          * @param string $db
2176          *
2177          * @return bool Success or failure
2178          */
2179         public function selectDB( $db ) {
2180                 # Stub. Shouldn't cause serious problems if it's not overridden, but
2181                 # if your database engine supports a concept similar to MySQL's
2182                 # databases you may as well.
2183                 $this->mDBname = $db;
2184
2185                 return true;
2186         }
2187
2188         /**
2189          * Get the current DB name
2190          * @return string
2191          */
2192         public function getDBname() {
2193                 return $this->mDBname;
2194         }
2195
2196         /**
2197          * Get the server hostname or IP address
2198          * @return string
2199          */
2200         public function getServer() {
2201                 return $this->mServer;
2202         }
2203
2204         /**
2205          * Format a table name ready for use in constructing an SQL query
2206          *
2207          * This does two important things: it quotes the table names to clean them up,
2208          * and it adds a table prefix if only given a table name with no quotes.
2209          *
2210          * All functions of this object which require a table name call this function
2211          * themselves. Pass the canonical name to such functions. This is only needed
2212          * when calling query() directly.
2213          *
2214          * @param string $name Database table name
2215          * @param string $format One of:
2216          *   quoted - Automatically pass the table name through addIdentifierQuotes()
2217          *            so that it can be used in a query.
2218          *   raw - Do not add identifier quotes to the table name
2219          * @return string Full database name
2220          */
2221         public function tableName( $name, $format = 'quoted' ) {
2222                 global $wgSharedDB, $wgSharedPrefix, $wgSharedTables, $wgSharedSchema;
2223                 # Skip the entire process when we have a string quoted on both ends.
2224                 # Note that we check the end so that we will still quote any use of
2225                 # use of `database`.table. But won't break things if someone wants
2226                 # to query a database table with a dot in the name.
2227                 if ( $this->isQuotedIdentifier( $name ) ) {
2228                         return $name;
2229                 }
2230
2231                 # Lets test for any bits of text that should never show up in a table
2232                 # name. Basically anything like JOIN or ON which are actually part of
2233                 # SQL queries, but may end up inside of the table value to combine
2234                 # sql. Such as how the API is doing.
2235                 # Note that we use a whitespace test rather than a \b test to avoid
2236                 # any remote case where a word like on may be inside of a table name
2237                 # surrounded by symbols which may be considered word breaks.
2238                 if ( preg_match( '/(^|\s)(DISTINCT|JOIN|ON|AS)(\s|$)/i', $name ) !== 0 ) {
2239                         return $name;
2240                 }
2241
2242                 # Split database and table into proper variables.
2243                 # We reverse the explode so that database.table and table both output
2244                 # the correct table.
2245                 $dbDetails = explode( '.', $name, 2 );
2246                 if ( count( $dbDetails ) == 3 ) {
2247                         list( $database, $schema, $table ) = $dbDetails;
2248                         # We don't want any prefix added in this case
2249                         $prefix = '';
2250                 } elseif ( count( $dbDetails ) == 2 ) {
2251                         list( $database, $table ) = $dbDetails;
2252                         # We don't want any prefix added in this case
2253                         # In dbs that support it, $database may actually be the schema
2254                         # but that doesn't affect any of the functionality here
2255                         $prefix = '';
2256                         $schema = null;
2257                 } else {
2258                         list( $table ) = $dbDetails;
2259                         if ( $wgSharedDB !== null # We have a shared database
2260                                 && $this->mForeign == false # We're not working on a foreign database
2261                                 && !$this->isQuotedIdentifier( $table ) # Prevent shared tables listing '`table`'
2262                                 && in_array( $table, $wgSharedTables ) # A shared table is selected
2263                         ) {
2264                                 $database = $wgSharedDB;
2265                                 $schema = $wgSharedSchema === null ? $this->mSchema : $wgSharedSchema;
2266                                 $prefix = $wgSharedPrefix === null ? $this->mTablePrefix : $wgSharedPrefix;
2267                         } else {
2268                                 $database = null;
2269                                 $schema = $this->mSchema; # Default schema
2270                                 $prefix = $this->mTablePrefix; # Default prefix
2271                         }
2272                 }
2273
2274                 # Quote $table and apply the prefix if not quoted.
2275                 # $tableName might be empty if this is called from Database::replaceVars()
2276                 $tableName = "{$prefix}{$table}";
2277                 if ( $format == 'quoted' && !$this->isQuotedIdentifier( $tableName ) && $tableName !== '' ) {
2278                         $tableName = $this->addIdentifierQuotes( $tableName );
2279                 }
2280
2281                 # Quote $schema and merge it with the table name if needed
2282                 if ( $schema !== null ) {
2283                         if ( $format == 'quoted' && !$this->isQuotedIdentifier( $schema ) ) {
2284                                 $schema = $this->addIdentifierQuotes( $schema );
2285                         }
2286                         $tableName = $schema . '.' . $tableName;
2287                 }
2288
2289                 # Quote $database and merge it with the table name if needed
2290                 if ( $database !== null ) {
2291                         if ( $format == 'quoted' && !$this->isQuotedIdentifier( $database ) ) {
2292                                 $database = $this->addIdentifierQuotes( $database );
2293                         }
2294                         $tableName = $database . '.' . $tableName;
2295                 }
2296
2297                 return $tableName;
2298         }
2299
2300         /**
2301          * Fetch a number of table names into an array
2302          * This is handy when you need to construct SQL for joins
2303          *
2304          * Example:
2305          * extract( $dbr->tableNames( 'user', 'watchlist' ) );
2306          * $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user
2307          *         WHERE wl_user=user_id AND wl_user=$nameWithQuotes";
2308          *
2309          * @return array
2310          */
2311         public function tableNames() {
2312                 $inArray = func_get_args();
2313                 $retVal = array();
2314
2315                 foreach ( $inArray as $name ) {
2316                         $retVal[$name] = $this->tableName( $name );
2317                 }
2318
2319                 return $retVal;
2320         }
2321
2322         /**
2323          * Fetch a number of table names into an zero-indexed numerical array
2324          * This is handy when you need to construct SQL for joins
2325          *
2326          * Example:
2327          * list( $user, $watchlist ) = $dbr->tableNamesN( 'user', 'watchlist' );
2328          * $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user
2329          *         WHERE wl_user=user_id AND wl_user=$nameWithQuotes";
2330          *
2331          * @return array
2332          */
2333         public function tableNamesN() {
2334                 $inArray = func_get_args();
2335                 $retVal = array();
2336
2337                 foreach ( $inArray as $name ) {
2338                         $retVal[] = $this->tableName( $name );
2339                 }
2340
2341                 return $retVal;
2342         }
2343
2344         /**
2345          * Get an aliased table name
2346          * e.g. tableName AS newTableName
2347          *
2348          * @param string $name Table name, see tableName()
2349          * @param string|bool $alias Alias (optional)
2350          * @return string SQL name for aliased table. Will not alias a table to its own name
2351          */
2352         public function tableNameWithAlias( $name, $alias = false ) {
2353                 if ( !$alias || $alias == $name ) {
2354                         return $this->tableName( $name );
2355                 } else {
2356                         return $this->tableName( $name ) . ' ' . $this->addIdentifierQuotes( $alias );
2357                 }
2358         }
2359
2360         /**
2361          * Gets an array of aliased table names
2362          *
2363          * @param array $tables array( [alias] => table )
2364          * @return string[] See tableNameWithAlias()
2365          */
2366         public function tableNamesWithAlias( $tables ) {
2367                 $retval = array();
2368                 foreach ( $tables as $alias => $table ) {
2369                         if ( is_numeric( $alias ) ) {
2370                                 $alias = $table;
2371                         }
2372                         $retval[] = $this->tableNameWithAlias( $table, $alias );
2373                 }
2374
2375                 return $retval;
2376         }
2377
2378         /**
2379          * Get an aliased field name
2380          * e.g. fieldName AS newFieldName
2381          *
2382          * @param string $name Field name
2383          * @param string|bool $alias Alias (optional)
2384          * @return string SQL name for aliased field. Will not alias a field to its own name
2385          */
2386         public function fieldNameWithAlias( $name, $alias = false ) {
2387                 if ( !$alias || (string)$alias === (string)$name ) {
2388                         return $name;
2389                 } else {
2390                         return $name . ' AS ' . $alias; //PostgreSQL needs AS
2391                 }
2392         }
2393
2394         /**
2395          * Gets an array of aliased field names
2396          *
2397          * @param array $fields array( [alias] => field )
2398          * @return string[] See fieldNameWithAlias()
2399          */
2400         public function fieldNamesWithAlias( $fields ) {
2401                 $retval = array();
2402                 foreach ( $fields as $alias => $field ) {
2403                         if ( is_numeric( $alias ) ) {
2404                                 $alias = $field;
2405                         }
2406                         $retval[] = $this->fieldNameWithAlias( $field, $alias );
2407                 }
2408
2409                 return $retval;
2410         }
2411
2412         /**
2413          * Get the aliased table name clause for a FROM clause
2414          * which might have a JOIN and/or USE INDEX clause
2415          *
2416          * @param array $tables ( [alias] => table )
2417          * @param array $use_index Same as for select()
2418          * @param array $join_conds Same as for select()
2419          * @return string
2420          */
2421         protected function tableNamesWithUseIndexOrJOIN(
2422                 $tables, $use_index = array(), $join_conds = array()
2423         ) {
2424                 $ret = array();
2425                 $retJOIN = array();
2426                 $use_index = (array)$use_index;
2427                 $join_conds = (array)$join_conds;
2428
2429                 foreach ( $tables as $alias => $table ) {
2430                         if ( !is_string( $alias ) ) {
2431                                 // No alias? Set it equal to the table name
2432                                 $alias = $table;
2433                         }
2434                         // Is there a JOIN clause for this table?
2435                         if ( isset( $join_conds[$alias] ) ) {
2436                                 list( $joinType, $conds ) = $join_conds[$alias];
2437                                 $tableClause = $joinType;
2438                                 $tableClause .= ' ' . $this->tableNameWithAlias( $table, $alias );
2439                                 if ( isset( $use_index[$alias] ) ) { // has USE INDEX?
2440                                         $use = $this->useIndexClause( implode( ',', (array)$use_index[$alias] ) );
2441                                         if ( $use != '' ) {
2442                                                 $tableClause .= ' ' . $use;
2443                                         }
2444                                 }
2445                                 $on = $this->makeList( (array)$conds, LIST_AND );
2446                                 if ( $on != '' ) {
2447                                         $tableClause .= ' ON (' . $on . ')';
2448                                 }
2449
2450                                 $retJOIN[] = $tableClause;
2451                         } elseif ( isset( $use_index[$alias] ) ) {
2452                                 // Is there an INDEX clause for this table?
2453                                 $tableClause = $this->tableNameWithAlias( $table, $alias );
2454                                 $tableClause .= ' ' . $this->useIndexClause(
2455                                         implode( ',', (array)$use_index[$alias] )
2456                                 );
2457
2458                                 $ret[] = $tableClause;
2459                         } else {
2460                                 $tableClause = $this->tableNameWithAlias( $table, $alias );
2461
2462                                 $ret[] = $tableClause;
2463                         }
2464                 }
2465
2466                 // We can't separate explicit JOIN clauses with ',', use ' ' for those
2467                 $implicitJoins = !empty( $ret ) ? implode( ',', $ret ) : "";
2468                 $explicitJoins = !empty( $retJOIN ) ? implode( ' ', $retJOIN ) : "";
2469
2470                 // Compile our final table clause
2471                 return implode( ' ', array( $implicitJoins, $explicitJoins ) );
2472         }
2473
2474         /**
2475          * Get the name of an index in a given table
2476          *
2477          * @param string $index
2478          * @return string
2479          */
2480         protected function indexName( $index ) {
2481                 // Backwards-compatibility hack
2482                 $renamed = array(
2483                         'ar_usertext_timestamp' => 'usertext_timestamp',
2484                         'un_user_id' => 'user_id',
2485                         'un_user_ip' => 'user_ip',
2486                 );
2487
2488                 if ( isset( $renamed[$index] ) ) {
2489                         return $renamed[$index];
2490                 } else {
2491                         return $index;
2492                 }
2493         }
2494
2495         /**
2496          * Adds quotes and backslashes.
2497          *
2498          * @param string $s
2499          * @return string
2500          */
2501         public function addQuotes( $s ) {
2502                 if ( $s === null ) {
2503                         return 'NULL';
2504                 } else {
2505                         # This will also quote numeric values. This should be harmless,
2506                         # and protects against weird problems that occur when they really
2507                         # _are_ strings such as article titles and string->number->string
2508                         # conversion is not 1:1.
2509                         return "'" . $this->strencode( $s ) . "'";
2510                 }
2511         }
2512
2513         /**
2514          * Quotes an identifier using `backticks` or "double quotes" depending on the database type.
2515          * MySQL uses `backticks` while basically everything else uses double quotes.
2516          * Since MySQL is the odd one out here the double quotes are our generic
2517          * and we implement backticks in DatabaseMysql.
2518          *
2519          * @param string $s
2520          * @return string
2521          */
2522         public function addIdentifierQuotes( $s ) {
2523                 return '"' . str_replace( '"', '""', $s ) . '"';
2524         }
2525
2526         /**
2527          * Returns if the given identifier looks quoted or not according to
2528          * the database convention for quoting identifiers .
2529          *
2530          * @param string $name
2531          * @return bool
2532          */
2533         public function isQuotedIdentifier( $name ) {
2534                 return $name[0] == '"' && substr( $name, -1, 1 ) == '"';
2535         }
2536
2537         /**
2538          * @param string $s
2539          * @return string
2540          */
2541         protected function escapeLikeInternal( $s ) {
2542                 return addcslashes( $s, '\%_' );
2543         }
2544
2545         /**
2546          * LIKE statement wrapper, receives a variable-length argument list with
2547          * parts of pattern to match containing either string literals that will be
2548          * escaped or tokens returned by anyChar() or anyString(). Alternatively,
2549          * the function could be provided with an array of aforementioned
2550          * parameters.
2551          *
2552          * Example: $dbr->buildLike( 'My_page_title/', $dbr->anyString() ) returns
2553          * a LIKE clause that searches for subpages of 'My page title'.
2554          * Alternatively:
2555          *   $pattern = array( 'My_page_title/', $dbr->anyString() );
2556          *   $query .= $dbr->buildLike( $pattern );
2557          *
2558          * @since 1.16
2559          * @return string Fully built LIKE statement
2560          */
2561         public function buildLike() {
2562                 $params = func_get_args();
2563
2564                 if ( count( $params ) > 0 && is_array( $params[0] ) ) {
2565                         $params = $params[0];
2566                 }
2567
2568                 $s = '';
2569
2570                 foreach ( $params as $value ) {
2571                         if ( $value instanceof LikeMatch ) {
2572                                 $s .= $value->toString();
2573                         } else {
2574                                 $s .= $this->escapeLikeInternal( $value );
2575                         }
2576                 }
2577
2578                 return " LIKE {$this->addQuotes( $s )} ";
2579         }
2580
2581         /**
2582          * Returns a token for buildLike() that denotes a '_' to be used in a LIKE query
2583          *
2584          * @return LikeMatch
2585          */
2586         public function anyChar() {
2587                 return new LikeMatch( '_' );
2588         }
2589
2590         /**
2591          * Returns a token for buildLike() that denotes a '%' to be used in a LIKE query
2592          *
2593          * @return LikeMatch
2594          */
2595         public function anyString() {
2596                 return new LikeMatch( '%' );
2597         }
2598
2599         /**
2600          * Returns an appropriately quoted sequence value for inserting a new row.
2601          * MySQL has autoincrement fields, so this is just NULL. But the PostgreSQL
2602          * subclass will return an integer, and save the value for insertId()
2603          *
2604          * Any implementation of this function should *not* involve reusing
2605          * sequence numbers created for rolled-back transactions.
2606          * See http://bugs.mysql.com/bug.php?id=30767 for details.
2607          * @param string $seqName
2608          * @return null|int
2609          */
2610         public function nextSequenceValue( $seqName ) {
2611                 return null;
2612         }
2613
2614         /**
2615          * USE INDEX clause. Unlikely to be useful for anything but MySQL. This
2616          * is only needed because a) MySQL must be as efficient as possible due to
2617          * its use on Wikipedia, and b) MySQL 4.0 is kind of dumb sometimes about
2618          * which index to pick. Anyway, other databases might have different
2619          * indexes on a given table. So don't bother overriding this unless you're
2620          * MySQL.
2621          * @param string $index
2622          * @return string
2623          */
2624         public function useIndexClause( $index ) {
2625                 return '';
2626         }
2627
2628         /**
2629          * REPLACE query wrapper.
2630          *
2631          * REPLACE is a very handy MySQL extension, which functions like an INSERT
2632          * except that when there is a duplicate key error, the old row is deleted
2633          * and the new row is inserted in its place.
2634          *
2635          * We simulate this with standard SQL with a DELETE followed by INSERT. To
2636          * perform the delete, we need to know what the unique indexes are so that
2637          * we know how to find the conflicting rows.
2638          *
2639          * It may be more efficient to leave off unique indexes which are unlikely
2640          * to collide. However if you do this, you run the risk of encountering
2641          * errors which wouldn't have occurred in MySQL.
2642          *
2643          * @param string $table The table to replace the row(s) in.
2644          * @param array $uniqueIndexes Is an array of indexes. Each element may be either
2645          *    a field name or an array of field names
2646          * @param array $rows Can be either a single row to insert, or multiple rows,
2647          *    in the same format as for DatabaseBase::insert()
2648          * @param string $fname Calling function name (use __METHOD__) for logs/profiling
2649          */
2650         public function replace( $table, $uniqueIndexes, $rows, $fname = __METHOD__ ) {
2651                 $quotedTable = $this->tableName( $table );
2652
2653                 if ( count( $rows ) == 0 ) {
2654                         return;
2655                 }
2656
2657                 # Single row case
2658                 if ( !is_array( reset( $rows ) ) ) {
2659                         $rows = array( $rows );
2660                 }
2661
2662                 foreach ( $rows as $row ) {
2663                         # Delete rows which collide
2664                         if ( $uniqueIndexes ) {
2665                                 $sql = "DELETE FROM $quotedTable WHERE ";
2666                                 $first = true;
2667                                 foreach ( $uniqueIndexes as $index ) {
2668                                         if ( $first ) {
2669                                                 $first = false;
2670                                                 $sql .= '( ';
2671                                         } else {
2672                                                 $sql .= ' ) OR ( ';
2673                                         }
2674                                         if ( is_array( $index ) ) {
2675                                                 $first2 = true;
2676                                                 foreach ( $index as $col ) {
2677                                                         if ( $first2 ) {
2678                                                                 $first2 = false;
2679                                                         } else {
2680                                                                 $sql .= ' AND ';
2681                                                         }
2682                                                         $sql .= $col . '=' . $this->addQuotes( $row[$col] );
2683                                                 }
2684                                         } else {
2685                                                 $sql .= $index . '=' . $this->addQuotes( $row[$index] );
2686                                         }
2687                                 }
2688                                 $sql .= ' )';
2689                                 $this->query( $sql, $fname );
2690                         }
2691
2692                         # Now insert the row
2693                         $this->insert( $table, $row, $fname );
2694                 }
2695         }
2696
2697         /**
2698          * REPLACE query wrapper for MySQL and SQLite, which have a native REPLACE
2699          * statement.
2700          *
2701          * @param string $table Table name
2702          * @param array|string $rows Row(s) to insert
2703          * @param string $fname Caller function name
2704          *
2705          * @return ResultWrapper
2706          */
2707         protected function nativeReplace( $table, $rows, $fname ) {
2708                 $table = $this->tableName( $table );
2709
2710                 # Single row case
2711                 if ( !is_array( reset( $rows ) ) ) {
2712                         $rows = array( $rows );
2713                 }
2714
2715                 $sql = "REPLACE INTO $table (" . implode( ',', array_keys( $rows[0] ) ) . ') VALUES ';
2716                 $first = true;
2717
2718                 foreach ( $rows as $row ) {
2719                         if ( $first ) {
2720                                 $first = false;
2721                         } else {
2722                                 $sql .= ',';
2723                         }
2724
2725                         $sql .= '(' . $this->makeList( $row ) . ')';
2726                 }
2727
2728                 return $this->query( $sql, $fname );
2729         }
2730
2731         /**
2732          * INSERT ON DUPLICATE KEY UPDATE wrapper, upserts an array into a table.
2733          *
2734          * This updates any conflicting rows (according to the unique indexes) using
2735          * the provided SET clause and inserts any remaining (non-conflicted) rows.
2736          *
2737          * $rows may be either:
2738          *   - A single associative array. The array keys are the field names, and
2739          *     the values are the values to insert. The values are treated as data
2740          *     and will be quoted appropriately. If NULL is inserted, this will be
2741          *     converted to a database NULL.
2742          *   - An array with numeric keys, holding a list of associative arrays.
2743          *     This causes a multi-row INSERT on DBMSs that support it. The keys in
2744          *     each subarray must be identical to each other, and in the same order.
2745          *
2746          * It may be more efficient to leave off unique indexes which are unlikely
2747          * to collide. However if you do this, you run the risk of encountering
2748          * errors which wouldn't have occurred in MySQL.
2749          *
2750          * Usually throws a DBQueryError on failure. If errors are explicitly ignored,
2751          * returns success.
2752          *
2753          * @since 1.22
2754          *
2755          * @param string $table Table name. This will be passed through DatabaseBase::tableName().
2756          * @param array $rows A single row or list of rows to insert
2757          * @param array $uniqueIndexes List of single field names or field name tuples
2758          * @param array $set An array of values to SET. For each array element, the
2759          *   key gives the field name, and the value gives the data to set that
2760          *   field to. The data will be quoted by DatabaseBase::addQuotes().
2761          * @param string $fname Calling function name (use __METHOD__) for logs/profiling
2762          * @throws Exception
2763          * @return bool
2764          */
2765         public function upsert( $table, array $rows, array $uniqueIndexes, array $set,
2766                 $fname = __METHOD__
2767         ) {
2768                 if ( !count( $rows ) ) {
2769                         return true; // nothing to do
2770                 }
2771
2772                 if ( !is_array( reset( $rows ) ) ) {
2773                         $rows = array( $rows );
2774                 }
2775
2776                 if ( count( $uniqueIndexes ) ) {
2777                         $clauses = array(); // list WHERE clauses that each identify a single row
2778                         foreach ( $rows as $row ) {
2779                                 foreach ( $uniqueIndexes as $index ) {
2780                                         $index = is_array( $index ) ? $index : array( $index ); // columns
2781                                         $rowKey = array(); // unique key to this row
2782                                         foreach ( $index as $column ) {
2783                                                 $rowKey[$column] = $row[$column];
2784                                         }
2785                                         $clauses[] = $this->makeList( $rowKey, LIST_AND );
2786                                 }
2787                         }
2788                         $where = array( $this->makeList( $clauses, LIST_OR ) );
2789                 } else {
2790                         $where = false;
2791                 }
2792
2793                 $useTrx = !$this->mTrxLevel;
2794                 if ( $useTrx ) {
2795                         $this->begin( $fname );
2796                 }
2797                 try {
2798                         # Update any existing conflicting row(s)
2799                         if ( $where !== false ) {
2800                                 $ok = $this->update( $table, $set, $where, $fname );
2801                         } else {
2802                                 $ok = true;
2803                         }
2804                         # Now insert any non-conflicting row(s)
2805                         $ok = $this->insert( $table, $rows, $fname, array( 'IGNORE' ) ) && $ok;
2806                 } catch ( Exception $e ) {
2807                         if ( $useTrx ) {
2808                                 $this->rollback( $fname );
2809                         }
2810                         throw $e;
2811                 }
2812                 if ( $useTrx ) {
2813                         $this->commit( $fname );
2814                 }
2815
2816                 return $ok;
2817         }
2818
2819         /**
2820          * DELETE where the condition is a join.
2821          *
2822          * MySQL overrides this to use a multi-table DELETE syntax, in other databases
2823          * we use sub-selects
2824          *
2825          * For safety, an empty $conds will not delete everything. If you want to
2826          * delete all rows where the join condition matches, set $conds='*'.
2827          *
2828          * DO NOT put the join condition in $conds.
2829          *
2830          * @param string $delTable The table to delete from.
2831          * @param string $joinTable The other table.
2832          * @param string $delVar The variable to join on, in the first table.
2833          * @param string $joinVar The variable to join on, in the second table.
2834          * @param array $conds Condition array of field names mapped to variables,
2835          *   ANDed together in the WHERE clause
2836          * @param string $fname Calling function name (use __METHOD__) for logs/profiling
2837          * @throws DBUnexpectedError
2838          */
2839         public function deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds,
2840                 $fname = __METHOD__
2841         ) {
2842                 if ( !$conds ) {
2843                         throw new DBUnexpectedError( $this,
2844                                 'DatabaseBase::deleteJoin() called with empty $conds' );
2845                 }
2846
2847                 $delTable = $this->tableName( $delTable );
2848                 $joinTable = $this->tableName( $joinTable );
2849                 $sql = "DELETE FROM $delTable WHERE $delVar IN (SELECT $joinVar FROM $joinTable ";
2850                 if ( $conds != '*' ) {
2851                         $sql .= 'WHERE ' . $this->makeList( $conds, LIST_AND );
2852                 }
2853                 $sql .= ')';
2854
2855                 $this->query( $sql, $fname );
2856         }
2857
2858         /**
2859          * Returns the size of a text field, or -1 for "unlimited"
2860          *
2861          * @param string $table
2862          * @param string $field
2863          * @return int
2864          */
2865         public function textFieldSize( $table, $field ) {
2866                 $table = $this->tableName( $table );
2867                 $sql = "SHOW COLUMNS FROM $table LIKE \"$field\";";
2868                 $res = $this->query( $sql, 'DatabaseBase::textFieldSize' );
2869                 $row = $this->fetchObject( $res );
2870
2871                 $m = array();
2872
2873                 if ( preg_match( '/\((.*)\)/', $row->Type, $m ) ) {
2874                         $size = $m[1];
2875                 } else {
2876                         $size = -1;
2877                 }
2878
2879                 return $size;
2880         }
2881
2882         /**
2883          * A string to insert into queries to show that they're low-priority, like
2884          * MySQL's LOW_PRIORITY. If no such feature exists, return an empty
2885          * string and nothing bad should happen.
2886          *
2887          * @return string Returns the text of the low priority option if it is
2888          *   supported, or a blank string otherwise
2889          */
2890         public function lowPriorityOption() {
2891                 return '';
2892         }
2893
2894         /**
2895          * DELETE query wrapper.
2896          *
2897          * @param array $table Table name
2898          * @param string|array $conds of conditions. See $conds in DatabaseBase::select()
2899          *   for the format. Use $conds == "*" to delete all rows
2900          * @param string $fname name of the calling function
2901          * @throws DBUnexpectedError
2902          * @return bool|ResultWrapper
2903          */
2904         public function delete( $table, $conds, $fname = __METHOD__ ) {
2905                 if ( !$conds ) {
2906                         throw new DBUnexpectedError( $this, 'DatabaseBase::delete() called with no conditions' );
2907                 }
2908
2909                 $table = $this->tableName( $table );
2910                 $sql = "DELETE FROM $table";
2911
2912                 if ( $conds != '*' ) {
2913                         if ( is_array( $conds ) ) {
2914                                 $conds = $this->makeList( $conds, LIST_AND );
2915                         }
2916                         $sql .= ' WHERE ' . $conds;
2917                 }
2918
2919                 return $this->query( $sql, $fname );
2920         }
2921
2922         /**
2923          * INSERT SELECT wrapper. Takes data from a SELECT query and inserts it
2924          * into another table.
2925          *
2926          * @param string $destTable The table name to insert into
2927          * @param string|array $srcTable May be either a table name, or an array of table names
2928          *    to include in a join.
2929          *
2930          * @param array $varMap Must be an associative array of the form
2931          *    array( 'dest1' => 'source1', ...). Source items may be literals
2932          *    rather than field names, but strings should be quoted with
2933          *    DatabaseBase::addQuotes()
2934          *
2935          * @param array $conds Condition array. See $conds in DatabaseBase::select() for
2936          *    the details of the format of condition arrays. May be "*" to copy the
2937          *    whole table.
2938          *
2939          * @param string $fname The function name of the caller, from __METHOD__
2940          *
2941          * @param array $insertOptions Options for the INSERT part of the query, see
2942          *    DatabaseBase::insert() for details.
2943          * @param array $selectOptions Options for the SELECT part of the query, see
2944          *    DatabaseBase::select() for details.
2945          *
2946          * @return ResultWrapper
2947          */
2948         public function insertSelect( $destTable, $srcTable, $varMap, $conds,
2949                 $fname = __METHOD__,
2950                 $insertOptions = array(), $selectOptions = array()
2951         ) {
2952                 $destTable = $this->tableName( $destTable );
2953
2954                 if ( !is_array( $insertOptions ) ) {
2955                         $insertOptions = array( $insertOptions );
2956                 }
2957
2958                 $insertOptions = $this->makeInsertOptions( $insertOptions );
2959
2960                 if ( !is_array( $selectOptions ) ) {
2961                         $selectOptions = array( $selectOptions );
2962                 }
2963
2964                 list( $startOpts, $useIndex, $tailOpts ) = $this->makeSelectOptions( $selectOptions );
2965
2966                 if ( is_array( $srcTable ) ) {
2967                         $srcTable = implode( ',', array_map( array( &$this, 'tableName' ), $srcTable ) );
2968                 } else {
2969                         $srcTable = $this->tableName( $srcTable );
2970                 }
2971
2972                 $sql = "INSERT $insertOptions INTO $destTable (" . implode( ',', array_keys( $varMap ) ) . ')' .
2973                         " SELECT $startOpts " . implode( ',', $varMap ) .
2974                         " FROM $srcTable $useIndex ";
2975
2976                 if ( $conds != '*' ) {
2977                         if ( is_array( $conds ) ) {
2978                                 $conds = $this->makeList( $conds, LIST_AND );
2979                         }
2980                         $sql .= " WHERE $conds";
2981                 }
2982
2983                 $sql .= " $tailOpts";
2984
2985                 return $this->query( $sql, $fname );
2986         }
2987
2988         /**
2989          * Construct a LIMIT query with optional offset. This is used for query
2990          * pages. The SQL should be adjusted so that only the first $limit rows
2991          * are returned. If $offset is provided as well, then the first $offset
2992          * rows should be discarded, and the next $limit rows should be returned.
2993          * If the result of the query is not ordered, then the rows to be returned
2994          * are theoretically arbitrary.
2995          *
2996          * $sql is expected to be a SELECT, if that makes a difference.
2997          *
2998          * The version provided by default works in MySQL and SQLite. It will very
2999          * likely need to be overridden for most other DBMSes.
3000          *
3001          * @param string $sql SQL query we will append the limit too
3002          * @param int $limit The SQL limit
3003          * @param int|bool $offset The SQL offset (default false)
3004          * @throws DBUnexpectedError
3005          * @return string
3006          */
3007         public function limitResult( $sql, $limit, $offset = false ) {
3008                 if ( !is_numeric( $limit ) ) {
3009                         throw new DBUnexpectedError( $this, "Invalid non-numeric limit passed to limitResult()\n" );
3010                 }
3011
3012                 return "$sql LIMIT "
3013                         . ( ( is_numeric( $offset ) && $offset != 0 ) ? "{$offset}," : "" )
3014                         . "{$limit} ";
3015         }
3016
3017         /**
3018          * Returns true if current database backend supports ORDER BY or LIMIT for separate subqueries
3019          * within the UNION construct.
3020          * @return bool
3021          */
3022         public function unionSupportsOrderAndLimit() {
3023                 return true; // True for almost every DB supported
3024         }
3025
3026         /**
3027          * Construct a UNION query
3028          * This is used for providing overload point for other DB abstractions
3029          * not compatible with the MySQL syntax.
3030          * @param array $sqls SQL statements to combine
3031          * @param bool $all Use UNION ALL
3032          * @return string SQL fragment
3033          */
3034         public function unionQueries( $sqls, $all ) {
3035                 $glue = $all ? ') UNION ALL (' : ') UNION (';
3036
3037                 return '(' . implode( $glue, $sqls ) . ')';
3038         }
3039
3040         /**
3041          * Returns an SQL expression for a simple conditional. This doesn't need
3042          * to be overridden unless CASE isn't supported in your DBMS.
3043          *
3044          * @param string|array $cond SQL expression which will result in a boolean value
3045          * @param string $trueVal SQL expression to return if true
3046          * @param string $falseVal SQL expression to return if false
3047          * @return string SQL fragment
3048          */
3049         public function conditional( $cond, $trueVal, $falseVal ) {
3050                 if ( is_array( $cond ) ) {
3051                         $cond = $this->makeList( $cond, LIST_AND );
3052                 }
3053
3054                 return " (CASE WHEN $cond THEN $trueVal ELSE $falseVal END) ";
3055         }
3056
3057         /**
3058          * Returns a comand for str_replace function in SQL query.
3059          * Uses REPLACE() in MySQL
3060          *
3061          * @param string $orig Column to modify
3062          * @param string $old Column to seek
3063          * @param string $new Column to replace with
3064          *
3065          * @return string
3066          */
3067         public function strreplace( $orig, $old, $new ) {
3068                 return "REPLACE({$orig}, {$old}, {$new})";
3069         }
3070
3071         /**
3072          * Determines how long the server has been up
3073          * STUB
3074          *
3075          * @return int
3076          */
3077         public function getServerUptime() {
3078                 return 0;
3079         }
3080
3081         /**
3082          * Determines if the last failure was due to a deadlock
3083          * STUB
3084          *
3085          * @return bool
3086          */
3087         public function wasDeadlock() {
3088                 return false;
3089         }
3090
3091         /**
3092          * Determines if the last failure was due to a lock timeout
3093          * STUB
3094          *
3095          * @return bool
3096          */
3097         public function wasLockTimeout() {
3098                 return false;
3099         }
3100
3101         /**
3102          * Determines if the last query error was something that should be dealt
3103          * with by pinging the connection and reissuing the query.
3104          * STUB
3105          *
3106          * @return bool
3107          */
3108         public function wasErrorReissuable() {
3109                 return false;
3110         }
3111
3112         /**
3113          * Determines if the last failure was due to the database being read-only.
3114          * STUB
3115          *
3116          * @return bool
3117          */
3118         public function wasReadOnlyError() {
3119                 return false;
3120         }
3121
3122         /**
3123          * Perform a deadlock-prone transaction.
3124          *
3125          * This function invokes a callback function to perform a set of write
3126          * queries. If a deadlock occurs during the processing, the transaction
3127          * will be rolled back and the callback function will be called again.
3128          *
3129          * Usage:
3130          *   $dbw->deadlockLoop( callback, ... );
3131          *
3132          * Extra arguments are passed through to the specified callback function.
3133          *
3134          * Returns whatever the callback function returned on its successful,
3135          * iteration, or false on error, for example if the retry limit was
3136          * reached.
3137          *
3138          * @return bool
3139          */
3140         public function deadlockLoop() {
3141                 $this->begin( __METHOD__ );
3142                 $args = func_get_args();
3143                 $function = array_shift( $args );
3144                 $oldIgnore = $this->ignoreErrors( true );
3145                 $tries = self::DEADLOCK_TRIES;
3146
3147                 if ( is_array( $function ) ) {
3148                         $fname = $function[0];
3149                 } else {
3150                         $fname = $function;
3151                 }
3152
3153                 do {
3154                         $retVal = call_user_func_array( $function, $args );
3155                         $error = $this->lastError();
3156                         $errno = $this->lastErrno();
3157                         $sql = $this->lastQuery();
3158
3159                         if ( $errno ) {
3160                                 if ( $this->wasDeadlock() ) {
3161                                         # Retry
3162                                         usleep( mt_rand( self::DEADLOCK_DELAY_MIN, self::DEADLOCK_DELAY_MAX ) );
3163                                 } else {
3164                                         $this->reportQueryError( $error, $errno, $sql, $fname );
3165                                 }
3166                         }
3167                 } while ( $this->wasDeadlock() && --$tries > 0 );
3168
3169                 $this->ignoreErrors( $oldIgnore );
3170
3171                 if ( $tries <= 0 ) {
3172                         $this->rollback( __METHOD__ );
3173                         $this->reportQueryError( $error, $errno, $sql, $fname );
3174
3175                         return false;
3176                 } else {
3177                         $this->commit( __METHOD__ );
3178
3179                         return $retVal;
3180                 }
3181         }
3182
3183         /**
3184          * Wait for the slave to catch up to a given master position.
3185          *
3186          * @param DBMasterPos $pos
3187          * @param int $timeout The maximum number of seconds to wait for
3188          *   synchronisation
3189          * @return int Zzero if the slave was past that position already,
3190          *   greater than zero if we waited for some period of time, less than
3191          *   zero if we timed out.
3192          */
3193         public function masterPosWait( DBMasterPos $pos, $timeout ) {
3194                 # Real waits are implemented in the subclass.
3195                 return 0;
3196         }
3197
3198         /**
3199          * Get the replication position of this slave
3200          *
3201          * @return DBMasterPos|bool False if this is not a slave.
3202          */
3203         public function getSlavePos() {
3204                 # Stub
3205                 return false;
3206         }
3207
3208         /**
3209          * Get the position of this master
3210          *
3211          * @return DBMasterPos|bool False if this is not a master
3212          */
3213         public function getMasterPos() {
3214                 # Stub
3215                 return false;
3216         }
3217
3218         /**
3219          * Run an anonymous function as soon as there is no transaction pending.
3220          * If there is a transaction and it is rolled back, then the callback is cancelled.
3221          * Queries in the function will run in AUTO-COMMIT mode unless there are begin() calls.
3222          * Callbacks must commit any transactions that they begin.
3223          *
3224          * This is useful for updates to different systems or when separate transactions are needed.
3225          * For example, one might want to enqueue jobs into a system outside the database, but only
3226          * after the database is updated so that the jobs will see the data when they actually run.
3227          * It can also be used for updates that easily cause deadlocks if locks are held too long.
3228          *
3229          * @param callable $callback
3230          * @since 1.20
3231          */
3232         final public function onTransactionIdle( $callback ) {
3233                 $this->mTrxIdleCallbacks[] = array( $callback, wfGetCaller() );
3234                 if ( !$this->mTrxLevel ) {
3235                         $this->runOnTransactionIdleCallbacks();
3236                 }
3237         }
3238
3239         /**
3240          * Run an anonymous function before the current transaction commits or now if there is none.
3241          * If there is a transaction and it is rolled back, then the callback is cancelled.
3242          * Callbacks must not start nor commit any transactions.
3243          *
3244          * This is useful for updates that easily cause deadlocks if locks are held too long
3245          * but where atomicity is strongly desired for these updates and some related updates.
3246          *
3247          * @param callable $callback
3248          * @since 1.22
3249          */
3250         final public function onTransactionPreCommitOrIdle( $callback ) {
3251                 if ( $this->mTrxLevel ) {
3252                         $this->mTrxPreCommitCallbacks[] = array( $callback, wfGetCaller() );
3253                 } else {
3254                         $this->onTransactionIdle( $callback ); // this will trigger immediately
3255                 }
3256         }
3257
3258         /**
3259          * Actually any "on transaction idle" callbacks.
3260          *
3261          * @since 1.20
3262          */
3263         protected function runOnTransactionIdleCallbacks() {
3264                 $autoTrx = $this->getFlag( DBO_TRX ); // automatic begin() enabled?
3265
3266                 $e = null; // last exception
3267                 do { // callbacks may add callbacks :)
3268                         $callbacks = $this->mTrxIdleCallbacks;
3269                         $this->mTrxIdleCallbacks = array(); // recursion guard
3270                         foreach ( $callbacks as $callback ) {
3271                                 try {
3272                                         list( $phpCallback ) = $callback;
3273                                         $this->clearFlag( DBO_TRX ); // make each query its own transaction
3274                                         call_user_func( $phpCallback );
3275                                         $this->setFlag( $autoTrx ? DBO_TRX : 0 ); // restore automatic begin()
3276                                 } catch ( Exception $e ) {
3277                                 }
3278                         }
3279                 } while ( count( $this->mTrxIdleCallbacks ) );
3280
3281                 if ( $e instanceof Exception ) {
3282                         throw $e; // re-throw any last exception
3283                 }
3284         }
3285
3286         /**
3287          * Actually any "on transaction pre-commit" callbacks.
3288          *
3289          * @since 1.22
3290          */
3291         protected function runOnTransactionPreCommitCallbacks() {
3292                 $e = null; // last exception
3293                 do { // callbacks may add callbacks :)
3294                         $callbacks = $this->mTrxPreCommitCallbacks;
3295                         $this->mTrxPreCommitCallbacks = array(); // recursion guard
3296                         foreach ( $callbacks as $callback ) {
3297                                 try {
3298                                         list( $phpCallback ) = $callback;
3299                                         call_user_func( $phpCallback );
3300                                 } catch ( Exception $e ) {
3301                                 }
3302                         }
3303                 } while ( count( $this->mTrxPreCommitCallbacks ) );
3304
3305                 if ( $e instanceof Exception ) {
3306                         throw $e; // re-throw any last exception
3307                 }
3308         }
3309
3310         /**
3311          * Begin an atomic section of statements
3312          *
3313          * If a transaction has been started already, just keep track of the given
3314          * section name to make sure the transaction is not committed pre-maturely.
3315          * This function can be used in layers (with sub-sections), so use a stack
3316          * to keep track of the different atomic sections. If there is no transaction,
3317          * start one implicitly.
3318          *
3319          * The goal of this function is to create an atomic section of SQL queries
3320          * without having to start a new transaction if it already exists.
3321          *
3322          * Atomic sections are more strict than transactions. With transactions,
3323          * attempting to begin a new transaction when one is already running results
3324          * in MediaWiki issuing a brief warning and doing an implicit commit. All
3325          * atomic levels *must* be explicitly closed using DatabaseBase::endAtomic(),
3326          * and any database transactions cannot be began or committed until all atomic
3327          * levels are closed. There is no such thing as implicitly opening or closing
3328          * an atomic section.
3329          *
3330          * @since 1.23
3331          * @param string $fname
3332          * @throws DBError
3333          */
3334         final public function startAtomic( $fname = __METHOD__ ) {
3335                 if ( !$this->mTrxLevel ) {
3336                         $this->begin( $fname );
3337                         $this->mTrxAutomatic = true;
3338                         $this->mTrxAutomaticAtomic = true;
3339                 }
3340
3341                 $this->mTrxAtomicLevels->push( $fname );
3342         }
3343
3344         /**
3345          * Ends an atomic section of SQL statements
3346          *
3347          * Ends the next section of atomic SQL statements and commits the transaction
3348          * if necessary.
3349          *
3350          * @since 1.23
3351          * @see DatabaseBase::startAtomic
3352          * @param string $fname
3353          * @throws DBError
3354          */
3355         final public function endAtomic( $fname = __METHOD__ ) {
3356                 if ( !$this->mTrxLevel ) {
3357                         throw new DBUnexpectedError( $this, 'No atomic transaction is open.' );
3358                 }
3359                 if ( $this->mTrxAtomicLevels->isEmpty() ||
3360                         $this->mTrxAtomicLevels->pop() !== $fname
3361                 ) {
3362                         throw new DBUnexpectedError( $this, 'Invalid atomic section ended.' );
3363                 }
3364
3365                 if ( $this->mTrxAtomicLevels->isEmpty() && $this->mTrxAutomaticAtomic ) {
3366                         $this->commit( $fname, 'flush' );
3367                 }
3368         }
3369
3370         /**
3371          * Begin a transaction. If a transaction is already in progress,
3372          * that transaction will be committed before the new transaction is started.
3373          *
3374          * Note that when the DBO_TRX flag is set (which is usually the case for web
3375          * requests, but not for maintenance scripts), any previous database query
3376          * will have started a transaction automatically.
3377          *
3378          * Nesting of transactions is not supported. Attempts to nest transactions
3379          * will cause a warning, unless the current transaction was started
3380          * automatically because of the DBO_TRX flag.
3381          *
3382          * @param string $fname
3383          * @throws DBError
3384          */
3385         final public function begin( $fname = __METHOD__ ) {
3386                 global $wgDebugDBTransactions;
3387
3388                 if ( $this->mTrxLevel ) { // implicit commit
3389                         if ( !$this->mTrxAtomicLevels->isEmpty() ) {
3390                                 // If the current transaction was an automatic atomic one, then we definitely have
3391                                 // a problem. Same if there is any unclosed atomic level.
3392                                 throw new DBUnexpectedError( $this,
3393                                         "Attempted to start explicit transaction when atomic levels are still open."
3394                                 );
3395                         } elseif ( !$this->mTrxAutomatic ) {
3396                                 // We want to warn about inadvertently nested begin/commit pairs, but not about
3397                                 // auto-committing implicit transactions that were started by query() via DBO_TRX
3398                                 $msg = "$fname: Transaction already in progress (from {$this->mTrxFname}), " .
3399                                         " performing implicit commit!";
3400                                 wfWarn( $msg );
3401                                 wfLogDBError( $msg );
3402                         } else {
3403                                 // if the transaction was automatic and has done write operations,
3404                                 // log it if $wgDebugDBTransactions is enabled.
3405                                 if ( $this->mTrxDoneWrites && $wgDebugDBTransactions ) {
3406                                         wfDebug( "$fname: Automatic transaction with writes in progress" .
3407                                                 " (from {$this->mTrxFname}), performing implicit commit!\n"
3408                                         );
3409                                 }
3410                         }
3411
3412                         $this->runOnTransactionPreCommitCallbacks();
3413                         $this->doCommit( $fname );
3414                         if ( $this->mTrxDoneWrites ) {
3415                                 $id = spl_object_hash( $this );
3416                                 Profiler::instance()->transactionWritingOut( $this->mServer, $this->mDBname, $id );
3417                         }
3418                         $this->runOnTransactionIdleCallbacks();
3419                 }
3420
3421                 # Avoid fatals if close() was called
3422                 if ( !$this->isOpen() ) {
3423                         throw new DBUnexpectedError( $this, "DB connection was already closed." );
3424                 }
3425
3426                 $this->doBegin( $fname );
3427                 $this->mTrxFname = $fname;
3428                 $this->mTrxDoneWrites = false;
3429                 $this->mTrxAutomatic = false;
3430                 $this->mTrxAutomaticAtomic = false;
3431                 $this->mTrxAtomicLevels = new SplStack;
3432                 $this->mTrxIdleCallbacks = array();
3433                 $this->mTrxPreCommitCallbacks = array();
3434         }
3435
3436         /**
3437          * Issues the BEGIN command to the database server.
3438          *
3439          * @see DatabaseBase::begin()
3440          * @param string $fname
3441          */
3442         protected function doBegin( $fname ) {
3443                 $this->query( 'BEGIN', $fname );
3444                 $this->mTrxLevel = 1;
3445         }
3446
3447         /**
3448          * Commits a transaction previously started using begin().
3449          * If no transaction is in progress, a warning is issued.
3450          *
3451          * Nesting of transactions is not supported.
3452          *
3453          * @param string $fname
3454          * @param string $flush Flush flag, set to 'flush' to disable warnings about
3455          *   explicitly committing implicit transactions, or calling commit when no
3456          *   transaction is in progress. This will silently break any ongoing
3457          *   explicit transaction. Only set the flush flag if you are sure that it
3458          *   is safe to ignore these warnings in your context.
3459          * @throws DBUnexpectedError
3460          */
3461         final public function commit( $fname = __METHOD__, $flush = '' ) {
3462                 if ( !$this->mTrxAtomicLevels->isEmpty() ) {
3463                         // There are still atomic sections open. This cannot be ignored
3464                         throw new DBUnexpectedError(
3465                                 $this,
3466                                 "Attempted to commit transaction while atomic sections are still open"
3467                         );
3468                 }
3469
3470                 if ( $flush !== 'flush' ) {
3471                         if ( !$this->mTrxLevel ) {
3472                                 wfWarn( "$fname: No transaction to commit, something got out of sync!" );
3473                         } elseif ( $this->mTrxAutomatic ) {
3474                                 wfWarn( "$fname: Explicit commit of implicit transaction. Something may be out of sync!" );
3475                         }
3476                 } else {
3477                         if ( !$this->mTrxLevel ) {
3478                                 return; // nothing to do
3479                         } elseif ( !$this->mTrxAutomatic ) {
3480                                 wfWarn( "$fname: Flushing an explicit transaction, getting out of sync!" );
3481                         }
3482                 }
3483
3484                 # Avoid fatals if close() was called
3485                 if ( !$this->isOpen() ) {
3486                         throw new DBUnexpectedError( $this, "DB connection was already closed." );
3487                 }
3488
3489                 $this->runOnTransactionPreCommitCallbacks();
3490                 $this->doCommit( $fname );
3491                 if ( $this->mTrxDoneWrites ) {
3492                         $id = spl_object_hash( $this );
3493                         Profiler::instance()->transactionWritingOut( $this->mServer, $this->mDBname, $id );
3494                 }
3495                 $this->runOnTransactionIdleCallbacks();
3496         }
3497
3498         /**
3499          * Issues the COMMIT command to the database server.
3500          *
3501          * @see DatabaseBase::commit()
3502          * @param string $fname
3503          */
3504         protected function doCommit( $fname ) {
3505                 if ( $this->mTrxLevel ) {
3506                         $this->query( 'COMMIT', $fname );
3507                         $this->mTrxLevel = 0;
3508                 }
3509         }
3510
3511         /**
3512          * Rollback a transaction previously started using begin().
3513          * If no transaction is in progress, a warning is issued.
3514          *
3515          * No-op on non-transactional databases.
3516          *
3517          * @param string $fname
3518          * @param string $flush Flush flag, set to 'flush' to disable warnings about
3519          *   calling rollback when no transaction is in progress. This will silently
3520          *   break any ongoing explicit transaction. Only set the flush flag if you
3521          *   are sure that it is safe to ignore these warnings in your context.
3522          * @since 1.23 Added $flush parameter
3523          */
3524         final public function rollback( $fname = __METHOD__, $flush = '' ) {
3525                 if ( $flush !== 'flush' ) {
3526                         if ( !$this->mTrxLevel ) {
3527                                 wfWarn( "$fname: No transaction to rollback, something got out of sync!" );
3528                         } elseif ( $this->mTrxAutomatic ) {
3529                                 wfWarn( "$fname: Explicit rollback of implicit transaction. Something may be out of sync!" );
3530                         }
3531                 } else {
3532                         if ( !$this->mTrxLevel ) {
3533                                 return; // nothing to do
3534                         } elseif ( !$this->mTrxAutomatic ) {
3535                                 wfWarn( "$fname: Flushing an explicit transaction, getting out of sync!" );
3536                         }
3537                 }
3538
3539                 # Avoid fatals if close() was called
3540                 if ( !$this->isOpen() ) {
3541                         throw new DBUnexpectedError( $this, "DB connection was already closed." );
3542                 }
3543
3544                 $this->doRollback( $fname );
3545                 $this->mTrxIdleCallbacks = array(); // cancel
3546                 $this->mTrxPreCommitCallbacks = array(); // cancel
3547                 $this->mTrxAtomicLevels = new SplStack;
3548                 if ( $this->mTrxDoneWrites ) {
3549                         $id = spl_object_hash( $this );
3550                         Profiler::instance()->transactionWritingOut( $this->mServer, $this->mDBname, $id );
3551                 }
3552         }
3553
3554         /**
3555          * Issues the ROLLBACK command to the database server.
3556          *
3557          * @see DatabaseBase::rollback()
3558          * @param string $fname
3559          */
3560         protected function doRollback( $fname ) {
3561                 if ( $this->mTrxLevel ) {
3562                         $this->query( 'ROLLBACK', $fname, true );
3563                         $this->mTrxLevel = 0;
3564                 }
3565         }
3566
3567         /**
3568          * Creates a new table with structure copied from existing table
3569          * Note that unlike most database abstraction functions, this function does not
3570          * automatically append database prefix, because it works at a lower
3571          * abstraction level.
3572          * The table names passed to this function shall not be quoted (this
3573          * function calls addIdentifierQuotes when needed).
3574          *
3575          * @param string $oldName Name of table whose structure should be copied
3576          * @param string $newName Name of table to be created
3577          * @param bool $temporary Whether the new table should be temporary
3578          * @param string $fname Calling function name
3579          * @throws MWException
3580          * @return bool True if operation was successful
3581          */
3582         public function duplicateTableStructure( $oldName, $newName, $temporary = false,
3583                 $fname = __METHOD__
3584         ) {
3585                 throw new MWException(
3586                         'DatabaseBase::duplicateTableStructure is not implemented in descendant class' );
3587         }
3588
3589         /**
3590          * List all tables on the database
3591          *
3592          * @param string $prefix Only show tables with this prefix, e.g. mw_
3593          * @param string $fname Calling function name
3594          * @throws MWException
3595          */
3596         function listTables( $prefix = null, $fname = __METHOD__ ) {
3597                 throw new MWException( 'DatabaseBase::listTables is not implemented in descendant class' );
3598         }
3599
3600         /**
3601          * Reset the views process cache set by listViews()
3602          * @since 1.22
3603          */
3604         final public function clearViewsCache() {
3605                 $this->allViews = null;
3606         }
3607
3608         /**
3609          * Lists all the VIEWs in the database
3610          *
3611          * For caching purposes the list of all views should be stored in
3612          * $this->allViews. The process cache can be cleared with clearViewsCache()
3613          *
3614          * @param string $prefix Only show VIEWs with this prefix, eg. unit_test_
3615          * @param string $fname Name of calling function
3616          * @throws MWException
3617          * @since 1.22
3618          */
3619         public function listViews( $prefix = null, $fname = __METHOD__ ) {
3620                 throw new MWException( 'DatabaseBase::listViews is not implemented in descendant class' );
3621         }
3622
3623         /**
3624          * Differentiates between a TABLE and a VIEW
3625          *
3626          * @param string $name Name of the database-structure to test.
3627          * @throws MWException
3628          * @since 1.22
3629          */
3630         public function isView( $name ) {
3631                 throw new MWException( 'DatabaseBase::isView is not implemented in descendant class' );
3632         }
3633
3634         /**
3635          * Convert a timestamp in one of the formats accepted by wfTimestamp()
3636          * to the format used for inserting into timestamp fields in this DBMS.
3637          *
3638          * The result is unquoted, and needs to be passed through addQuotes()
3639          * before it can be included in raw SQL.
3640          *
3641          * @param string|int $ts
3642          *
3643          * @return string
3644          */
3645         public function timestamp( $ts = 0 ) {
3646                 return wfTimestamp( TS_MW, $ts );
3647         }
3648
3649         /**
3650          * Convert a timestamp in one of the formats accepted by wfTimestamp()
3651          * to the format used for inserting into timestamp fields in this DBMS. If
3652          * NULL is input, it is passed through, allowing NULL values to be inserted
3653          * into timestamp fields.
3654          *
3655          * The result is unquoted, and needs to be passed through addQuotes()
3656          * before it can be included in raw SQL.
3657          *
3658          * @param string|int $ts
3659          *
3660          * @return string
3661          */
3662         public function timestampOrNull( $ts = null ) {
3663                 if ( is_null( $ts ) ) {
3664                         return null;
3665                 } else {
3666                         return $this->timestamp( $ts );
3667                 }
3668         }
3669
3670         /**
3671          * Take the result from a query, and wrap it in a ResultWrapper if
3672          * necessary. Boolean values are passed through as is, to indicate success
3673          * of write queries or failure.
3674          *
3675          * Once upon a time, DatabaseBase::query() returned a bare MySQL result
3676          * resource, and it was necessary to call this function to convert it to
3677          * a wrapper. Nowadays, raw database objects are never exposed to external
3678          * callers, so this is unnecessary in external code. For compatibility with
3679          * old code, ResultWrapper objects are passed through unaltered.
3680          *
3681          * @param bool|ResultWrapper|resource $result
3682          * @return bool|ResultWrapper
3683          */
3684         public function resultObject( $result ) {
3685                 if ( empty( $result ) ) {
3686                         return false;
3687                 } elseif ( $result instanceof ResultWrapper ) {
3688                         return $result;
3689                 } elseif ( $result === true ) {
3690                         // Successful write query
3691                         return $result;
3692                 } else {
3693                         return new ResultWrapper( $this, $result );
3694                 }
3695         }
3696
3697         /**
3698          * Ping the server and try to reconnect if it there is no connection
3699          *
3700          * @return bool Success or failure
3701          */
3702         public function ping() {
3703                 # Stub. Not essential to override.
3704                 return true;
3705         }
3706
3707         /**
3708          * Get slave lag. Currently supported only by MySQL.
3709          *
3710          * Note that this function will generate a fatal error on many
3711          * installations. Most callers should use LoadBalancer::safeGetLag()
3712          * instead.
3713          *
3714          * @return int Database replication lag in seconds
3715          */
3716         public function getLag() {
3717                 return 0;
3718         }
3719
3720         /**
3721          * Return the maximum number of items allowed in a list, or 0 for unlimited.
3722          *
3723          * @return int
3724          */
3725         function maxListLen() {
3726                 return 0;
3727         }
3728
3729         /**
3730          * Some DBMSs have a special format for inserting into blob fields, they
3731          * don't allow simple quoted strings to be inserted. To insert into such
3732          * a field, pass the data through this function before passing it to
3733          * DatabaseBase::insert().
3734          *
3735          * @param string $b
3736          * @return string
3737          */
3738         public function encodeBlob( $b ) {
3739                 return $b;
3740         }
3741
3742         /**
3743          * Some DBMSs return a special placeholder object representing blob fields
3744          * in result objects. Pass the object through this function to return the
3745          * original string.
3746          *
3747          * @param string $b
3748          * @return string
3749          */
3750         public function decodeBlob( $b ) {
3751                 return $b;
3752         }
3753
3754         /**
3755          * Override database's default behavior. $options include:
3756          *     'connTimeout' : Set the connection timeout value in seconds.
3757          *                     May be useful for very long batch queries such as
3758          *                     full-wiki dumps, where a single query reads out over
3759          *                     hours or days.
3760          *
3761          * @param array $options
3762          * @return void
3763          */
3764         public function setSessionOptions( array $options ) {
3765         }
3766
3767         /**
3768          * Read and execute SQL commands from a file.
3769          *
3770          * Returns true on success, error string or exception on failure (depending
3771          * on object's error ignore settings).
3772          *
3773          * @param string $filename File name to open
3774          * @param bool|callable $lineCallback Optional function called before reading each line
3775          * @param bool|callable $resultCallback Optional function called for each MySQL result
3776          * @param bool|string $fname Calling function name or false if name should be
3777          *   generated dynamically using $filename
3778          * @param bool|callable $inputCallback Optional function called for each
3779          *   complete line sent
3780          * @throws Exception|MWException
3781          * @return bool|string
3782          */
3783         public function sourceFile(
3784                 $filename, $lineCallback = false, $resultCallback = false, $fname = false, $inputCallback = false
3785         ) {
3786                 wfSuppressWarnings();
3787                 $fp = fopen( $filename, 'r' );
3788                 wfRestoreWarnings();
3789
3790                 if ( false === $fp ) {
3791                         throw new MWException( "Could not open \"{$filename}\".\n" );
3792                 }
3793
3794                 if ( !$fname ) {
3795                         $fname = __METHOD__ . "( $filename )";
3796                 }
3797
3798                 try {
3799                         $error = $this->sourceStream( $fp, $lineCallback, $resultCallback, $fname, $inputCallback );
3800                 } catch ( MWException $e ) {
3801                         fclose( $fp );
3802                         throw $e;
3803                 }
3804
3805                 fclose( $fp );
3806
3807                 return $error;
3808         }
3809
3810         /**
3811          * Get the full path of a patch file. Originally based on archive()
3812          * from updaters.inc. Keep in mind this always returns a patch, as
3813          * it fails back to MySQL if no DB-specific patch can be found
3814          *
3815          * @param string $patch The name of the patch, like patch-something.sql
3816          * @return string Full path to patch file
3817          */
3818         public function patchPath( $patch ) {
3819                 global $IP;
3820
3821                 $dbType = $this->getType();
3822                 if ( file_exists( "$IP/maintenance/$dbType/archives/$patch" ) ) {
3823                         return "$IP/maintenance/$dbType/archives/$patch";
3824                 } else {
3825                         return "$IP/maintenance/archives/$patch";
3826                 }
3827         }
3828
3829         /**
3830          * Set variables to be used in sourceFile/sourceStream, in preference to the
3831          * ones in $GLOBALS. If an array is set here, $GLOBALS will not be used at
3832          * all. If it's set to false, $GLOBALS will be used.
3833          *
3834          * @param bool|array $vars Mapping variable name to value.
3835          */
3836         public function setSchemaVars( $vars ) {
3837                 $this->mSchemaVars = $vars;
3838         }
3839
3840         /**
3841          * Read and execute commands from an open file handle.
3842          *
3843          * Returns true on success, error string or exception on failure (depending
3844          * on object's error ignore settings).
3845          *
3846          * @param resource $fp File handle
3847          * @param bool|callable $lineCallback Optional function called before reading each query
3848          * @param bool|callable $resultCallback Optional function called for each MySQL result
3849          * @param string $fname Calling function name
3850          * @param bool|callable $inputCallback Optional function called for each complete query sent
3851          * @return bool|string
3852          */
3853         public function sourceStream( $fp, $lineCallback = false, $resultCallback = false,
3854                 $fname = __METHOD__, $inputCallback = false
3855         ) {
3856                 $cmd = '';
3857
3858                 while ( !feof( $fp ) ) {
3859                         if ( $lineCallback ) {
3860                                 call_user_func( $lineCallback );
3861                         }
3862
3863                         $line = trim( fgets( $fp ) );
3864
3865                         if ( $line == '' ) {
3866                                 continue;
3867                         }
3868
3869                         if ( '-' == $line[0] && '-' == $line[1] ) {
3870                                 continue;
3871                         }
3872
3873                         if ( $cmd != '' ) {
3874                                 $cmd .= ' ';
3875                         }
3876
3877                         $done = $this->streamStatementEnd( $cmd, $line );
3878
3879                         $cmd .= "$line\n";
3880
3881                         if ( $done || feof( $fp ) ) {
3882                                 $cmd = $this->replaceVars( $cmd );
3883
3884                                 if ( ( $inputCallback && call_user_func( $inputCallback, $cmd ) ) || !$inputCallback ) {
3885                                         $res = $this->query( $cmd, $fname );
3886
3887                                         if ( $resultCallback ) {
3888                                                 call_user_func( $resultCallback, $res, $this );
3889                                         }
3890
3891                                         if ( false === $res ) {
3892                                                 $err = $this->lastError();
3893
3894                                                 return "Query \"{$cmd}\" failed with error code \"$err\".\n";
3895                                         }
3896                                 }
3897                                 $cmd = '';
3898                         }
3899                 }
3900
3901                 return true;
3902         }
3903
3904         /**
3905          * Called by sourceStream() to check if we've reached a statement end
3906          *
3907          * @param string $sql SQL assembled so far
3908          * @param string $newLine New line about to be added to $sql
3909          * @return bool Whether $newLine contains end of the statement
3910          */
3911         public function streamStatementEnd( &$sql, &$newLine ) {
3912                 if ( $this->delimiter ) {
3913                         $prev = $newLine;
3914                         $newLine = preg_replace( '/' . preg_quote( $this->delimiter, '/' ) . '$/', '', $newLine );
3915                         if ( $newLine != $prev ) {
3916                                 return true;
3917                         }
3918                 }
3919
3920                 return false;
3921         }
3922
3923         /**
3924          * Database independent variable replacement. Replaces a set of variables
3925          * in an SQL statement with their contents as given by $this->getSchemaVars().
3926          *
3927          * Supports '{$var}' `{$var}` and / *$var* / (without the spaces) style variables.
3928          *
3929          * - '{$var}' should be used for text and is passed through the database's
3930          *   addQuotes method.
3931          * - `{$var}` should be used for identifiers (eg: table and database names),
3932          *   it is passed through the database's addIdentifierQuotes method which
3933          *   can be overridden if the database uses something other than backticks.
3934          * - / *$var* / is just encoded, besides traditional table prefix and
3935          *   table options its use should be avoided.
3936          *
3937          * @param string $ins SQL statement to replace variables in
3938          * @return string The new SQL statement with variables replaced
3939          */
3940         protected function replaceSchemaVars( $ins ) {
3941                 $vars = $this->getSchemaVars();
3942                 foreach ( $vars as $var => $value ) {
3943                         // replace '{$var}'
3944                         $ins = str_replace( '\'{$' . $var . '}\'', $this->addQuotes( $value ), $ins );
3945                         // replace `{$var}`
3946                         $ins = str_replace( '`{$' . $var . '}`', $this->addIdentifierQuotes( $value ), $ins );
3947                         // replace /*$var*/
3948                         $ins = str_replace( '/*$' . $var . '*/', $this->strencode( $value ), $ins );
3949                 }
3950
3951                 return $ins;
3952         }
3953
3954         /**
3955          * Replace variables in sourced SQL
3956          *
3957          * @param string $ins
3958          * @return string
3959          */
3960         protected function replaceVars( $ins ) {
3961                 $ins = $this->replaceSchemaVars( $ins );
3962
3963                 // Table prefixes
3964                 $ins = preg_replace_callback( '!/\*(?:\$wgDBprefix|_)\*/([a-zA-Z_0-9]*)!',
3965                         array( $this, 'tableNameCallback' ), $ins );
3966
3967                 // Index names
3968                 $ins = preg_replace_callback( '!/\*i\*/([a-zA-Z_0-9]*)!',
3969                         array( $this, 'indexNameCallback' ), $ins );
3970
3971                 return $ins;
3972         }
3973
3974         /**
3975          * Get schema variables. If none have been set via setSchemaVars(), then
3976          * use some defaults from the current object.
3977          *
3978          * @return array
3979          */
3980         protected function getSchemaVars() {
3981                 if ( $this->mSchemaVars ) {
3982                         return $this->mSchemaVars;
3983                 } else {
3984                         return $this->getDefaultSchemaVars();
3985                 }
3986         }
3987
3988         /**
3989          * Get schema variables to use if none have been set via setSchemaVars().
3990          *
3991          * Override this in derived classes to provide variables for tables.sql
3992          * and SQL patch files.
3993          *
3994          * @return array
3995          */
3996         protected function getDefaultSchemaVars() {
3997                 return array();
3998         }
3999
4000         /**
4001          * Table name callback
4002          *
4003          * @param array $matches
4004          * @return string
4005          */
4006         protected function tableNameCallback( $matches ) {
4007                 return $this->tableName( $matches[1] );
4008         }
4009
4010         /**
4011          * Index name callback
4012          *
4013          * @param array $matches
4014          * @return string
4015          */
4016         protected function indexNameCallback( $matches ) {
4017                 return $this->indexName( $matches[1] );
4018         }
4019
4020         /**
4021          * Check to see if a named lock is available. This is non-blocking.
4022          *
4023          * @param string $lockName Name of lock to poll
4024          * @param string $method Name of method calling us
4025          * @return bool
4026          * @since 1.20
4027          */
4028         public function lockIsFree( $lockName, $method ) {
4029                 return true;
4030         }
4031
4032         /**
4033          * Acquire a named lock
4034          *
4035          * Abstracted from Filestore::lock() so child classes can implement for
4036          * their own needs.
4037          *
4038          * @param string $lockName Name of lock to aquire
4039          * @param string $method Name of method calling us
4040          * @param int $timeout
4041          * @return bool
4042          */
4043         public function lock( $lockName, $method, $timeout = 5 ) {
4044                 return true;
4045         }
4046
4047         /**
4048          * Release a lock.
4049          *
4050          * @param string $lockName Name of lock to release
4051          * @param string $method Name of method calling us
4052          *
4053          * @return int Returns 1 if the lock was released, 0 if the lock was not established
4054          * by this thread (in which case the lock is not released), and NULL if the named
4055          * lock did not exist
4056          */
4057         public function unlock( $lockName, $method ) {
4058                 return true;
4059         }
4060
4061         /**
4062          * Lock specific tables
4063          *
4064          * @param array $read Array of tables to lock for read access
4065          * @param array $write Array of tables to lock for write access
4066          * @param string $method Name of caller
4067          * @param bool $lowPriority Whether to indicate writes to be LOW PRIORITY
4068          * @return bool
4069          */
4070         public function lockTables( $read, $write, $method, $lowPriority = true ) {
4071                 return true;
4072         }
4073
4074         /**
4075          * Unlock specific tables
4076          *
4077          * @param string $method The caller
4078          * @return bool
4079          */
4080         public function unlockTables( $method ) {
4081                 return true;
4082         }
4083
4084         /**
4085          * Delete a table
4086          * @param string $tableName
4087          * @param string $fName
4088          * @return bool|ResultWrapper
4089          * @since 1.18
4090          */
4091         public function dropTable( $tableName, $fName = __METHOD__ ) {
4092                 if ( !$this->tableExists( $tableName, $fName ) ) {
4093                         return false;
4094                 }
4095                 $sql = "DROP TABLE " . $this->tableName( $tableName );
4096                 if ( $this->cascadingDeletes() ) {
4097                         $sql .= " CASCADE";
4098                 }
4099
4100                 return $this->query( $sql, $fName );
4101         }
4102
4103         /**
4104          * Get search engine class. All subclasses of this need to implement this
4105          * if they wish to use searching.
4106          *
4107          * @return string
4108          */
4109         public function getSearchEngine() {
4110                 return 'SearchEngineDummy';
4111         }
4112
4113         /**
4114          * Find out when 'infinity' is. Most DBMSes support this. This is a special
4115          * keyword for timestamps in PostgreSQL, and works with CHAR(14) as well
4116          * because "i" sorts after all numbers.
4117          *
4118          * @return string
4119          */
4120         public function getInfinity() {
4121                 return 'infinity';
4122         }
4123
4124         /**
4125          * Encode an expiry time into the DBMS dependent format
4126          *
4127          * @param string $expiry timestamp for expiry, or the 'infinity' string
4128          * @return string
4129          */
4130         public function encodeExpiry( $expiry ) {
4131                 return ( $expiry == '' || $expiry == 'infinity' || $expiry == $this->getInfinity() )
4132                         ? $this->getInfinity()
4133                         : $this->timestamp( $expiry );
4134         }
4135
4136         /**
4137          * Decode an expiry time into a DBMS independent format
4138          *
4139          * @param string $expiry DB timestamp field value for expiry
4140          * @param int $format TS_* constant, defaults to TS_MW
4141          * @return string
4142          */
4143         public function decodeExpiry( $expiry, $format = TS_MW ) {
4144                 return ( $expiry == '' || $expiry == $this->getInfinity() )
4145                         ? 'infinity'
4146                         : wfTimestamp( $format, $expiry );
4147         }
4148
4149         /**
4150          * Allow or deny "big selects" for this session only. This is done by setting
4151          * the sql_big_selects session variable.
4152          *
4153          * This is a MySQL-specific feature.
4154          *
4155          * @param bool|string $value True for allow, false for deny, or "default" to
4156          *   restore the initial value
4157          */
4158         public function setBigSelects( $value = true ) {
4159                 // no-op
4160         }
4161
4162         /**
4163          * @since 1.19
4164          */
4165         public function __toString() {
4166                 return (string)$this->mConn;
4167         }
4168
4169         /**
4170          * Run a few simple sanity checks
4171          */
4172         public function __destruct() {
4173                 if ( $this->mTrxLevel && $this->mTrxDoneWrites ) {
4174                         trigger_error( "Uncommitted DB writes (transaction from {$this->mTrxFname})." );
4175                 }
4176                 if ( count( $this->mTrxIdleCallbacks ) || count( $this->mTrxPreCommitCallbacks ) ) {
4177                         $callers = array();
4178                         foreach ( $this->mTrxIdleCallbacks as $callbackInfo ) {
4179                                 $callers[] = $callbackInfo[1];
4180                         }
4181                         $callers = implode( ', ', $callers );
4182                         trigger_error( "DB transaction callbacks still pending (from $callers)." );
4183                 }
4184         }
4185 }