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