Compatibility Considerations

MyISAM storage engine

MyISAM (the default storage engine for MySQL) does not support transactions. If there is an error while data is being saved to the database, XWiki will attempt to rollback the transaction to it's previous known good state. If you use MyISAM it will do nothing, leaving the database in whatever state it was in when the error occurred.

If you use MySQL with default engine MyISAM, you will most likely corrupt your database. We highly recommend using a storage engine such as InnoDB which supports transactions.

MySQL versions older than 5.0

XWiki does not fully work with MySQL versions 4.x or lower, due to several limitations of the way the SQL standards are implemented in MySQL, limited support for non-latin1 encodings, the flaky integration of Hibernate and MySQL 4, and other things. Most of the application works fine, but there are some parts that cannot easily be fixed, so if you must use MySQL 4.x, you're doing it on your own. Seriously, MySQL 4 is pretty old and buggy, you should consider upgrading.

Installation Steps

Follow these instructions:

  • Download and install MySQL 5.X or greater.
  • Start the MySQL server. You can do that in several ways. For example:
    mysqld --console
  • Create the wiki database. You can do that in several ways. For example:
    mysql -u root -e "create database xwiki default character set utf8"
  • Give all privileges to the xwiki user for accessing the xwiki database. You can do that in several ways. For example (if you get connections problems try localhost instead of the IP address below):
    mysql -u root -e "grant all privileges on xwiki.* to xwiki@localhost identified by 'xwiki'"
  • Please make sure that the DNS-name "localhost" is defined in your hosts-file (i.e. /etc/hosts)
  • You need to have the MySQL JDBC Driver JAR (named mysql-connector-java*.jar installed in XWiki's WAR file. If this file isn't present in XWiki's WEB-INF/lib directory you'll need to download it and copy it there. You can download it from the MySQL Connector/J Driver page or directly from the Maven Central Repository.

    You need version 5.x or higher, version 3.x doesn't handle Boolean data correctly and will either throw errors, or will make all documents hidden by default.

  • Now you need to tell XWiki to use MySQL. To do this, edit the WEB-INF/hibernate.cfg.xml file where you have expanded the XWiki WAR file and replace the matching properties with the following ones:
    <property name="connection.url">jdbc:mysql://localhost/xwiki</property>
    <property name="connection.username">xwiki</property>
    <property name="connection.password">xwiki</property>
    <property name="connection.driver_class">com.mysql.jdbc.Driver</property>
    <property name="dialect">org.hibernate.dialect.MySQLDialect</property>

By default MySQL only accepts packets smaller than 1MB. If you get the "Packet for query is too large (max_allowed_packet)" error then see the Packet too large error page. For example to increase the packet size to 32M you could start the MySQL server with:

mysqld --console --max_allowed_packet=32M

XWiki does not create automatically the Database Indexes. You can use the Admin Tools Application for that or create them manually


Unable to create the database

When running "mysql -u root -e "create database xwiki default character set utf8" you may get a

ERROR 1045 (28000): Access denied for user 'xwiki'@'localhost' (using password: YES)

This means that you have a password set for the MySQL root user but you are not specifying it in the console command. You must enter the -p parameter.

Can't create test file

When running mysqld --console you may get the following (especially if you're on Mac):

071111 17:20:53 [Warning] Can't create test file /usr/local/mysql-5.0.45-osx10.4-i686/data/Vincent.lower-test
071111 17:20:53 [Warning] Can't create test file /usr/local/mysql-5.0.45-osx10.4-i686/data/Vincent.lower-test
mysqld: Can't change dir to '/usr/local/mysql-5.0.45-osx10.4-i686/data/' (Errcode: 13)
071111 17:20:53 [ERROR] Aborting

To start MySQL run the following instead:

sudo /usr/local/mysql/bin/mysqld_safe --user=mysql

Data Truncation Error

If you receive an Exception like the following while installing/upgrading XWiki, chances are, that you are using an outdated version of MySQLConnectorJ.

Caused by: java.sql.BatchUpdateException: Data truncation: Out of
range value adjusted for column 'XWD_HIDDEN' at row 1
      at com.mysql.jdbc.PreparedStatement.executeBatch(
      at org.apache.commons.dbcp.DelegatingStatement.executeBatch(
      at org.apache.commons.dbcp.DelegatingStatement.executeBatch(
      at org.hibernate.jdbc.BatchingBatcher.doExecuteBatch(
      at org.hibernate.jdbc.AbstractBatcher.executeBatch(

On Linux, mysql-connector-java-3.x has proven not to work due to a bug in the handling of UTF-8, and lack of support for Boolean types.

Upgrading to the latest version of MySQLConnectorJ should solve such an error in most of the cases.


Get Connected