includes/installer/DatabaseUpdater.php

   1 <?php
   2 /**
   3  * DBMS-specific updater helper.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup Deployment
  22  */
  23
  24 require_once __DIR__ . '/../../maintenance/Maintenance.php';
  25
  26 /**
  27  * Class for handling database updates. Roughly based off of updaters.inc, with
  28  * a few improvements :)
  29  *
  30  * @ingroup Deployment
  31  * @since 1.17
  32  */
  33 abstract class DatabaseUpdater {
  34         protected static $updateCounter = 0;
  35
  36         /**
  37          * Array of updates to perform on the database
  38          *
  39          * @var array
  40          */
  41         protected $updates = array();
  42
  43         /**
  44          * Array of updates that were skipped
  45          *
  46          * @var array
  47          */
  48         protected $updatesSkipped = array();
  49
  50         /**
  51          * List of extension-provided database updates
  52          * @var array
  53          */
  54         protected $extensionUpdates = array();
  55
  56         /**
  57          * Handle to the database subclass
  58          *
  59          * @var DatabaseBase
  60          */
  61         protected $db;
  62
  63         protected $shared = false;
  64
  65         /**
  66          * Scripts to run after database update
  67          * Should be a subclass of LoggedUpdateMaintenance
  68          */
  69         protected $postDatabaseUpdateMaintenance = array(
  70                 'DeleteDefaultMessages',
  71                 'PopulateRevisionLength',
  72                 'PopulateRevisionSha1',
  73                 'PopulateImageSha1',
  74                 'FixExtLinksProtocolRelative',
  75                 'PopulateFilearchiveSha1',
  76                 'PopulateBacklinkNamespace'
  77         );
  78
  79         /**
  80          * File handle for SQL output.
  81          *
  82          * @var resource
  83          */
  84         protected $fileHandle = null;
  85
  86         /**
  87          * Flag specifying whether or not to skip schema (e.g. SQL-only) updates.
  88          *
  89          * @var bool
  90          */
  91         protected $skipSchema = false;
  92
  93         /**
  94          * Hold the value of $wgContentHandlerUseDB during the upgrade.
  95          */
  96         protected $holdContentHandlerUseDB = true;
  97
  98         /**
  99          * Constructor
 100          *
 101          * @param DatabaseBase $db To perform updates on
 102          * @param bool $shared Whether to perform updates on shared tables
 103          * @param Maintenance $maintenance Maintenance object which created us
 104          */
 105         protected function __construct( DatabaseBase &$db, $shared, Maintenance $maintenance = null ) {
 106                 $this->db = $db;
 107                 $this->db->setFlag( DBO_DDLMODE ); // For Oracle's handling of schema files
 108                 $this->shared = $shared;
 109                 if ( $maintenance ) {
 110                         $this->maintenance = $maintenance;
 111                         $this->fileHandle = $maintenance->fileHandle;
 112                 } else {
 113                         $this->maintenance = new FakeMaintenance;
 114                 }
 115                 $this->maintenance->setDB( $db );
 116                 $this->initOldGlobals();
 117                 $this->loadExtensions();
 118                 wfRunHooks( 'LoadExtensionSchemaUpdates', array( $this ) );
 119         }
 120
 121         /**
 122          * Initialize all of the old globals. One day this should all become
 123          * something much nicer
 124          */
 125         private function initOldGlobals() {
 126                 global $wgExtNewTables, $wgExtNewFields, $wgExtPGNewFields,
 127                         $wgExtPGAlteredFields, $wgExtNewIndexes, $wgExtModifiedFields;
 128
 129                 # For extensions only, should be populated via hooks
 130                 # $wgDBtype should be checked to specifiy the proper file
 131                 $wgExtNewTables = array(); // table, dir
 132                 $wgExtNewFields = array(); // table, column, dir
 133                 $wgExtPGNewFields = array(); // table, column, column attributes; for PostgreSQL
 134                 $wgExtPGAlteredFields = array(); // table, column, new type, conversion method; for PostgreSQL
 135                 $wgExtNewIndexes = array(); // table, index, dir
 136                 $wgExtModifiedFields = array(); // table, index, dir
 137         }
 138
 139         /**
 140          * Loads LocalSettings.php, if needed, and initialises everything needed for
 141          * LoadExtensionSchemaUpdates hook.
 142          */
 143         private function loadExtensions() {
 144                 if ( !defined( 'MEDIAWIKI_INSTALL' ) ) {
 145                         return; // already loaded
 146                 }
 147                 $vars = Installer::getExistingLocalSettings();
 148                 if ( !$vars ) {
 149                         return; // no LocalSettings found
 150                 }
 151                 if ( !isset( $vars['wgHooks'] ) || !isset( $vars['wgHooks']['LoadExtensionSchemaUpdates'] ) ) {
 152                         return;
 153                 }
 154                 global $wgHooks, $wgAutoloadClasses;
 155                 $wgHooks['LoadExtensionSchemaUpdates'] = $vars['wgHooks']['LoadExtensionSchemaUpdates'];
 156                 $wgAutoloadClasses = $wgAutoloadClasses + $vars['wgAutoloadClasses'];
 157         }
 158
 159         /**
 160          * @param DatabaseBase $db
 161          * @param bool $shared
 162          * @param Maintenance $maintenance
 163          *
 164          * @throws MWException
 165          * @return DatabaseUpdater
 166          */
 167         public static function newForDB( &$db, $shared = false, $maintenance = null ) {
 168                 $type = $db->getType();
 169                 if ( in_array( $type, Installer::getDBTypes() ) ) {
 170                         $class = ucfirst( $type ) . 'Updater';
 171
 172                         return new $class( $db, $shared, $maintenance );
 173                 } else {
 174                         throw new MWException( __METHOD__ . ' called for unsupported $wgDBtype' );
 175                 }
 176         }
 177
 178         /**
 179          * Get a database connection to run updates
 180          *
 181          * @return DatabaseBase
 182          */
 183         public function getDB() {
 184                 return $this->db;
 185         }
 186
 187         /**
 188          * Output some text. If we're running from web, escape the text first.
 189          *
 190          * @param string $str Text to output
 191          */
 192         public function output( $str ) {
 193                 if ( $this->maintenance->isQuiet() ) {
 194                         return;
 195                 }
 196                 global $wgCommandLineMode;
 197                 if ( !$wgCommandLineMode ) {
 198                         $str = htmlspecialchars( $str );
 199                 }
 200                 echo $str;
 201                 flush();
 202         }
 203
 204         /**
 205          * Add a new update coming from an extension. This should be called by
 206          * extensions while executing the LoadExtensionSchemaUpdates hook.
 207          *
 208          * @since 1.17
 209          *
 210          * @param array $update The update to run. Format is the following:
 211          *                first item is the callback function, it also can be a
 212          *                simple string with the name of a function in this class,
 213          *                following elements are parameters to the function.
 214          *                Note that callback functions will receive this object as
 215          *                first parameter.
 216          */
 217         public function addExtensionUpdate( array $update ) {
 218                 $this->extensionUpdates[] = $update;
 219         }
 220
 221         /**
 222          * Convenience wrapper for addExtensionUpdate() when adding a new table (which
 223          * is the most common usage of updaters in an extension)
 224          *
 225          * @since 1.18
 226          *
 227          * @param string $tableName Name of table to create
 228          * @param string $sqlPath Full path to the schema file
 229          */
 230         public function addExtensionTable( $tableName, $sqlPath ) {
 231                 $this->extensionUpdates[] = array( 'addTable', $tableName, $sqlPath, true );
 232         }
 233
 234         /**
 235          * @since 1.19
 236          *
 237          * @param string $tableName
 238          * @param string $indexName
 239          * @param string $sqlPath
 240          */
 241         public function addExtensionIndex( $tableName, $indexName, $sqlPath ) {
 242                 $this->extensionUpdates[] = array( 'addIndex', $tableName, $indexName, $sqlPath, true );
 243         }
 244
 245         /**
 246          *
 247          * @since 1.19
 248          *
 249          * @param string $tableName
 250          * @param string $columnName
 251          * @param string $sqlPath
 252          */
 253         public function addExtensionField( $tableName, $columnName, $sqlPath ) {
 254                 $this->extensionUpdates[] = array( 'addField', $tableName, $columnName, $sqlPath, true );
 255         }
 256
 257         /**
 258          *
 259          * @since 1.20
 260          *
 261          * @param string $tableName
 262          * @param string $columnName
 263          * @param string $sqlPath
 264          */
 265         public function dropExtensionField( $tableName, $columnName, $sqlPath ) {
 266                 $this->extensionUpdates[] = array( 'dropField', $tableName, $columnName, $sqlPath, true );
 267         }
 268
 269         /**
 270          * Drop an index from an extension table
 271          *
 272          * @since 1.21
 273          *
 274          * @param string $tableName The table name
 275          * @param string $indexName The index name
 276          * @param string $sqlPath The path to the SQL change path
 277          */
 278         public function dropExtensionIndex( $tableName, $indexName, $sqlPath ) {
 279                 $this->extensionUpdates[] = array( 'dropIndex', $tableName, $indexName, $sqlPath, true );
 280         }
 281
 282         /**
 283          *
 284          * @since 1.20
 285          *
 286          * @param string $tableName
 287          * @param string $sqlPath
 288          */
 289         public function dropExtensionTable( $tableName, $sqlPath ) {
 290                 $this->extensionUpdates[] = array( 'dropTable', $tableName, $sqlPath, true );
 291         }
 292
 293         /**
 294          * Rename an index on an extension table
 295          *
 296          * @since 1.21
 297          *
 298          * @param string $tableName The table name
 299          * @param string $oldIndexName The old index name
 300          * @param string $newIndexName The new index name
 301          * @param string $sqlPath The path to the SQL change path
 302          * @param bool $skipBothIndexExistWarning Whether to warn if both the old
 303          * and the new indexes exist. [facultative; by default, false]
 304          */
 305         public function renameExtensionIndex( $tableName, $oldIndexName, $newIndexName,
 306                 $sqlPath, $skipBothIndexExistWarning = false
 307         ) {
 308                 $this->extensionUpdates[] = array(
 309                         'renameIndex',
 310                         $tableName,
 311                         $oldIndexName,
 312                         $newIndexName,
 313                         $skipBothIndexExistWarning,
 314                         $sqlPath,
 315                         true
 316                 );
 317         }
 318
 319         /**
 320          * @since 1.21
 321          *
 322          * @param string $tableName The table name
 323          * @param string $fieldName The field to be modified
 324          * @param string $sqlPath The path to the SQL change path
 325          */
 326         public function modifyExtensionField( $tableName, $fieldName, $sqlPath ) {
 327                 $this->extensionUpdates[] = array( 'modifyField', $tableName, $fieldName, $sqlPath, true );
 328         }
 329
 330         /**
 331          *
 332          * @since 1.20
 333          *
 334          * @param string $tableName
 335          * @return bool
 336          */
 337         public function tableExists( $tableName ) {
 338                 return ( $this->db->tableExists( $tableName, __METHOD__ ) );
 339         }
 340
 341         /**
 342          * Add a maintenance script to be run after the database updates are complete.
 343          *
 344          * Script should subclass LoggedUpdateMaintenance
 345          *
 346          * @since 1.19
 347          *
 348          * @param string $class Name of a Maintenance subclass
 349          */
 350         public function addPostDatabaseUpdateMaintenance( $class ) {
 351                 $this->postDatabaseUpdateMaintenance[] = $class;
 352         }
 353
 354         /**
 355          * Get the list of extension-defined updates
 356          *
 357          * @return array
 358          */
 359         protected function getExtensionUpdates() {
 360                 return $this->extensionUpdates;
 361         }
 362
 363         /**
 364          * @since 1.17
 365          *
 366          * @return array
 367          */
 368         public function getPostDatabaseUpdateMaintenance() {
 369                 return $this->postDatabaseUpdateMaintenance;
 370         }
 371
 372         /**
 373          * @since 1.21
 374          *
 375          * Writes the schema updates desired to a file for the DB Admin to run.
 376          * @param array $schemaUpdate
 377          */
 378         private function writeSchemaUpdateFile( $schemaUpdate = array() ) {
 379                 $updates = $this->updatesSkipped;
 380                 $this->updatesSkipped = array();
 381
 382                 foreach ( $updates as $funcList ) {
 383                         $func = $funcList[0];
 384                         $arg = $funcList[1];
 385                         $origParams = $funcList[2];
 386                         call_user_func_array( $func, $arg );
 387                         flush();
 388                         $this->updatesSkipped[] = $origParams;
 389                 }
 390         }
 391
 392         /**
 393          * Do all the updates
 394          *
 395          * @param array $what What updates to perform
 396          */
 397         public function doUpdates( $what = array( 'core', 'extensions', 'stats' ) ) {
 398                 global $wgVersion;
 399
 400                 $this->db->begin( __METHOD__ );
 401                 $what = array_flip( $what );
 402                 $this->skipSchema = isset( $what['noschema'] ) || $this->fileHandle !== null;
 403                 if ( isset( $what['core'] ) ) {
 404                         $this->runUpdates( $this->getCoreUpdateList(), false );
 405                 }
 406                 if ( isset( $what['extensions'] ) ) {
 407                         $this->runUpdates( $this->getOldGlobalUpdates(), false );
 408                         $this->runUpdates( $this->getExtensionUpdates(), true );
 409                 }
 410
 411                 if ( isset( $what['stats'] ) ) {
 412                         $this->checkStats();
 413                 }
 414
 415                 $this->setAppliedUpdates( $wgVersion, $this->updates );
 416
 417                 if ( $this->fileHandle ) {
 418                         $this->skipSchema = false;
 419                         $this->writeSchemaUpdateFile();
 420                         $this->setAppliedUpdates( "$wgVersion-schema", $this->updatesSkipped );
 421                 }
 422
 423                 $this->db->commit( __METHOD__ );
 424         }
 425
 426         /**
 427          * Helper function for doUpdates()
 428          *
 429          * @param array $updates Array of updates to run
 430          * @param bool $passSelf Whether to pass this object we calling external functions
 431          */
 432         private function runUpdates( array $updates, $passSelf ) {
 433                 $updatesDone = array();
 434                 $updatesSkipped = array();
 435                 foreach ( $updates as $params ) {
 436                         $origParams = $params;
 437                         $func = array_shift( $params );
 438                         if ( !is_array( $func ) && method_exists( $this, $func ) ) {
 439                                 $func = array( $this, $func );
 440                         } elseif ( $passSelf ) {
 441                                 array_unshift( $params, $this );
 442                         }
 443                         $ret = call_user_func_array( $func, $params );
 444                         flush();
 445                         if ( $ret !== false ) {
 446                                 $updatesDone[] = $origParams;
 447                         } else {
 448                                 $updatesSkipped[] = array( $func, $params, $origParams );
 449                         }
 450                 }
 451                 $this->updatesSkipped = array_merge( $this->updatesSkipped, $updatesSkipped );
 452                 $this->updates = array_merge( $this->updates, $updatesDone );
 453         }
 454
 455         /**
 456          * @param string $version
 457          * @param array $updates
 458          */
 459         protected function setAppliedUpdates( $version, $updates = array() ) {
 460                 $this->db->clearFlag( DBO_DDLMODE );
 461                 if ( !$this->canUseNewUpdatelog() ) {
 462                         return;
 463                 }
 464                 $key = "updatelist-$version-" . time() . self::$updateCounter;
 465                 self::$updateCounter++;
 466                 $this->db->insert( 'updatelog',
 467                         array( 'ul_key' => $key, 'ul_value' => serialize( $updates ) ),
 468                         __METHOD__ );
 469                 $this->db->setFlag( DBO_DDLMODE );
 470         }
 471
 472         /**
 473          * Helper function: check if the given key is present in the updatelog table.
 474          * Obviously, only use this for updates that occur after the updatelog table was
 475          * created!
 476          * @param string $key Name of the key to check for
 477          * @return bool
 478          */
 479         public function updateRowExists( $key ) {
 480                 $row = $this->db->selectRow(
 481                         'updatelog',
 482                         # Bug 65813
 483                         '1 AS X',
 484                         array( 'ul_key' => $key ),
 485                         __METHOD__
 486                 );
 487
 488                 return (bool)$row;
 489         }
 490
 491         /**
 492          * Helper function: Add a key to the updatelog table
 493          * Obviously, only use this for updates that occur after the updatelog table was
 494          * created!
 495          * @param string $key Name of key to insert
 496          * @param string $val [optional] Value to insert along with the key
 497          */
 498         public function insertUpdateRow( $key, $val = null ) {
 499                 $this->db->clearFlag( DBO_DDLMODE );
 500                 $values = array( 'ul_key' => $key );
 501                 if ( $val && $this->canUseNewUpdatelog() ) {
 502                         $values['ul_value'] = $val;
 503                 }
 504                 $this->db->insert( 'updatelog', $values, __METHOD__, 'IGNORE' );
 505                 $this->db->setFlag( DBO_DDLMODE );
 506         }
 507
 508         /**
 509          * Updatelog was changed in 1.17 to have a ul_value column so we can record
 510          * more information about what kind of updates we've done (that's what this
 511          * class does). Pre-1.17 wikis won't have this column, and really old wikis
 512          * might not even have updatelog at all
 513          *
 514          * @return bool
 515          */
 516         protected function canUseNewUpdatelog() {
 517                 return $this->db->tableExists( 'updatelog', __METHOD__ ) &&
 518                         $this->db->fieldExists( 'updatelog', 'ul_value', __METHOD__ );
 519         }
 520
 521         /**
 522          * Returns whether updates should be executed on the database table $name.
 523          * Updates will be prevented if the table is a shared table and it is not
 524          * specified to run updates on shared tables.
 525          *
 526          * @param string $name Table name
 527          * @return bool
 528          */
 529         protected function doTable( $name ) {
 530                 global $wgSharedDB, $wgSharedTables;
 531
 532                 // Don't bother to check $wgSharedTables if there isn't a shared database
 533                 // or the user actually also wants to do updates on the shared database.
 534                 if ( $wgSharedDB === null || $this->shared ) {
 535                         return true;
 536                 }
 537
 538                 if ( in_array( $name, $wgSharedTables ) ) {
 539                         $this->output( "...skipping update to shared table $name.\n" );
 540                         return false;
 541                 } else {
 542                         return true;
 543                 }
 544         }
 545
 546         /**
 547          * Before 1.17, we used to handle updates via stuff like
 548          * $wgExtNewTables/Fields/Indexes. This is nasty :) We refactored a lot
 549          * of this in 1.17 but we want to remain back-compatible for a while. So
 550          * load up these old global-based things into our update list.
 551          *
 552          * @return array
 553          */
 554         protected function getOldGlobalUpdates() {
 555                 global $wgExtNewFields, $wgExtNewTables, $wgExtModifiedFields,
 556                         $wgExtNewIndexes;
 557
 558                 $updates = array();
 559
 560                 foreach ( $wgExtNewTables as $tableRecord ) {
 561                         $updates[] = array(
 562                                 'addTable', $tableRecord[0], $tableRecord[1], true
 563                         );
 564                 }
 565
 566                 foreach ( $wgExtNewFields as $fieldRecord ) {
 567                         $updates[] = array(
 568                                 'addField', $fieldRecord[0], $fieldRecord[1],
 569                                 $fieldRecord[2], true
 570                         );
 571                 }
 572
 573                 foreach ( $wgExtNewIndexes as $fieldRecord ) {
 574                         $updates[] = array(
 575                                 'addIndex', $fieldRecord[0], $fieldRecord[1],
 576                                 $fieldRecord[2], true
 577                         );
 578                 }
 579
 580                 foreach ( $wgExtModifiedFields as $fieldRecord ) {
 581                         $updates[] = array(
 582                                 'modifyField', $fieldRecord[0], $fieldRecord[1],
 583                                 $fieldRecord[2], true
 584                         );
 585                 }
 586
 587                 return $updates;
 588         }
 589
 590         /**
 591          * Get an array of updates to perform on the database. Should return a
 592          * multi-dimensional array. The main key is the MediaWiki version (1.12,
 593          * 1.13...) with the values being arrays of updates, identical to how
 594          * updaters.inc did it (for now)
 595          *
 596          * @return array
 597          */
 598         abstract protected function getCoreUpdateList();
 599
 600         /**
 601          * Append an SQL fragment to the open file handle.
 602          *
 603          * @param string $filename File name to open
 604          */
 605         public function copyFile( $filename ) {
 606                 $this->db->sourceFile( $filename, false, false, false,
 607                         array( $this, 'appendLine' )
 608                 );
 609         }
 610
 611         /**
 612          * Append a line to the open filehandle.  The line is assumed to
 613          * be a complete SQL statement.
 614          *
 615          * This is used as a callback for for sourceLine().
 616          *
 617          * @param string $line Text to append to the file
 618          * @return bool False to skip actually executing the file
 619          * @throws MWException
 620          */
 621         public function appendLine( $line ) {
 622                 $line = rtrim( $line ) . ";\n";
 623                 if ( fwrite( $this->fileHandle, $line ) === false ) {
 624                         throw new MWException( "trouble writing file" );
 625                 }
 626
 627                 return false;
 628         }
 629
 630         /**
 631          * Applies a SQL patch
 632          *
 633          * @param string $path Path to the patch file
 634          * @param bool $isFullPath Whether to treat $path as a relative or not
 635          * @param string $msg Description of the patch
 636          * @return bool False if patch is skipped.
 637          */
 638         protected function applyPatch( $path, $isFullPath = false, $msg = null ) {
 639                 if ( $msg === null ) {
 640                         $msg = "Applying $path patch";
 641                 }
 642                 if ( $this->skipSchema ) {
 643                         $this->output( "...skipping schema change ($msg).\n" );
 644
 645                         return false;
 646                 }
 647
 648                 $this->output( "$msg ..." );
 649
 650                 if ( !$isFullPath ) {
 651                         $path = $this->db->patchPath( $path );
 652                 }
 653                 if ( $this->fileHandle !== null ) {
 654                         $this->copyFile( $path );
 655                 } else {
 656                         $this->db->sourceFile( $path );
 657                 }
 658                 $this->output( "done.\n" );
 659
 660                 return true;
 661         }
 662
 663         /**
 664          * Add a new table to the database
 665          *
 666          * @param string $name Name of the new table
 667          * @param string $patch Path to the patch file
 668          * @param bool $fullpath Whether to treat $patch path as a relative or not
 669          * @return bool False if this was skipped because schema changes are skipped
 670          */
 671         protected function addTable( $name, $patch, $fullpath = false ) {
 672                 if ( !$this->doTable( $name ) ) {
 673                         return true;
 674                 }
 675
 676                 if ( $this->db->tableExists( $name, __METHOD__ ) ) {
 677                         $this->output( "...$name table already exists.\n" );
 678                 } else {
 679                         return $this->applyPatch( $patch, $fullpath, "Creating $name table" );
 680                 }
 681
 682                 return true;
 683         }
 684
 685         /**
 686          * Add a new field to an existing table
 687          *
 688          * @param string $table Name of the table to modify
 689          * @param string $field Name of the new field
 690          * @param string $patch Path to the patch file
 691          * @param bool $fullpath Whether to treat $patch path as a relative or not
 692          * @return bool False if this was skipped because schema changes are skipped
 693          */
 694         protected function addField( $table, $field, $patch, $fullpath = false ) {
 695                 if ( !$this->doTable( $table ) ) {
 696                         return true;
 697                 }
 698
 699                 if ( !$this->db->tableExists( $table, __METHOD__ ) ) {
 700                         $this->output( "...$table table does not exist, skipping new field patch.\n" );
 701                 } elseif ( $this->db->fieldExists( $table, $field, __METHOD__ ) ) {
 702                         $this->output( "...have $field field in $table table.\n" );
 703                 } else {
 704                         return $this->applyPatch( $patch, $fullpath, "Adding $field field to table $table" );
 705                 }
 706
 707                 return true;
 708         }
 709
 710         /**
 711          * Add a new index to an existing table
 712          *
 713          * @param string $table Name of the table to modify
 714          * @param string $index Name of the new index
 715          * @param string $patch Path to the patch file
 716          * @param bool $fullpath Whether to treat $patch path as a relative or not
 717          * @return bool False if this was skipped because schema changes are skipped
 718          */
 719         protected function addIndex( $table, $index, $patch, $fullpath = false ) {
 720                 if ( !$this->doTable( $table ) ) {
 721                         return true;
 722                 }
 723
 724                 if ( !$this->db->tableExists( $table, __METHOD__ ) ) {
 725                         $this->output( "...skipping: '$table' table doesn't exist yet.\n" );
 726                 } elseif ( $this->db->indexExists( $table, $index, __METHOD__ ) ) {
 727                         $this->output( "...index $index already set on $table table.\n" );
 728                 } else {
 729                         return $this->applyPatch( $patch, $fullpath, "Adding index $index to table $table" );
 730                 }
 731
 732                 return true;
 733         }
 734
 735         /**
 736          * Drop a field from an existing table
 737          *
 738          * @param string $table Name of the table to modify
 739          * @param string $field Name of the old field
 740          * @param string $patch Path to the patch file
 741          * @param bool $fullpath Whether to treat $patch path as a relative or not
 742          * @return bool False if this was skipped because schema changes are skipped
 743          */
 744         protected function dropField( $table, $field, $patch, $fullpath = false ) {
 745                 if ( !$this->doTable( $table ) ) {
 746                         return true;
 747                 }
 748
 749                 if ( $this->db->fieldExists( $table, $field, __METHOD__ ) ) {
 750                         return $this->applyPatch( $patch, $fullpath, "Table $table contains $field field. Dropping" );
 751                 } else {
 752                         $this->output( "...$table table does not contain $field field.\n" );
 753                 }
 754
 755                 return true;
 756         }
 757
 758         /**
 759          * Drop an index from an existing table
 760          *
 761          * @param string $table Name of the table to modify
 762          * @param string $index Name of the index
 763          * @param string $patch Path to the patch file
 764          * @param bool $fullpath Whether to treat $patch path as a relative or not
 765          * @return bool False if this was skipped because schema changes are skipped
 766          */
 767         protected function dropIndex( $table, $index, $patch, $fullpath = false ) {
 768                 if ( !$this->doTable( $table ) ) {
 769                         return true;
 770                 }
 771
 772                 if ( $this->db->indexExists( $table, $index, __METHOD__ ) ) {
 773                         return $this->applyPatch( $patch, $fullpath, "Dropping $index index from table $table" );
 774                 } else {
 775                         $this->output( "...$index key doesn't exist.\n" );
 776                 }
 777
 778                 return true;
 779         }
 780
 781         /**
 782          * Rename an index from an existing table
 783          *
 784          * @param string $table Name of the table to modify
 785          * @param string $oldIndex Old name of the index
 786          * @param string $newIndex New name of the index
 787          * @param bool $skipBothIndexExistWarning Whether to warn if both the
 788          * old and the new indexes exist.
 789          * @param string $patch Path to the patch file
 790          * @param bool $fullpath Whether to treat $patch path as a relative or not
 791          * @return bool False if this was skipped because schema changes are skipped
 792          */
 793         protected function renameIndex( $table, $oldIndex, $newIndex,
 794                 $skipBothIndexExistWarning, $patch, $fullpath = false
 795         ) {
 796                 if ( !$this->doTable( $table ) ) {
 797                         return true;
 798                 }
 799
 800                 // First requirement: the table must exist
 801                 if ( !$this->db->tableExists( $table, __METHOD__ ) ) {
 802                         $this->output( "...skipping: '$table' table doesn't exist yet.\n" );
 803
 804                         return true;
 805                 }
 806
 807                 // Second requirement: the new index must be missing
 808                 if ( $this->db->indexExists( $table, $newIndex, __METHOD__ ) ) {
 809                         $this->output( "...index $newIndex already set on $table table.\n" );
 810                         if ( !$skipBothIndexExistWarning &&
 811                                 $this->db->indexExists( $table, $oldIndex, __METHOD__ )
 812                         ) {
 813                                 $this->output( "...WARNING: $oldIndex still exists, despite it has " .
 814                                         "been renamed into $newIndex (which also exists).\n" .
 815                                         "            $oldIndex should be manually removed if not needed anymore.\n" );
 816                         }
 817
 818                         return true;
 819                 }
 820
 821                 // Third requirement: the old index must exist
 822                 if ( !$this->db->indexExists( $table, $oldIndex, __METHOD__ ) ) {
 823                         $this->output( "...skipping: index $oldIndex doesn't exist.\n" );
 824
 825                         return true;
 826                 }
 827
 828                 // Requirements have been satisfied, patch can be applied
 829                 return $this->applyPatch(
 830                         $patch,
 831                         $fullpath,
 832                         "Renaming index $oldIndex into $newIndex to table $table"
 833                 );
 834         }
 835
 836         /**
 837          * If the specified table exists, drop it, or execute the
 838          * patch if one is provided.
 839          *
 840          * Public @since 1.20
 841          *
 842          * @param string $table Table to drop.
 843          * @param string|bool $patch String of patch file that will drop the table. Default: false.
 844          * @param bool $fullpath Whether $patch is a full path. Default: false.
 845          * @return bool False if this was skipped because schema changes are skipped
 846          */
 847         public function dropTable( $table, $patch = false, $fullpath = false ) {
 848                 if ( !$this->doTable( $table ) ) {
 849                         return true;
 850                 }
 851
 852                 if ( $this->db->tableExists( $table, __METHOD__ ) ) {
 853                         $msg = "Dropping table $table";
 854
 855                         if ( $patch === false ) {
 856                                 $this->output( "$msg ..." );
 857                                 $this->db->dropTable( $table, __METHOD__ );
 858                                 $this->output( "done.\n" );
 859                         } else {
 860                                 return $this->applyPatch( $patch, $fullpath, $msg );
 861                         }
 862                 } else {
 863                         $this->output( "...$table doesn't exist.\n" );
 864                 }
 865
 866                 return true;
 867         }
 868
 869         /**
 870          * Modify an existing field
 871          *
 872          * @param string $table Name of the table to which the field belongs
 873          * @param string $field Name of the field to modify
 874          * @param string $patch Path to the patch file
 875          * @param bool $fullpath Whether to treat $patch path as a relative or not
 876          * @return bool False if this was skipped because schema changes are skipped
 877          */
 878         public function modifyField( $table, $field, $patch, $fullpath = false ) {
 879                 if ( !$this->doTable( $table ) ) {
 880                         return true;
 881                 }
 882
 883                 $updateKey = "$table-$field-$patch";
 884                 if ( !$this->db->tableExists( $table, __METHOD__ ) ) {
 885                         $this->output( "...$table table does not exist, skipping modify field patch.\n" );
 886                 } elseif ( !$this->db->fieldExists( $table, $field, __METHOD__ ) ) {
 887                         $this->output( "...$field field does not exist in $table table, " .
 888                                 "skipping modify field patch.\n" );
 889                 } elseif ( $this->updateRowExists( $updateKey ) ) {
 890                         $this->output( "...$field in table $table already modified by patch $patch.\n" );
 891                 } else {
 892                         $this->insertUpdateRow( $updateKey );
 893
 894                         return $this->applyPatch( $patch, $fullpath, "Modifying $field field of table $table" );
 895                 }
 896
 897                 return true;
 898         }
 899
 900         /**
 901          * Purge the objectcache table
 902          */
 903         public function purgeCache() {
 904                 global $wgLocalisationCacheConf;
 905                 # We can't guarantee that the user will be able to use TRUNCATE,
 906                 # but we know that DELETE is available to us
 907                 $this->output( "Purging caches..." );
 908                 $this->db->delete( 'objectcache', '*', __METHOD__ );
 909                 if ( $wgLocalisationCacheConf['manualRecache'] ) {
 910                         $this->rebuildLocalisationCache();
 911                 }
 912                 MessageBlobStore::getInstance()->clear();
 913                 $this->output( "done.\n" );
 914         }
 915
 916         /**
 917          * Check the site_stats table is not properly populated.
 918          */
 919         protected function checkStats() {
 920                 $this->output( "...site_stats is populated..." );
 921                 $row = $this->db->selectRow( 'site_stats', '*', array( 'ss_row_id' => 1 ), __METHOD__ );
 922                 if ( $row === false ) {
 923                         $this->output( "data is missing! rebuilding...\n" );
 924                 } elseif ( isset( $row->site_stats ) && $row->ss_total_pages == -1 ) {
 925                         $this->output( "missing ss_total_pages, rebuilding...\n" );
 926                 } else {
 927                         $this->output( "done.\n" );
 928
 929                         return;
 930                 }
 931                 SiteStatsInit::doAllAndCommit( $this->db );
 932         }
 933
 934         # Common updater functions
 935
 936         /**
 937          * Sets the number of active users in the site_stats table
 938          */
 939         protected function doActiveUsersInit() {
 940                 $activeUsers = $this->db->selectField( 'site_stats', 'ss_active_users', false, __METHOD__ );
 941                 if ( $activeUsers == -1 ) {
 942                         $activeUsers = $this->db->selectField( 'recentchanges',
 943                                 'COUNT( DISTINCT rc_user_text )',
 944                                 array( 'rc_user != 0', 'rc_bot' => 0, "rc_log_type != 'newusers'" ), __METHOD__
 945                         );
 946                         $this->db->update( 'site_stats',
 947                                 array( 'ss_active_users' => intval( $activeUsers ) ),
 948                                 array( 'ss_row_id' => 1 ), __METHOD__, array( 'LIMIT' => 1 )
 949                         );
 950                 }
 951                 $this->output( "...ss_active_users user count set...\n" );
 952         }
 953
 954         /**
 955          * Populates the log_user_text field in the logging table
 956          */
 957         protected function doLogUsertextPopulation() {
 958                 if ( !$this->updateRowExists( 'populate log_usertext' ) ) {
 959                         $this->output(
 960                                 "Populating log_user_text field, printing progress markers. For large\n" .
 961                                 "databases, you may want to hit Ctrl-C and do this manually with\n" .
 962                                 "maintenance/populateLogUsertext.php.\n"
 963                         );
 964
 965                         $task = $this->maintenance->runChild( 'PopulateLogUsertext' );
 966                         $task->execute();
 967                         $this->output( "done.\n" );
 968                 }
 969         }
 970
 971         /**
 972          * Migrate log params to new table and index for searching
 973          */
 974         protected function doLogSearchPopulation() {
 975                 if ( !$this->updateRowExists( 'populate log_search' ) ) {
 976                         $this->output(
 977                                 "Populating log_search table, printing progress markers. For large\n" .
 978                                 "databases, you may want to hit Ctrl-C and do this manually with\n" .
 979                                 "maintenance/populateLogSearch.php.\n" );
 980
 981                         $task = $this->maintenance->runChild( 'PopulateLogSearch' );
 982                         $task->execute();
 983                         $this->output( "done.\n" );
 984                 }
 985         }
 986
 987         /**
 988          * Updates the timestamps in the transcache table
 989          * @return bool
 990          */
 991         protected function doUpdateTranscacheField() {
 992                 if ( $this->updateRowExists( 'convert transcache field' ) ) {
 993                         $this->output( "...transcache tc_time already converted.\n" );
 994
 995                         return true;
 996                 }
 997
 998                 return $this->applyPatch( 'patch-tc-timestamp.sql', false,
 999                         "Converting tc_time from UNIX epoch to MediaWiki timestamp" );
1000         }
1001
1002         /**
1003          * Update CategoryLinks collation
1004          */
1005         protected function doCollationUpdate() {
1006                 global $wgCategoryCollation;
1007                 if ( $this->db->fieldExists( 'categorylinks', 'cl_collation', __METHOD__ ) ) {
1008                         if ( $this->db->selectField(
1009                                 'categorylinks',
1010                                 'COUNT(*)',
1011                                 'cl_collation != ' . $this->db->addQuotes( $wgCategoryCollation ),
1012                                 __METHOD__
1013                                 ) == 0
1014                         ) {
1015                                 $this->output( "...collations up-to-date.\n" );
1016
1017                                 return;
1018                         }
1019
1020                         $this->output( "Updating category collations..." );
1021                         $task = $this->maintenance->runChild( 'UpdateCollation' );
1022                         $task->execute();
1023                         $this->output( "...done.\n" );
1024                 }
1025         }
1026
1027         /**
1028          * Migrates user options from the user table blob to user_properties
1029          */
1030         protected function doMigrateUserOptions() {
1031                 if ( $this->db->tableExists( 'user_properties' ) ) {
1032                         $cl = $this->maintenance->runChild( 'ConvertUserOptions', 'convertUserOptions.php' );
1033                         $cl->execute();
1034                         $this->output( "done.\n" );
1035                 }
1036         }
1037
1038         /**
1039          * Rebuilds the localisation cache
1040          */
1041         protected function rebuildLocalisationCache() {
1042                 /**
1043                  * @var $cl RebuildLocalisationCache
1044                  */
1045                 $cl = $this->maintenance->runChild( 'RebuildLocalisationCache', 'rebuildLocalisationCache.php' );
1046                 $this->output( "Rebuilding localisation cache...\n" );
1047                 $cl->setForce();
1048                 $cl->execute();
1049                 $this->output( "done.\n" );
1050         }
1051
1052         /**
1053          * Turns off content handler fields during parts of the upgrade
1054          * where they aren't available.
1055          */
1056         protected function disableContentHandlerUseDB() {
1057                 global $wgContentHandlerUseDB;
1058
1059                 if ( $wgContentHandlerUseDB ) {
1060                         $this->output( "Turning off Content Handler DB fields for this part of upgrade.\n" );
1061                         $this->holdContentHandlerUseDB = $wgContentHandlerUseDB;
1062                         $wgContentHandlerUseDB = false;
1063                 }
1064         }
1065
1066         /**
1067          * Turns content handler fields back on.
1068          */
1069         protected function enableContentHandlerUseDB() {
1070                 global $wgContentHandlerUseDB;
1071
1072                 if ( $this->holdContentHandlerUseDB ) {
1073                         $this->output( "Content Handler DB fields should be usable now.\n" );
1074                         $wgContentHandlerUseDB = $this->holdContentHandlerUseDB;
1075                 }
1076         }
1077 }