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