UPGRADE

   1 == The basic theory ==
   2
   3 Generally, within a stable release series (e.g. 1.4.0, 1.4.1, etc) there
   4 are no required database changes, and upgrading should require no more
   5 than copying the new source files over the old ones.
   6
   7 If there are larger changes, such as upgrading from one release series
   8 to another (e.g. from 1.3.12 to 1.4.3), then you may need to update the
   9 database schema and configuration.
  10
  11 Basically, to upgrade a wiki you:
  12 * Back up your data! (See Backups! below)
  13 * Extract the new archive. If you can do this in a clean directory that's
  14   great, but it should work to extract over the old files too. This may
  15   be easier if you have images etc in place and don't want to move them
  16   around, but remember to back up first!
  17 * Run the installer to upgrade the database schema (if necessary).
  18
  19
  20 == IMPORTANT: Upgrading to 1.5 ==
  21
  22 Major changes have been made to the schema from 1.4.x. The updater
  23 has not been fully tested for all conditions, and might well break.
  24
  25 DO NOT ATTEMPT TO UPGRADE A LIVE, PUBLIC SITE TO 1.5 AT THIS TIME.
  26 NEVER EVER ATTEMPT TO PERFORM AN UPGRADE WITHOUT BACKING UP FIRST!
  27
  28 On a large site, the schema update might take a long time. It might
  29 explode, or leave your database half-done or otherwise badly hurting.
  30
  31 Among other changes, note that Latin-1 encoding (ISO-8859-1) is
  32 no longer supported. Latin-1 wikis will need to be upgraded to
  33 UTF-8, however the updater has not yet been updated to support
  34 this automatically.
  35
  36 Message changes:
  37 * A number of additional UI messages have been chagned from HTML to
  38   wikitext, and will need to be manually fixed if customized.
  39
  40
  41 === Web installer ===
  42
  43 You can use the web-based installer wizard if you first remove the
  44 LocalSettings.php (and AdminSettings.php, if any) files; be sure to
  45 give the installer the same information as you did on the original
  46 install (language/encoding, database name, password, etc). This will
  47 also generate a fresh LocalSettings.php, which you may need to customize.
  48
  49 You may change some settings during the install, but be very careful!
  50 Changing the encoding in particular will generally leave you with a
  51 lot of corrupt pages, particularly if your wiki is not in English.
  52
  53 === Command-line upgrade ===
  54
  55 Additionally, as of 1.4.0 you can run an in-place upgrade script from
  56 the command line, keeping your existing LocalSettings.php. This requires
  57 that you create an AdminSettings.php giving an appropriate database user
  58 and password with privileges to modify the database structure.
  59
  60 Once the new files are in place, go into the maintenance subdirectory and
  61 run the script:
  62
  63   php update.php
  64
  65 See caveats below on upgrading from 1.3.x or earlier.
  66
  67
  68 == Backups! ==
  69
  70 To upgrade an existing MediaWiki installation, first BACK UP YOUR WIKI!
  71 If something goes wrong, you want to be able to start again.
  72
  73 Your image files, configuration, etc can simply be copied or archived as
  74 you would any other files. (Make sure that the contents of your
  75 LocalSettings.php are not accidentally made public, as this contains
  76 a database password.)
  77
  78 To back up the database, use the tools provided by your service provider
  79 (if applicable) or the standard mysqldump program.
  80
  81 For general help on mysqldump:
  82 http://dev.mysql.com/doc/mysql/en/mysqldump.html
  83
  84 WARNING: If using MySQL 4.1.x, mysqldump's charset conversion may in
  85 some cases damage data in your wiki. If necessary, set the charset
  86 option to 'latin1' to avoid the conversion. Fore more info see:
  87 http://mail.wikipedia.org/pipermail/wikitech-l/2004-November/026359.html
  88
  89
  90 == Caveats ==
  91
  92
  93 === Upgrading from 1.4.2 or earlier ===
  94
  95 1.4.3 has added new fields to the sitestats table. These fields are
  96 optional and help to speed Special:Statistics on large sites. If you
  97 choose not to run the database upgrades, everything will continue to
  98 work in 1.4.3.
  99
 100 You can apply the update by running maintenance/update.php, or
 101 manually run the SQL commands from this file:
 102   maintenance/archives/patch-ss_total_articles.sql
 103
 104
 105 === Upgrading from 1.4rc1 or earlier betas ===
 106
 107 The logging table has been altered from 1.4beta4 to 1.4beta5
 108 and again in 1.4.0 final. Copy in the new files and use the web
 109 installer to upgrade, or the command-line maintenance/update.php.
 110
 111 If you cannot use the automated installers/updaters, you may
 112 update the table by manually running the SQL commands in these
 113 files:
 114    maintenance/archives/patch-log_params.sql
 115    maintenance/archives/patch-logging-title.sql
 116
 117
 118 === Upgrading from 1.3.x ===
 119
 120 This should generally go smoothly.
 121
 122 If you keep your LocalSettings.php, you may need to change the style paths
 123 to match the newly rearranged skin modules. Change these lines:
 124   $wgStylePath        = "$wgScriptPath/stylesheets";
 125   $wgStyleDirectory   = "$IP/stylesheets";
 126   $wgLogo             = "$wgStylePath/images/wiki.png";
 127
 128 to this:
 129   $wgStylePath        = "$wgScriptPath/skins";
 130   $wgStyleDirectory   = "$IP/skins";
 131   $wgLogo             = "$wgStylePath/common/images/wiki.png";
 132
 133 As well as new messages, the processing of some messages has changed.
 134 If you have customized them, please compare the new format using
 135 Special:Allmessages or the relevant LanguageXX.php files:
 136   copyrightwarning
 137   dberrortext
 138   editingcomment  (was named commentedit)
 139   editingsection  (was named sectionedit)
 140   numauthors
 141   numedits
 142   numtalkauthors
 143   numtalkedits
 144   numwatchers
 145   protectedarticle
 146   searchresulttext
 147   showhideminor
 148   unprotectedarticle
 149
 150 Note that the 1.3 beta releases included a potential vulnerability if PHP
 151 is configured with register_globals on and the includes directory is
 152 served to the web. For general safety, turn register_globals *off* if you
 153 don't _really_ need it for another package.
 154
 155 If your hosting provider turns it on and you can't turn it off yourself,
 156 send them a kind note explaining that it can expose their servers and their
 157 customers to attacks.
 158
 159
 160 === Upgrading from 1.2.x ===
 161
 162 If you've been using the MediaWiki: namespace for custom page templates,
 163 note that things are a little different. The Template: namespace has been
 164 added which is more powerful -- templates can include parameters for
 165 instance.
 166
 167 If you were using custom MediaWiki: entries for text inclusions, they
 168 will *not* automatically be moved to Template: entries at upgrade time.
 169 Be sure to go through and check that everything is working properly;
 170 you can move them manually or you can try using moveCustomMessages.php
 171 in maintenance/archives to do it automatically, but this might break things.
 172
 173 Also, be sure to pick the correct character encoding -- some languages were
 174 only available in Latin-1 on 1.2.x and are now available for Unicode as well.
 175 If you want to upgrade an existing wiki from Latin-1 to Unicode you'll have
 176 to dump the database to SQL, run it through iconv or another conversion tool,
 177 and restore it. Sorry.
 178
 179
 180 === Upgrading from 1.1.x or earlier ===
 181
 182 This is less thoroughly tested, but should work.
 183
 184 You need to specify the *admin* database username and password to the
 185 installer in order for it to successfully upgrade the database structure.
 186 You may wish to manually change the GRANTs later.
 187
 188 If you have a very old database (earlier than organized MediaWiki releases
 189 in late August 2003) you may need to manually run some of the update SQL
 190 scripts in maintenance/archives before the installer is able to pick up
 191 with remaining updates.
 192
 193
 194 === Upgrading from UseModWiki or old "phase 2" Wikipedia code ===
 195
 196 There is a semi-maintained UseModWiki to MediaWiki conversion script at
 197 maintenance/importUseModWiki.php; it may require tweaking and customization
 198 to work for you.
 199
 200 Install a new MediaWiki first, then use the conversion script which will
 201 output SQL statements; direct these to a file and then run that into your
 202 database.
 203
 204 You will have to rebuild the links tables etc after importing.