1 This file provides an overview of the MediaWiki upgrade process. For help with
2 specific problems, check
4 * the documentation at http://meta.wikimedia.org
5 * the documentation at http://www.mediawiki.org
6 * the mediawiki-l mailing list archive at
7 http://mail.wikipedia.org/pipermail/mediawiki-l
8 * the bug tracker at http://bugzilla.wikimedia.org
10 for information and workarounds to common issues.
14 Documentation on upgrading to 1.7 can also be found at
15 http://www.mediawiki.org/wiki/Manual:Upgrading_to_1.7.
17 === Consult the release notes ===
19 Before doing anything, stop and consult the release notes supplied with the new
20 version of the software. This detail bug fixes, new features and functionality,
21 and any particular points that may need to be noted during the upgrade
26 It is imperative that, prior to attempting an upgrade of the database schema,
27 you take a complete backup of your wiki database and files and verify it. While
28 the upgrade scripts are somewhat robust, there is no guarantee that things will
29 not fail, leaving the database in an inconsistent state.
31 Refer to the MySQL or Postgres documentation for information on backing up a
32 database. For information on making copies of files, consult the documentation
33 for your operating system.
35 === Perform the file upgrade ===
37 Having downloaded the desired new version of the software, either as a package
38 from SourceForge, or via an export from Subversion, decompress the files as
39 needed, and replace the existing MediaWiki files with the new.
43 * The LocalSettings.php file
44 * The AdminSettings.php file, where it exists
45 * The extensions directory
46 * The images directory
48 If using an alternative uploads directory, preserve this; and if using custom
49 skins, preserve these too. The core code is now updated.
51 === Perform the database upgrade ===
53 You will need an AdminSettings.php file set up in the correct format; see
54 AdminSettings.sample in the wiki root for more information and examples.
56 From the command line, browse to the maintenance directory and run the
57 update.php script to check and update the schema. This will insert missing
58 tables, update existing tables, and move data around as needed. In most cases,
59 this is successful and nothing further needs to be done.
61 === Check configuration settings ===
63 The names of configuration variables, and their default values and purposes,
64 can change between release branches, e.g. $wgDisableUploads in 1.4 is replaced
65 with $wgEnableUploads in later versions. When upgrading, consult the release
66 notes to check for configuration changes which would alter the expected
67 behaviour of MediaWiki.
71 It makes sense to test your wiki immediately following any kind of maintenance
72 procedure, and especially after upgrading; check that page views and edits work
73 normally and that special pages continue to function, etc. and correct errors
74 and quirks which reveal themselves.
76 == Upgrading from 1.7 wikis ==
78 $wgDefaultUserOptions now contains all the defaults, not only overrides.
79 If you're setting this as a complete array(), you may need to change it
80 to set only specific items as recommended in DefaultSettings.php.
83 == Upgrading from 1.6 wikis ==
85 $wgLocalTZoffset was in hours, it is now using minutes.
86 Link autonumbering got fixed (#5918) for protocols other than http.
87 - 'irc://irc.server.tld/' render as a link with a chat icon
88 - '[irc://irc.server.tld]' render as an autonumbered link: [1]
90 == Upgrading from pre-1.5 wikis ==
92 Major changes have been made to the schema from 1.4.x. The updater
93 has not been fully tested for all conditions, and might well break.
95 On a large site, the schema update might take a long time. It might
96 explode, or leave your database half-done or otherwise badly hurting.
98 Among other changes, note that Latin-1 encoding (ISO-8859-1) is
99 no longer supported. Latin-1 wikis will need to be upgraded to
100 UTF-8; an experimental command-line upgrade helper script,
101 'upgrade1_5.php', can do this -- run it prior to 'update.php' or
104 If you absolutely cannot make the UTF-8 upgrade work, you can try
105 doing it by hand: dump your old database, convert the dump file
106 using iconv as described here:
107 http://portal.suse.com/sdb/en/2004/05/jbartsh_utf-8.html
108 and then reimport it. You can also convert filenames using convmv,
109 but note that the old directory hashes will no longer be valid,
110 so you will also have to move them to new destinations.
113 * A number of additional UI messages have been chagned from HTML to
114 wikitext, and will need to be manually fixed if customized.
116 === Configuration changes from 1.4.x: ===
118 $wgDisableUploads has been replaced with $wgEnableUploads.
120 $wgWhitelistAccount has been replaced by the 'createaccount' permission
121 key in $wgGroupPermissions. To emulate the old effect of setting:
122 $wgWhitelistAccount['user'] = 0;
124 $wgGroupPermissions['*']['createaccount'] = false;
126 $wgWhitelistEdit has been replaced by the 'edit' permission key.
127 To emulate the old effect of setting:
128 $wgWhitelistEdit = true;
130 $wgGroupPermissions['*']['edit'] = false;
132 If $wgWhitelistRead is set, you must also disable the 'read' permission
133 for it to take affect on anonymous users:
134 $wgWhitelistRead = array( "Main Page", "Special:Userlogin" );
135 $wgGroupPermissions['*']['read'] = false;
137 Note that you can disable/enable several other permissions by modifying
138 this configuration array in your LocalSettings.php; see DefaultSettings.php
139 for the complete default permission set.
141 If using Memcached, you must enabled it differently now:
142 $wgUseMemCached = true;
143 should be replaced with:
144 $wgMainCacheType = CACHE_MEMCACHED;
147 === Web installer ===
149 You can use the web-based installer wizard if you first remove the
150 LocalSettings.php (and AdminSettings.php, if any) files; be sure to
151 give the installer the same information as you did on the original
152 install (language/encoding, database name, password, etc). This will
153 also generate a fresh LocalSettings.php, which you may need to customize.
155 You may change some settings during the install, but be very careful!
156 Changing the encoding in particular will generally leave you with a
157 lot of corrupt pages, particularly if your wiki is not in English.
159 === Command-line upgrade ===
161 Additionally, as of 1.4.0 you can run an in-place upgrade script from
162 the command line, keeping your existing LocalSettings.php. This requires
163 that you create an AdminSettings.php giving an appropriate database user
164 and password with privileges to modify the database structure.
166 Once the new files are in place, go into the maintenance subdirectory and
171 See caveats below on upgrading from 1.3.x or earlier.
176 To upgrade an existing MediaWiki installation, first BACK UP YOUR WIKI!
177 If something goes wrong, you want to be able to start again.
179 Your image files, configuration, etc can simply be copied or archived as
180 you would any other files. (Make sure that the contents of your
181 LocalSettings.php are not accidentally made public, as this contains
182 a database password.)
184 To back up the database, use the tools provided by your service provider
185 (if applicable) or the standard mysqldump or pg_dump programs.
187 For general help on mysqldump:
188 http://dev.mysql.com/doc/mysql/en/mysqldump.html
190 WARNING: If using MySQL 4.1.x, mysqldump's charset conversion may in
191 some cases damage data in your wiki. If necessary, set the charset
192 option to 'latin1' to avoid the conversion. Fore more info see:
193 http://mail.wikipedia.org/pipermail/wikitech-l/2004-November/026359.html
195 For general help on pg_dump:
196 http://www.postgresql.org/docs/current/static/app-pgdump.html
203 Postgres support is new, and much of the upgrade instructions may
204 not apply. The schema was changed significantly from 1.7 to 1.8,
205 so you will need to at least use the update.php or web installer,
209 === Upgrading from 1.4.2 or earlier ===
211 1.4.3 has added new fields to the sitestats table. These fields are
212 optional and help to speed Special:Statistics on large sites. If you
213 choose not to run the database upgrades, everything will continue to
216 You can apply the update by running maintenance/update.php, or
217 manually run the SQL commands from this file:
218 maintenance/archives/patch-ss_total_articles.sql
221 === Upgrading from 1.4rc1 or earlier betas ===
223 The logging table has been altered from 1.4beta4 to 1.4beta5
224 and again in 1.4.0 final. Copy in the new files and use the web
225 installer to upgrade, or the command-line maintenance/update.php.
227 If you cannot use the automated installers/updaters, you may
228 update the table by manually running the SQL commands in these
230 maintenance/archives/patch-log_params.sql
231 maintenance/archives/patch-logging-title.sql
234 === Upgrading from 1.3.x ===
236 This should generally go smoothly.
238 If you keep your LocalSettings.php, you may need to change the style paths
239 to match the newly rearranged skin modules. Change these lines:
240 $wgStylePath = "$wgScriptPath/stylesheets";
241 $wgStyleDirectory = "$IP/stylesheets";
242 $wgLogo = "$wgStylePath/images/wiki.png";
245 $wgStylePath = "$wgScriptPath/skins";
246 $wgStyleDirectory = "$IP/skins";
247 $wgLogo = "$wgStylePath/common/images/wiki.png";
249 As well as new messages, the processing of some messages has changed.
250 If you have customized them, please compare the new format using
251 Special:Allmessages or the relevant LanguageXX.php files:
254 editingcomment (was named commentedit)
255 editingsection (was named sectionedit)
266 Note that the 1.3 beta releases included a potential vulnerability if PHP
267 is configured with register_globals on and the includes directory is
268 served to the web. For general safety, turn register_globals *off* if you
269 don't _really_ need it for another package.
271 If your hosting provider turns it on and you can't turn it off yourself,
272 send them a kind note explaining that it can expose their servers and their
273 customers to attacks.
276 === Upgrading from 1.2.x ===
278 If you've been using the MediaWiki: namespace for custom page templates,
279 note that things are a little different. The Template: namespace has been
280 added which is more powerful -- templates can include parameters for
283 If you were using custom MediaWiki: entries for text inclusions, they
284 will *not* automatically be moved to Template: entries at upgrade time.
285 Be sure to go through and check that everything is working properly;
286 you can move them manually or you can try using moveCustomMessages.php
287 in maintenance/archives to do it automatically, but this might break things.
289 Also, be sure to pick the correct character encoding -- some languages were
290 only available in Latin-1 on 1.2.x and are now available for Unicode as well.
291 If you want to upgrade an existing wiki from Latin-1 to Unicode you'll have
292 to dump the database to SQL, run it through iconv or another conversion tool,
293 and restore it. Sorry.
296 === Upgrading from 1.1.x or earlier ===
298 This is less thoroughly tested, but should work.
300 You need to specify the *admin* database username and password to the
301 installer in order for it to successfully upgrade the database structure.
302 You may wish to manually change the GRANTs later.
304 If you have a very old database (earlier than organized MediaWiki releases
305 in late August 2003) you may need to manually run some of the update SQL
306 scripts in maintenance/archives before the installer is able to pick up
307 with remaining updates.
310 === Upgrading from UseModWiki or old "phase 2" Wikipedia code ===
312 There is a semi-maintained UseModWiki to MediaWiki conversion script at
313 maintenance/importUseModWiki.php; it may require tweaking and customization
316 Install a new MediaWiki first, then use the conversion script which will
317 output SQL statements; direct these to a file and then run that into your
320 You will have to rebuild the links tables etc after importing.