View source for Manual:Restoring a wiki from backup

<languages/>
<translate><!--T:1--> One should [[<tvar name=man>Special:MyLanguage/Manual:Backing up a wiki</tvar>|backup one's wiki]] regularly, even if one never needs to restore it: backups provide peace of mind.</translate>
<translate><!--T:2--> However, a backup is useless if one ''cannot'' restore, and practice restoring a backup prevents later anguish.</translate>
<translate><!--T:3--> Hence, these instructions.</translate>

<translate>
== Versions and upgrading == <!--T:4-->
</translate>
<translate><!--T:5--> The instructions on this page should apply more or less evenly to any given version of MediaWiki.</translate>
<translate><!--T:9--> You can restore the database to a more recent version of MediaWiki, but be sure to [[<tvar name=upgrade>Special:MyLanguage/Manual:Upgrading#Run the update script</tvar>|run the update script]].</translate>
<translate><!--T:7--> Restoring a database backup of a newer version into an older version of the software is not supported.</translate>

<translate>
=== File transfer === <!--T:10-->

<!--T:11-->
Unless you have direct access to the server hosting the wiki, (and even then) you will have to choose a method for transferring files:

<!--T:12-->
*Secure copy with [<tvar name=url>http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html</tvar> putty] or [[w:WinSCP|WinSCP]]
*[[w:SSH File Transfer Protocol|SSH File Transfer Protocol]] (SFTP)
*Using a [[w:File Transfer Protocol|FTP]] client.
*The hosting company might provide a file manager interface via the web browser, check with your provider.
*Some other method, there is a list of these at [[w:List of file transfer protocols|List of file transfer protocols]]

== Overview == <!--T:13-->

<!--T:14-->
# Re-create the database, user and permissions
# Import the database backup
# Import the MediaWiki files
# Check the configuration file
# Test

== Re-create the database, user and permissions == <!--T:15-->

<!--T:16-->
On the server on which you are restoring MediaWiki, ensure you have

<!--T:17-->
# a correctly-working instance of MySQL
# a MySQL user with appropriate permissions, if you can't use MySQL user root

<!--T:18-->
If you are restoring from backup due to database corruption, consider reinstalling MySQL!</translate>
<translate><!--T:101--> Once MySQL is working properly, create a new MySQL database and grant your user account permissions on the database listed below.</translate> <translate><!--T:93-->
You may need to consult the [<tvar name=mysql-doc>https://dev.mysql.com/doc/</tvar> MySQL documentation], your hosting provider's control panel documentation, or the documentation of any other utilities you are using for information on how to do this.</translate>
<translate><!--T:102--> From the MySQL prompt as MySQL user root you can:</translate>
<!-- I used &#39; in the second line instead of six times an ' which looks even more confusing ~~~ --> 

 CREATE DATABASE '''''wikidb''''';
 CREATE USER '''''wikidb_user''''' IDENTIFIED BY &#39;'''''wikidb_userpassword'''''&#39;;
 
 USE '''''wikidb''''';
 GRANT SELECT, UPDATE, INSERT, DELETE, ALTER, CREATE, INDEX, DROP, LOCK TABLES, USAGE ON '''''wikidb.*''''' TO '''''wikidb_user''''';

{{Note|1=<translate><!--T:19--> It doesn't matter if the database doesn't have the same name; indeed, in a commercial hosting environment, where database names are usually prefixed with a hosting account username, a different database name is almost guaranteed.</translate> <translate><!--T:94--> In addition, the username can differ, as can that user's password.</translate> <translate><!--T:95--> You will have to adjust the <tvar name=ls><code>LocalSettings.php</code></tvar> file on the new location accordingly.</translate>}}

<translate>
== Import the database backup == <!--T:20-->
</translate>
''See also [[Manual:Importing XML dumps]]''

<translate>
<!--T:21-->
Next, import your [[<tvar name=backup-db>Special:MyLanguage/Manual:Backing up a wiki#Database</tvar>|database backup]].</translate> <translate><!--T:96--> This will create the tables in the database and populate them with data.</translate> <translate><!--T:97-->
Importing takes a variable amount of time, depending upon the number of pages, users, edits, etc. in your wiki.

=== Methods === <!--T:22-->

==== From the command line using <code>mysqladmin</code> ==== <!--T:23-->

<!--T:24-->
If a database exists and you want to entirely replace it from the backup. To destroy the database:
</translate>

 mysqladmin -u '''''wikidb_user''''' -p drop '''''wikidb'''''

<translate><!--T:25--> Substituting as appropriate for <tvar name=wikidb_user><code>'''''wikidb_user'''''</code></tvar> and <tvar name=wikidb><code>'''''wikidb'''''</code></tvar>.</translate>
<translate><!--T:103--> The <tvar name=p><code>-p</code></tvar> parameter will prompt you for the password.</translate>

<translate>
<!--T:26-->
Then to create a new database:
</translate>

 mysqladmin -u '''''wikidb_user''''' -p create '''''wikidb'''''

<translate><!--T:121--> For example after backing up with [<tvar name=url>http://dev.mysql.com/doc/refman/5.0/en/mysqldump.html</tvar> mysqldump]:</translate>
 # <translate><!--T:122--> Don't do this now: This is how you might have created a backup earlier.</translate>
 mysqldump --default-character-set=binary --user='''''wikidb_user''''' --password='''''wikidb_userpassword''''' '''''wikidb''''' > '''''dump_of_wikidb.sql'''''
 # <translate><!--T:123--> The wikidatabase '''''wikidb''''' from which you backed up may have a different name</translate>
 # <translate><!--T:124--> than the wikidatabase '''''wikidb''''' you've created above. Of course '''''wikidb_user''''' and</translate>
 # <translate><!--T:125--> '''''wikidb_userpassword''''' may be different as well.</translate>

<translate>
<!--T:27-->
Make sure to specify the correct character set or the restore may fail, check <tvar name=1><code>LocalSettings.php</code></tvar> to find out which character set it is.

<!--T:28-->
To import <tvar name=dump><code>'''''dump_of_wikidb.sql'''''</code></tvar> from the command line you simply do:
</translate>

 mysql -u '''''wikidb_user''''' -p '''''wikidb''''' < '''''dump_of_wikidb.sql'''''

<translate>
<!--T:29-->
and afterwards [[<tvar name=m-upd>Special:MyLanguage/Manual:update.php</tvar>|if required]] do:
</translate>

 php '''''wikifolder'''''/maintenance/update.php
 # <translate><!--T:126--> Most people name their '''''wikifolder''''' simply "w", making this pathname</translate> 
 # <translate><!--T:127--> something like "htdocs/w/maintenance/update.php"</translate>

{{Note|1=<translate><!--T:30--> After using <tvar name=mysqldump><code>dump</code></tvar>, you shouldn't use <tvar name=mysqlimport><code>mysqlimport</code></tvar> to restore your wikidatabase, you should use <tvar name=sql><code>sql</code></tvar>.</translate> <translate><!--T:98--> Because <tvar name=mysqlimp2><code>mysqlimport</code></tvar> requires the data to be loaded in some delimited text format, eg. <tvar name=csv>CSV</tvar>, whereas the output of <tvar name=dump2><code>mysqldump</code></tvar> is a sequence of SQL statements.</translate>}} 

{{Note|1=<translate><!--T:31--> If not copying the old <tvar name=ls><code>LocalSettings.php</code></tvar> to a new install ensure the database prefix is set to the prior installation's in the new installation before running <tvar name=code><code>php update.php</code></tvar></translate>}}

<translate><!--T:32--> See also [<tvar name=1>https://dev.mysql.com/doc/refman/8.0/en/mysql-batch-commands.html</tvar> Executing SQL Statements from a Text File]</translate>

{{Note|1=<translate><!--T:33--> If your site is slow after importing a database dump, you may need to rebuild indexes.</translate> <translate><!--T:99--> See [<tvar name=after-import>http://stackoverflow.com/questions/3210310/after-importing-sql-files-indexes-in-place-but-not-actually-indexed</tvar> After importing sql files indexes in place, but not actually indexed]</translate>}}

<translate>
==== With the browser for phpMyAdmin ==== <!--T:34-->
</translate>
<translate><!--T:35--> Open the browser to your phpMyAdmin, login, choose the wiki database. (Check LocalSettings.php if you're not sure).</translate>
<translate><!--T:131--> Follow the instructions in the [<tvar name=url>https://docs.phpmyadmin.net/en/latest/faq.html#how-can-i-restore-upload-my-database-or-table-using-a-dump-how-can-i-run-a-sql-file</tvar> phpMyAdmin documentation].</translate>

<translate>
==== From an XML dump ==== <!--T:40-->

<!--T:41-->
''Main article: <tvar name=imp>{{ll|Manual:Importing XML dumps}}</tvar>''

<!--T:42-->
To import an [[<tvar name=1>Special:MyLanguage/Manual:DumpBackup.php</tvar>|XML dump]] into a wiki, use the command-line tool <tvar name=2>{{ll|Manual:importDump.php|importDump.php}}</tvar>. Do:
</translate>

 php '''''wikifolder'''''/maintenance/importDump.php --dbpass '''''wikidb_userpassword''''' --quiet '''''--wiki wikidb''''' '''''path-to-dumpfile/dumpfile.xml'''''
 php '''''wikifolder'''''/maintenance/rebuildrecentchanges.php

<translate>
<!--T:43-->
Substitute <tvar name=code1><code>'''''wikidb_userpassword'''''</code></tvar>, <tvar name=code2><code>'''''wikidb'''''</code></tvar> and <tvar name=code3><code>'''''path-to-dumpfile/dumpfile.xml'''''</code></tvar> as appropriate.

<!--T:44-->
Afterwards use <tvar name=1>{{ll|Manual:ImportImages.php|ImportImages.php}}</tvar> to import the images:
</translate>

 php '''''wikifolder'''''/maintenance/importImages.php '''''wikifolder_backup/images'''''

<translate>
== Import the MediaWiki files == <!--T:45-->
</translate>
''See also [[Manual:importImages.php]]''

<translate>
<!--T:46-->
Next, restore your [[<tvar name=backup-wiki-fs>Special:MyLanguage/Manual:Backing_up_a_wiki#File_system</tvar>|backup of the MediaWiki filesystem]]: this is the final "large" step in the restore process.

<!--T:47-->
* If you followed the [[<tvar name=backup-wiki->Special:MyLanguage/Manual:Backing_up_a_wiki</tvar>|backup manual]] instructions, and backed up the entire directory, this will include the images and extensions directories, plus custom skins, etc. and the configuration file.</translate> 
<translate>
<!--T:108-->
* If you backed up only portions of the directory, e.g. images, extensions, etc. then you will need to first upload/copy a fresh install of the MediaWiki files, then transfer the backed-up directories and files into the correct locations in the new filesystem.

=====To wipe and restore the wiki file system===== <!--T:48-->
</translate>
<translate><!--T:49--> Remember to also restore the file system components of the wiki that might be required, eg. images, logo, and extensions.</translate>
<translate><!--T:109--> Especially to edit <tvar name=1><code>LocalSettings.php</code></tvar> to check everything is correct.</translate>
<translate><!--T:110--> A sequence of Linux commands to wipe and restore the wiki file system could look like this:</translate>

 wget <nowiki>http://download.wikimedia.org/mediawiki/</nowiki>{{MW stable branch number}}/mediawiki-{{MW stable release number}}.tar.gz
 tar -xvzf mediawiki-{{MW stable release number}}.tar.gz
 rm mediawiki-{{MW stable release number}}.tar.gz
 rm -fR '''''wikifolder'''''/
 mv mediawiki-{{MW stable release number}} '''''wikifolder'''''
 rm -fR '''''wikifolder'''''/extensions/
 cp -R '''''wikifolder_backup'''''/extensions '''''wikifolder'''''/extensions

<translate><!--T:50--> Open the wiki from the browser and click on the ''Set up the wiki first'' link.</translate>
<translate><!--T:111--> See <tvar name=1>{{ll|Manual:Config script}}</tvar> for details.</translate>
<translate><!--T:112--> If needed, you can run the command-line installer <tvar name=wikifolder><code>php '''''wikifolder'''''/maintenance/install.php</code></tvar>.</translate>
<translate><!--T:113--> After this is done edit <tvar name=ls><code>LocalSettings.php</code></tvar> to suit the fresh install, restoring lines for extensions, etc.</translate>
<translate><!--T:114--> Restore from backup any other files, such as a custom logo and favicon to the correct paths.</translate>

<translate>
<!--T:51-->
If you've not installed as a root Linux/Unix user and the images and thumbnails don't work, you'll need to fix the owner or permissions '''recursively''' on the folder that has the uploaded images, usually in <tvar name=path>'''''wikifolder'''''/images</tvar>.

=== Notes === <!--T:52-->
</translate>
* <translate><!--T:53--> If following the latter process, ensure that your "fresh install" consists of the same version of MediaWiki as the old one did</translate>
* <translate><!--T:84--> Check that the upload directory (e.g. images in version 13) has the correct permissions set if using uploads; it needs to be writable by the web server.</translate>
* <translate><!--T:85--> Make sure any extension directories have the correct permissions as well (e.g. if linux: <tvar name=code1><code>chmod -R o=rx extensions</code></tvar> or <tvar name=code2><code>chmod -R o=rx includes</code></tvar>)</translate>
* <translate><!--T:54--> The best method to use when manually transferring a wiki from a windows platform to a Linux platform involves:</translate>
*# <translate><!--T:86--> Manually installing MediaWiki on the Linux platform from a tar file as outlined here: [[<tvar name=linux-install>Special:MyLanguage/Manual:Running MediaWiki on Debian GNU/Linux#Get latest MediaWiki</tvar>|Manual Install of Wiki]] (i.e. try not to use install from a automated package)</translate>
*# <translate><!--T:87--> Replacing the newly installed MediaWiki folder (e.g. <tvar name=code><code>/var/www/mediawiki</code></tvar>...) on your Linux machine with the MediaWiki base folder from your windows machine</translate>
*# <translate><!--T:88--> Updating your Linux machine's MySQL Database (e.g. wikidb) with the wiki database from your windows machine (i.e. use the backup and restore features of mysql as outlined above)</translate>
* <translate><!--T:55--> After importing a wiki database, even if the database can work, some minor problems may arise:</translate>
*# <translate><!--T:89--> Searchindex may need to be repaired: In phpMyAdmin, enter <tvar name=code><code>REPAIR TABLE ''wikidb''.searchindex;</code></tvar> for rebuilding the search index.</translate> <translate><!--T:115--> <tvar name=wikidb>''wikidb''</tvar> is your database's name.</translate>
*# <translate><!--T:90--> The collation of some rows may be changed. Cross check it with the original database.</translate>

<translate>
== Check the configuration file == <!--T:56-->

<!--T:57-->
The final task involves verification of, and possibly modifying, the <tvar name=ls><code>{{ll|Manual:LocalSettings.php|LocalSettings.php}}</code></tvar> file.
</translate>

* <translate><!--T:91--> If you are restoring onto the same server from which you backed up, you probably need not change anything.</translate>
* <translate><!--T:92--> If you are restoring onto a new server (i.e., if you are moving or duplicating the MediaWiki), certain entries will almost undoubtedly require changing, and you may need to change the database connection information as well.</translate>

<translate><!--T:58--> Check the following configuration options:</translate>

{|class="wikitable"
|-valign=top
! <translate><!--T:59--> Configuration option</translate>
! <translate><!--T:60--> Action required</translate>
! <translate><!--T:61--> Default/Example</translate>
|-valign=top
|'''{{ll|Manual:$IP|$IP}}'''||<translate><!--T:62--> Needs to be correct for the paths on the new server</translate>

<translate><!--T:63--> (Usually remains the same, so change is not required)</translate>
| <translate><!--T:64--> Default:</translate>
<pre>
 if( defined( 'MW_INSTALL_PATH' ) ) {
 	$IP = MW_INSTALL_PATH;
 } else {
 	$IP = dirname( __FILE__ );
 }
</pre>
|-valign=top
|'''{{ll|Manual:$wgScriptPath|$wgScriptPath}}'''||<translate><!--T:65--> Needs to be correct for the path on the new server</translate>
|
<code>$wgScriptPath	    = "'''''wikifolder'''''";</code><br/>
<translate><!--T:128--> Example:</translate><br/>
<code>$wgScriptPath	    = "/w";</code>
|-valign=top
|'''{{ll|Manual:$wgArticlePath|$wgArticlePath}}'''||<translate><!--T:66--> Needs to be correct for the path on the new server</translate>
|
<translate><!--T:129--> Examples:</translate><br/>
<code>$wgArticlePath      = "$wgScriptPath/$1";</code><br/>
<code>$wgArticlePath      = "/wiki/$1";</code>
|-valign=top
|'''{{ll|Manual:$wgDBserver|$wgDBserver}}'''||<translate><!--T:67--> Check the database server name is correct</translate>
|
<translate><!--T:130--> Example:</translate><br/>
<code>$wgDBserver         = "localhost";</code>
|-valign=top
|'''{{ll|Manual:$wgDBname|$wgDBname}}'''||<translate><!--T:68--> This might have changed in a shared hosting environment</translate>
|
<code>$wgDBname           = "'''''wikidb'''''";</code>
|-valign=top
|'''{{ll|Manual:$wgDBuser|$wgDBuser}}'''||<translate><!--T:69--> This might have changed in a shared hosting environment</translate>
|
<code>$wgDBuser           = "'''''wikidb_user'''''";</code>
|-valign=top
|'''{{ll|Manual:$wgDBpassword|$wgDBpassword}}'''||<translate><!--T:70--> Check this is correct for the new user</translate>
|
<code>$wgDBpassword       = "'''''wikidb_userpassword'''''";</code>
|}<!--- LIST OF PLACEHOLDERS USED ON THIS Manual: PAGE
<code>'''''wikifolder'''''</code>
<code>'''''wikidb'''''</code>
<code>'''''wikidb_user'''''</code>
<code>'''''wikidb_userpassword'''''</code> END OF LIST -->
<translate>
<!--T:71-->
You might also need to check the paths to [[w:Diff|diff3]], [[w:ImageMagick|ImageMagick]], etc.</translate>

<translate>
== Test == <!--T:72-->
</translate>
<translate><!--T:73--> At this point, attempt to access the wiki on the new server and use it.</translate>
<translate><!--T:116--> Log in as a sysop and a regular user and check that viewing, creating and editing pages and uploading files still works.</translate>
<translate><!--T:117--> You will need to fix any problems reported either by PHP or MediaWiki itself.</translate>

<translate>
=== Frequent problems === <!--T:74-->
</translate>
<translate><!--T:75--> After your move you might see PHP warnings stating that certain files could not be accessed.</translate>
<translate><!--T:118--> This is most likely caused by <tvar name=phab>[[phabricator:T37472]]</tvar>:</translate>
<translate><!--T:119--> The column md_deps in the [[<tvar name=module-deps>Special:MyLanguage/Manual:Module_deps_table</tvar>|module-deps]] table contains absolute file paths, which are used to locate the images and LESS files that CSS depends on.</translate>
<translate><!--T:120--> These paths will break when the wiki is e.g. moved to another folder or to another server.</translate>

<translate>
<!--T:76-->
Until this bug is solved, you can use this workaround to manually fix wrong entries in the module_deps table:
</translate>

<syntaxhighlight lang="sql">
SET @old='wiki.old-domain.org';
SET @new='wiki.new-domain.org';

UPDATE `module_deps` SET `md_deps` = REPLACE( `md_deps`, @old, @new );
</syntaxhighlight>
<translate><!--T:77--> This can be used to update wrong path segments and to fix the error.</translate>

<translate>
== See also == <!--T:78-->
</translate>
* {{ll|Manual:Backing up a wiki}}
* {{ll|Manual:Moving a wiki}}
* {{ll|Manual:Restoring wiki code from cached HTML}} <translate><!--T:79--> (if you don't have a successful backup)</translate>
* {{ll|Manual:Upgrading}}
* {{ll|Manual:Installing MediaWiki}}
* <translate><!--T:80--> Script:</translate> [[Fullsiterestore]]
* {{ll|Manual:importImages.php}}

<translate>
== References == <!--T:83-->
</translate>
<references />

[[Category:Import/Export{{#translation:}}|{{PAGENAME}}]]