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; an experimental command-line upgrade helper script,
  34 'upgrade1_5.php', can do this -- run it prior to 'update.php' or
  35 the web upgrader.
  36
  37 If you absolutely cannot make the UTF-8 upgrade work, you can try
  38 doing it by hand: dump your old database, convert the dump file
  39 using iconv as described here:
  40 http://portal.suse.com/sdb/en/2004/05/jbartsh_utf-8.html
  41 and then reimport it. You can also convert filenames using convmv,
  42 but note that the old directory hashes will no longer be valid,
  43 so you will also have to move them to new destinations.
  44
  45 Message changes:
  46 * A number of additional UI messages have been chagned from HTML to
  47   wikitext, and will need to be manually fixed if customized.
  48
  49
  50 === Configuration changes from 1.4.x: ===
  51
  52 $wgDisableUploads has been replaced with $wgEnableUploads.
  53
  54 $wgWhitelistAccount has been replaced by the 'createaccount' permission
  55 key in $wgGroupPermissions. To emulate the old effect of setting:
  56   $wgWhitelistAccount['user'] = 0;
  57 set:
  58   $wgGroupPermissions['*']['createaccount'] = false;
  59
  60 $wgWhitelistEdit has been replaced by the 'edit' permission key.
  61 To emulate the old effect of setting:
  62   $wgWhitelistEdit = true;
  63 set:
  64   $wgGroupPermissions['*']['edit'] = false;
  65
  66 If $wgWhitelistRead is set, you must also disable the 'read' permission
  67 for it to take affect on anonymous users:
  68   $wgWhitelistRead = array( "Main Page", "Special:Userlogin" );
  69   $wgGroupPermissions['*']['read'] = false;
  70
  71 Note that you can disable/enable several other permissions by modifying
  72 this configuration array in your LocalSettings.php; see DefaultSettings.php
  73 for the complete default permission set.
  74
  75 If using Memcached, you must enabled it differently now:
  76   $wgUseMemCached = true;
  77 should be replaced with:
  78   $wgMainCacheType = CACHE_MEMCACHED;
  79
  80
  81 === Web installer ===
  82
  83 You can use the web-based installer wizard if you first remove the
  84 LocalSettings.php (and AdminSettings.php, if any) files; be sure to
  85 give the installer the same information as you did on the original
  86 install (language/encoding, database name, password, etc). This will
  87 also generate a fresh LocalSettings.php, which you may need to customize.
  88
  89 You may change some settings during the install, but be very careful!
  90 Changing the encoding in particular will generally leave you with a
  91 lot of corrupt pages, particularly if your wiki is not in English.
  92
  93 === Command-line upgrade ===
  94
  95 Additionally, as of 1.4.0 you can run an in-place upgrade script from
  96 the command line, keeping your existing LocalSettings.php. This requires
  97 that you create an AdminSettings.php giving an appropriate database user
  98 and password with privileges to modify the database structure.
  99
 100 Once the new files are in place, go into the maintenance subdirectory and
 101 run the script:
 102
 103   php update.php
 104
 105 See caveats below on upgrading from 1.3.x or earlier.
 106
 107
 108 == Backups! ==
 109
 110 To upgrade an existing MediaWiki installation, first BACK UP YOUR WIKI!
 111 If something goes wrong, you want to be able to start again.
 112
 113 Your image files, configuration, etc can simply be copied or archived as
 114 you would any other files. (Make sure that the contents of your
 115 LocalSettings.php are not accidentally made public, as this contains
 116 a database password.)
 117
 118 To back up the database, use the tools provided by your service provider
 119 (if applicable) or the standard mysqldump program.
 120
 121 For general help on mysqldump:
 122 http://dev.mysql.com/doc/mysql/en/mysqldump.html
 123
 124 WARNING: If using MySQL 4.1.x, mysqldump's charset conversion may in
 125 some cases damage data in your wiki. If necessary, set the charset
 126 option to 'latin1' to avoid the conversion. Fore more info see:
 127 http://mail.wikipedia.org/pipermail/wikitech-l/2004-November/026359.html
 128
 129
 130 == Caveats ==
 131
 132
 133 === Upgrading from 1.4.2 or earlier ===
 134
 135 1.4.3 has added new fields to the sitestats table. These fields are
 136 optional and help to speed Special:Statistics on large sites. If you
 137 choose not to run the database upgrades, everything will continue to
 138 work in 1.4.3.
 139
 140 You can apply the update by running maintenance/update.php, or
 141 manually run the SQL commands from this file:
 142   maintenance/archives/patch-ss_total_articles.sql
 143
 144
 145 === Upgrading from 1.4rc1 or earlier betas ===
 146
 147 The logging table has been altered from 1.4beta4 to 1.4beta5
 148 and again in 1.4.0 final. Copy in the new files and use the web
 149 installer to upgrade, or the command-line maintenance/update.php.
 150
 151 If you cannot use the automated installers/updaters, you may
 152 update the table by manually running the SQL commands in these
 153 files:
 154    maintenance/archives/patch-log_params.sql
 155    maintenance/archives/patch-logging-title.sql
 156
 157
 158 === Upgrading from 1.3.x ===
 159
 160 This should generally go smoothly.
 161
 162 If you keep your LocalSettings.php, you may need to change the style paths
 163 to match the newly rearranged skin modules. Change these lines:
 164   $wgStylePath        = "$wgScriptPath/stylesheets";
 165   $wgStyleDirectory   = "$IP/stylesheets";
 166   $wgLogo             = "$wgStylePath/images/wiki.png";
 167
 168 to this:
 169   $wgStylePath        = "$wgScriptPath/skins";
 170   $wgStyleDirectory   = "$IP/skins";
 171   $wgLogo             = "$wgStylePath/common/images/wiki.png";
 172
 173 As well as new messages, the processing of some messages has changed.
 174 If you have customized them, please compare the new format using
 175 Special:Allmessages or the relevant LanguageXX.php files:
 176   copyrightwarning
 177   dberrortext
 178   editingcomment  (was named commentedit)
 179   editingsection  (was named sectionedit)
 180   numauthors
 181   numedits
 182   numtalkauthors
 183   numtalkedits
 184   numwatchers
 185   protectedarticle
 186   searchresulttext
 187   showhideminor
 188   unprotectedarticle
 189
 190 Note that the 1.3 beta releases included a potential vulnerability if PHP
 191 is configured with register_globals on and the includes directory is
 192 served to the web. For general safety, turn register_globals *off* if you
 193 don't _really_ need it for another package.
 194
 195 If your hosting provider turns it on and you can't turn it off yourself,
 196 send them a kind note explaining that it can expose their servers and their
 197 customers to attacks.
 198
 199
 200 === Upgrading from 1.2.x ===
 201
 202 If you've been using the MediaWiki: namespace for custom page templates,
 203 note that things are a little different. The Template: namespace has been
 204 added which is more powerful -- templates can include parameters for
 205 instance.
 206
 207 If you were using custom MediaWiki: entries for text inclusions, they
 208 will *not* automatically be moved to Template: entries at upgrade time.
 209 Be sure to go through and check that everything is working properly;
 210 you can move them manually or you can try using moveCustomMessages.php
 211 in maintenance/archives to do it automatically, but this might break things.
 212
 213 Also, be sure to pick the correct character encoding -- some languages were
 214 only available in Latin-1 on 1.2.x and are now available for Unicode as well.
 215 If you want to upgrade an existing wiki from Latin-1 to Unicode you'll have
 216 to dump the database to SQL, run it through iconv or another conversion tool,
 217 and restore it. Sorry.
 218
 219
 220 === Upgrading from 1.1.x or earlier ===
 221
 222 This is less thoroughly tested, but should work.
 223
 224 You need to specify the *admin* database username and password to the
 225 installer in order for it to successfully upgrade the database structure.
 226 You may wish to manually change the GRANTs later.
 227
 228 If you have a very old database (earlier than organized MediaWiki releases
 229 in late August 2003) you may need to manually run some of the update SQL
 230 scripts in maintenance/archives before the installer is able to pick up
 231 with remaining updates.
 232
 233
 234 === Upgrading from UseModWiki or old "phase 2" Wikipedia code ===
 235
 236 There is a semi-maintained UseModWiki to MediaWiki conversion script at
 237 maintenance/importUseModWiki.php; it may require tweaking and customization
 238 to work for you.
 239
 240 Install a new MediaWiki first, then use the conversion script which will
 241 output SQL statements; direct these to a file and then run that into your
 242 database.
 243
 244 You will have to rebuild the links tables etc after importing.