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