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