includes/installer/DatabaseUpdater.php

   1 <?php
   2 /**
   3  * DBMS-specific updater helper.
   4  *
   5  * @file
   6  * @ingroup Deployment
   7  */
   8
   9 require_once( dirname(__FILE__) . '/../../maintenance/Maintenance.php' );
  10
  11 /*
  12  * Class for handling database updates. Roughly based off of updaters.inc, with
  13  * a few improvements :)
  14  *
  15  * @ingroup Deployment
  16  * @since 1.17
  17  */
  18 abstract class DatabaseUpdater {
  19
  20         /**
  21          * Array of updates to perform on the database
  22          *
  23          * @var array
  24          */
  25         protected $updates = array();
  26
  27         /**
  28          * List of extension-provided database updates
  29          * @var array
  30          */
  31         protected $extensionUpdates = array();
  32
  33         /**
  34          * List of extension-provided database updaters
  35          * @var array
  36          */
  37         protected $extensionUpdaters = array();
  38
  39         /**
  40          * Used to hold schema files during installation process
  41          * @var array
  42          */
  43         protected $newExtensions = array();
  44
  45         /**
  46          * Handle to the database subclass
  47          *
  48          * @var DatabaseBase
  49          */
  50         protected $db;
  51
  52         protected $shared = false;
  53
  54         protected $postDatabaseUpdateMaintenance = array(
  55                 'DeleteDefaultMessages'
  56         );
  57
  58         /**
  59          * Constructor
  60          *
  61          * @param $db DatabaseBase object to perform updates on
  62          * @param $shared bool Whether to perform updates on shared tables
  63          * @param $maintenance Maintenance Maintenance object which created us
  64          */
  65         protected function __construct( DatabaseBase &$db, $shared, Maintenance $maintenance = null ) {
  66                 $this->db = $db;
  67                 $this->db->setFlag( DBO_DDLMODE ); // For Oracle's handling of schema files
  68                 $this->shared = $shared;
  69                 if ( $maintenance ) {
  70                         $this->maintenance = $maintenance;
  71                 } else {
  72                         $this->maintenance = new FakeMaintenance;
  73                 }
  74                 $this->maintenance->setDB( $db );
  75                 $this->initOldGlobals();
  76                 $this->loadExtensions();
  77                 wfRunHooks( 'LoadExtensionSchemaUpdates', array( $this ) );
  78         }
  79
  80         /**
  81          * Initialize all of the old globals. One day this should all become
  82          * something much nicer
  83          */
  84         private function initOldGlobals() {
  85                 global $wgExtNewTables, $wgExtNewFields, $wgExtPGNewFields,
  86                         $wgExtPGAlteredFields, $wgExtNewIndexes, $wgExtModifiedFields;
  87
  88                 # For extensions only, should be populated via hooks
  89                 # $wgDBtype should be checked to specifiy the proper file
  90                 $wgExtNewTables = array(); // table, dir
  91                 $wgExtNewFields = array(); // table, column, dir
  92                 $wgExtPGNewFields = array(); // table, column, column attributes; for PostgreSQL
  93                 $wgExtPGAlteredFields = array(); // table, column, new type, conversion method; for PostgreSQL
  94                 $wgExtNewIndexes = array(); // table, index, dir
  95                 $wgExtModifiedFields = array(); // table, index, dir
  96         }
  97
  98         /**
  99          * Loads LocalSettings.php, if needed, and initialises everything needed for LoadExtensionSchemaUpdates hook
 100          */
 101         private function loadExtensions() {
 102                 if ( !defined( 'MEDIAWIKI_INSTALL' ) ) {
 103                         return; // already loaded
 104                 }
 105                 $vars = Installer::getExistingLocalSettings();
 106                 if ( !$vars ) {
 107                         return; // no LocalSettings found
 108                 }
 109                 if ( !isset( $vars['wgHooks'] ) && !isset( $vars['wgHooks']['LoadExtensionSchemaUpdates'] ) ) {
 110                         return;
 111                 }
 112                 global $wgHooks, $wgAutoloadClasses;
 113                 $wgHooks['LoadExtensionSchemaUpdates'] = $vars['wgHooks']['LoadExtensionSchemaUpdates'];
 114                 $wgAutoloadClasses = $wgAutoloadClasses + $vars['wgAutoloadClasses'];
 115         }
 116
 117         /**
 118          * @throws MWException
 119          * @param DatabaseBase $db
 120          * @param bool $shared
 121          * @param null $maintenance
 122          * @return DatabaseUpdater
 123          */
 124         public static function newForDB( &$db, $shared = false, $maintenance = null ) {
 125                 $type = $db->getType();
 126                 if( in_array( $type, Installer::getDBTypes() ) ) {
 127                         $class = ucfirst( $type ) . 'Updater';
 128                         return new $class( $db, $shared, $maintenance );
 129                 } else {
 130                         throw new MWException( __METHOD__ . ' called for unsupported $wgDBtype' );
 131                 }
 132         }
 133
 134         /**
 135          * Get a database connection to run updates
 136          *
 137          * @return DatabaseBase
 138          */
 139         public function getDB() {
 140                 return $this->db;
 141         }
 142
 143         /**
 144          * Output some text. If we're running from web, escape the text first.
 145          *
 146          * @param $str String: Text to output
 147          */
 148         public function output( $str ) {
 149                 if ( $this->maintenance->isQuiet() ) {
 150                         return;
 151                 }
 152                 global $wgCommandLineMode;
 153                 if( !$wgCommandLineMode ) {
 154                         $str = htmlspecialchars( $str );
 155                 }
 156                 echo $str;
 157                 flush();
 158         }
 159
 160         /**
 161          * Add a new update coming from an extension. This should be called by
 162          * extensions while executing the LoadExtensionSchemaUpdates hook.
 163          *
 164          * @param $update Array: the update to run. Format is the following:
 165          *                first item is the callback function, it also can be a
 166          *                simple string with the name of a function in this class,
 167          *                following elements are parameters to the function.
 168          *                Note that callback functions will receive this object as
 169          *                first parameter.
 170          */
 171         public function addExtensionUpdate( Array $update ) {
 172                 $this->extensionUpdates[] = $update;
 173         }
 174
 175         /**
 176          * Add a updater class that will handle extensions DB install/update.
 177          * This should be called by extensions while executing the
 178          * LoadExtensionSchemaUpdates hook.
 179          *
 180          * @param $updater (string) classname (extends DatabaseUpdater).
 181          */
 182         public function addExtensionUpdater( $updater ) {
 183                 $this->extensionUpdaters[] = $updater;
 184         }
 185
 186         /**
 187          * Convenience wrapper for addExtensionUpdate() when adding a new table (which
 188          * is the most common usage of updaters in an extension)
 189          * @param $tableName String Name of table to create
 190          * @param $sqlPath String Full path to the schema file
 191          */
 192         public function addExtensionTable( $tableName, $sqlPath ) {
 193                 $this->extensionUpdates[] = array( 'addTable', $tableName, $sqlPath, true );
 194         }
 195
 196         /**
 197          * Add a brand new extension to MediaWiki. Used during the initial install
 198          * @param $ext String Name of extension
 199          * @param $sqlPath String Full path to the schema file
 200          */
 201         public function addNewExtension( $ext, $sqlPath ) {
 202                 $this->newExtensions[ strtolower( $ext ) ] = $sqlPath;
 203         }
 204
 205         /**
 206          * Get the list of extensions that registered a schema with our DB type
 207          * @return array
 208          */
 209         public function getNewExtensions() {
 210                 return $this->newExtensions;
 211         }
 212
 213         /**
 214          * Get the list of extension-defined updates
 215          *
 216          * @return Array
 217          */
 218         protected function getExtensionUpdates() {
 219                 return $this->extensionUpdates;
 220         }
 221
 222         /**
 223          * Get the list of extension-defined updaters
 224          *
 225          * @return Array
 226          */
 227         protected function getExtensionUpdaters() {
 228                 return $this->extensionUpdaters;
 229         }
 230
 231         public function getPostDatabaseUpdateMaintenance() {
 232                 return $this->postDatabaseUpdateMaintenance;
 233         }
 234
 235         /**
 236          * Do all the updates
 237          *
 238          * @param $what Array: what updates to perform
 239          */
 240         public function doUpdates( $what = array( 'core', 'extensions', 'purge' ) ) {
 241                 global $wgVersion;
 242
 243                 $what = array_flip( $what );
 244                 if ( isset( $what['core'] ) ) {
 245                         $this->runUpdates( $this->getCoreUpdateList(), false );
 246                 }
 247                 if ( isset( $what['extensions'] ) ) {
 248                         $this->runUpdates( $this->getOldGlobalUpdates(), false );
 249                         $this->runUpdates( $this->getExtensionUpdates(), true );
 250                         foreach ( $this->getExtensionUpdaters() as $updaterClass ) {
 251                                 $eupdater = new $updaterClass( $this );
 252                                 $eupdater->doUpdates();
 253                         }
 254                 }
 255
 256                 $this->setAppliedUpdates( $wgVersion, $this->updates );
 257
 258                 if( isset( $what['purge'] ) ) {
 259                         $this->purgeCache();
 260                 }
 261                 if ( isset( $what['core'] ) ) {
 262                         $this->checkStats();
 263                 }
 264         }
 265
 266         /**
 267          * Helper function for doUpdates()
 268          *
 269          * @param $updates Array of updates to run
 270          * @param $passSelf Boolean: whether to pass this object we calling external
 271          *                  functions
 272          */
 273         private function runUpdates( array $updates, $passSelf ) {
 274                 foreach ( $updates as $params ) {
 275                         $func = array_shift( $params );
 276                         if( !is_array( $func ) && method_exists( $this, $func ) ) {
 277                                 $func = array( $this, $func );
 278                         } elseif ( $passSelf ) {
 279                                 array_unshift( $params, $this );
 280                         }
 281                         call_user_func_array( $func, $params );
 282                         flush();
 283                 }
 284                 $this->updates = array_merge( $this->updates, $updates );
 285         }
 286
 287         protected function setAppliedUpdates( $version, $updates = array() ) {
 288                 if( !$this->canUseNewUpdatelog() ) {
 289                         return;
 290                 }
 291                 $key = "updatelist-$version-" . time();
 292                 $this->db->insert( 'updatelog',
 293                         array( 'ul_key' => $key, 'ul_value' => serialize( $updates ) ),
 294                          __METHOD__ );
 295         }
 296
 297         /**
 298          * Helper function: check if the given key is present in the updatelog table.
 299          * Obviously, only use this for updates that occur after the updatelog table was
 300          * created!
 301          * @param $key String Name of the key to check for
 302          */
 303         public function updateRowExists( $key ) {
 304                 $row = $this->db->selectRow(
 305                         'updatelog',
 306                         '1',
 307                         array( 'ul_key' => $key ),
 308                         __METHOD__
 309                 );
 310                 return (bool)$row;
 311         }
 312
 313         /**
 314          * Helper function: Add a key to the updatelog table
 315          * Obviously, only use this for updates that occur after the updatelog table was
 316          * created!
 317          * @param $key String Name of key to insert
 318          * @param $val String [optional] value to insert along with the key
 319          */
 320         public function insertUpdateRow( $key, $val = null ) {
 321                 $values = array( 'ul_key' => $key );
 322                 if( $val && $this->canUseNewUpdatelog() ) {
 323                         $values['ul_value'] = $val;
 324                 }
 325                 $this->db->insert( 'updatelog', $values, __METHOD__, 'IGNORE' );
 326         }
 327
 328         /**
 329          * Updatelog was changed in 1.17 to have a ul_value column so we can record
 330          * more information about what kind of updates we've done (that's what this
 331          * class does). Pre-1.17 wikis won't have this column, and really old wikis
 332          * might not even have updatelog at all
 333          *
 334          * @return boolean
 335          */
 336         protected function canUseNewUpdatelog() {
 337                 return $this->db->tableExists( 'updatelog' ) &&
 338                         $this->db->fieldExists( 'updatelog', 'ul_value' );
 339         }
 340
 341         /**
 342          * Before 1.17, we used to handle updates via stuff like
 343          * $wgExtNewTables/Fields/Indexes. This is nasty :) We refactored a lot
 344          * of this in 1.17 but we want to remain back-compatible for a while. So
 345          * load up these old global-based things into our update list.
 346          */
 347         protected function getOldGlobalUpdates() {
 348                 global $wgExtNewFields, $wgExtNewTables, $wgExtModifiedFields,
 349                         $wgExtNewIndexes, $wgSharedDB, $wgSharedTables;
 350
 351                 $doUser = $this->shared ?
 352                         $wgSharedDB && in_array( 'user', $wgSharedTables ) :
 353                         !$wgSharedDB || !in_array( 'user', $wgSharedTables );
 354
 355                 $updates = array();
 356
 357                 foreach ( $wgExtNewTables as $tableRecord ) {
 358                         $updates[] = array(
 359                                 'addTable', $tableRecord[0], $tableRecord[1], true
 360                         );
 361                 }
 362
 363                 foreach ( $wgExtNewFields as $fieldRecord ) {
 364                         if ( $fieldRecord[0] != 'user' || $doUser ) {
 365                                 $updates[] = array(
 366                                         'addField', $fieldRecord[0], $fieldRecord[1],
 367                                                 $fieldRecord[2], true
 368                                 );
 369                         }
 370                 }
 371
 372                 foreach ( $wgExtNewIndexes as $fieldRecord ) {
 373                         $updates[] = array(
 374                                 'addIndex', $fieldRecord[0], $fieldRecord[1],
 375                                         $fieldRecord[2], true
 376                         );
 377                 }
 378
 379                 foreach ( $wgExtModifiedFields as $fieldRecord ) {
 380                         $updates[] = array(
 381                                 'modifyField', $fieldRecord[0], $fieldRecord[1],
 382                                         $fieldRecord[2], true
 383                         );
 384                 }
 385
 386                 return $updates;
 387         }
 388
 389         /**
 390          * Get an array of updates to perform on the database. Should return a
 391          * multi-dimensional array. The main key is the MediaWiki version (1.12,
 392          * 1.13...) with the values being arrays of updates, identical to how
 393          * updaters.inc did it (for now)
 394          *
 395          * @return Array
 396          */
 397         protected abstract function getCoreUpdateList();
 398
 399         /**
 400          * Applies a SQL patch
 401          * @param $path String Path to the patch file
 402          * @param $isFullPath Boolean Whether to treat $path as a relative or not
 403          */
 404         protected function applyPatch( $path, $isFullPath = false ) {
 405                 if ( $isFullPath ) {
 406                         $this->db->sourceFile( $path );
 407                 } else {
 408                         $this->db->sourceFile( $this->db->patchPath( $path ) );
 409                 }
 410         }
 411
 412         /**
 413          * Add a new table to the database
 414          * @param $name String Name of the new table
 415          * @param $patch String Path to the patch file
 416          * @param $fullpath Boolean Whether to treat $patch path as a relative or not
 417          */
 418         protected function addTable( $name, $patch, $fullpath = false ) {
 419                 if ( $this->db->tableExists( $name ) ) {
 420                         $this->output( "...$name table already exists.\n" );
 421                 } else {
 422                         $this->output( "Creating $name table..." );
 423                         $this->applyPatch( $patch, $fullpath );
 424                         $this->output( "ok\n" );
 425                 }
 426         }
 427
 428         /**
 429          * Add a new field to an existing table
 430          * @param $table String Name of the table to modify
 431          * @param $field String Name of the new field
 432          * @param $patch String Path to the patch file
 433          * @param $fullpath Boolean Whether to treat $patch path as a relative or not
 434          */
 435         protected function addField( $table, $field, $patch, $fullpath = false ) {
 436                 if ( !$this->db->tableExists( $table ) ) {
 437                         $this->output( "...$table table does not exist, skipping new field patch\n" );
 438                 } elseif ( $this->db->fieldExists( $table, $field ) ) {
 439                         $this->output( "...have $field field in $table table.\n" );
 440                 } else {
 441                         $this->output( "Adding $field field to table $table..." );
 442                         $this->applyPatch( $patch, $fullpath );
 443                         $this->output( "ok\n" );
 444                 }
 445         }
 446
 447         /**
 448          * Add a new index to an existing table
 449          * @param $table String Name of the table to modify
 450          * @param $index String Name of the new index
 451          * @param $patch String Path to the patch file
 452          * @param $fullpath Boolean Whether to treat $patch path as a relative or not
 453          */
 454         protected function addIndex( $table, $index, $patch, $fullpath = false ) {
 455                 if ( $this->db->indexExists( $table, $index ) ) {
 456                         $this->output( "...$index key already set on $table table.\n" );
 457                 } else {
 458                         $this->output( "Adding $index key to table $table... " );
 459                         $this->applyPatch( $patch, $fullpath );
 460                         $this->output( "ok\n" );
 461                 }
 462         }
 463
 464         /**
 465          * Drop a field from an existing table
 466          *
 467          * @param $table String Name of the table to modify
 468          * @param $field String Name of the old field
 469          * @param $patch String Path to the patch file
 470          * @param $fullpath Boolean Whether to treat $patch path as a relative or not
 471          */
 472         protected function dropField( $table, $field, $patch, $fullpath = false ) {
 473                 if ( $this->db->fieldExists( $table, $field ) ) {
 474                         $this->output( "Table $table contains $field field. Dropping... " );
 475                         $this->applyPatch( $patch, $fullpath );
 476                         $this->output( "ok\n" );
 477                 } else {
 478                         $this->output( "...$table table does not contain $field field.\n" );
 479                 }
 480         }
 481
 482         /**
 483          * Drop an index from an existing table
 484          *
 485          * @param $table String: Name of the table to modify
 486          * @param $index String: Name of the old index
 487          * @param $patch String: Path to the patch file
 488          * @param $fullpath Boolean: Whether to treat $patch path as a relative or not
 489          */
 490         protected function dropIndex( $table, $index, $patch, $fullpath = false ) {
 491                 if ( $this->db->indexExists( $table, $index ) ) {
 492                         $this->output( "Dropping $index from table $table... " );
 493                         $this->applyPatch( $patch, $fullpath );
 494                         $this->output( "ok\n" );
 495                 } else {
 496                         $this->output( "...$index key doesn't exist.\n" );
 497                 }
 498         }
 499
 500         /**
 501          * Modify an existing field
 502          *
 503          * @param $table String: name of the table to which the field belongs
 504          * @param $field String: name of the field to modify
 505          * @param $patch String: path to the patch file
 506          * @param $fullpath Boolean: whether to treat $patch path as a relative or not
 507          */
 508         public function modifyField( $table, $field, $patch, $fullpath = false ) {
 509                 $updateKey = "$table-$field-$patch";
 510                 if ( !$this->db->tableExists( $table ) ) {
 511                         $this->output( "...$table table does not exist, skipping modify field patch\n" );
 512                 } elseif ( !$this->db->fieldExists( $table, $field ) ) {
 513                         $this->output( "...$field field does not exist in $table table, skipping modify field patch\n" );
 514                 } elseif( $this->updateRowExists( $updateKey ) ) {
 515                         $this->output( "...$field in table $table already modified by patch $patch\n" );
 516                 } else {
 517                         $this->output( "Modifying $field field of table $table..." );
 518                         $this->applyPatch( $patch, $fullpath );
 519                         $this->insertUpdateRow( $updateKey );
 520                         $this->output( "ok\n" );
 521                 }
 522         }
 523
 524         /**
 525          * Purge the objectcache table
 526          */
 527         protected function purgeCache() {
 528                 # We can't guarantee that the user will be able to use TRUNCATE,
 529                 # but we know that DELETE is available to us
 530                 $this->output( "Purging caches..." );
 531                 $this->db->delete( 'objectcache', '*', __METHOD__ );
 532                 $this->output( "done.\n" );
 533         }
 534
 535         /**
 536          * Check the site_stats table is not properly populated.
 537          */
 538         protected function checkStats() {
 539                 $this->output( "Checking site_stats row..." );
 540                 $row = $this->db->selectRow( 'site_stats', '*', array( 'ss_row_id' => 1 ), __METHOD__ );
 541                 if ( $row === false ) {
 542                         $this->output( "data is missing! rebuilding...\n" );
 543                 } elseif ( isset( $row->site_stats ) && $row->ss_total_pages == -1 ) {
 544                         $this->output( "missing ss_total_pages, rebuilding...\n" );
 545                 } else {
 546                         $this->output( "done.\n" );
 547                         return;
 548                 }
 549                 SiteStatsInit::doAllAndCommit( false );
 550         }
 551
 552         # Common updater functions
 553
 554         protected function doActiveUsersInit() {
 555                 $activeUsers = $this->db->selectField( 'site_stats', 'ss_active_users', false, __METHOD__ );
 556                 if ( $activeUsers == -1 ) {
 557                         $activeUsers = $this->db->selectField( 'recentchanges',
 558                                 'COUNT( DISTINCT rc_user_text )',
 559                                 array( 'rc_user != 0', 'rc_bot' => 0, "rc_log_type != 'newusers'" ), __METHOD__
 560                         );
 561                         $this->db->update( 'site_stats',
 562                                 array( 'ss_active_users' => intval( $activeUsers ) ),
 563                                 array( 'ss_row_id' => 1 ), __METHOD__, array( 'LIMIT' => 1 )
 564                         );
 565                 }
 566                 $this->output( "...ss_active_users user count set...\n" );
 567         }
 568
 569         protected function doLogUsertextPopulation() {
 570                 if ( $this->updateRowExists( 'populate log_usertext' ) ) {
 571                         $this->output( "...log_user_text field already populated.\n" );
 572                         return;
 573                 }
 574
 575                 $this->output(
 576                         "Populating log_user_text field, printing progress markers. For large\n" .
 577                         "databases, you may want to hit Ctrl-C and do this manually with\n" .
 578                         "maintenance/populateLogUsertext.php.\n" );
 579                 $task = $this->maintenance->runChild( 'PopulateLogUsertext' );
 580                 $task->execute();
 581                 $this->output( "Done populating log_user_text field.\n" );
 582         }
 583
 584         protected function doLogSearchPopulation() {
 585                 if ( $this->updateRowExists( 'populate log_search' ) ) {
 586                         $this->output( "...log_search table already populated.\n" );
 587                         return;
 588                 }
 589
 590                 $this->output(
 591                         "Populating log_search table, printing progress markers. For large\n" .
 592                         "databases, you may want to hit Ctrl-C and do this manually with\n" .
 593                         "maintenance/populateLogSearch.php.\n" );
 594                 $task = $this->maintenance->runChild( 'PopulateLogSearch' );
 595                 $task->execute();
 596                 $this->output( "Done populating log_search table.\n" );
 597         }
 598
 599         protected function doUpdateTranscacheField() {
 600                 if ( $this->updateRowExists( 'convert transcache field' ) ) {
 601                         $this->output( "...transcache tc_time already converted.\n" );
 602                         return;
 603                 }
 604
 605                 $this->output( "Converting tc_time from UNIX epoch to MediaWiki timestamp... " );
 606                 $this->applyPatch( 'patch-tc-timestamp.sql' );
 607                 $this->output( "ok\n" );
 608         }
 609
 610         protected function doCollationUpdate() {
 611                 global $wgCategoryCollation;
 612                 if ( $this->db->selectField(
 613                         'categorylinks',
 614                         'COUNT(*)',
 615                         'cl_collation != ' . $this->db->addQuotes( $wgCategoryCollation ),
 616                         __METHOD__
 617                 ) == 0 ) {
 618                         $this->output( "...collations up-to-date.\n" );
 619                         return;
 620                 }
 621
 622                 $task = $this->maintenance->runChild( 'UpdateCollation' );
 623                 $task->execute();
 624         }
 625 }