MySQL Installation

Version 49.3 by Vincent Massol on 2019/09/17

Compatibility Considerations

Currently we seem to have some problem with MySQL server 8.x or MySQL connector 8.x. It is recommended to use MySQL server 5.7.x or earlier (and connector 5.1.x) if you're using XWiki 10.x (the issue is fixed if you're on XWiki 11.3+).

See Database support strategy for the supported versions.

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 its 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 the 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 parts of the application work fine, but there are some parts that cannot be easily fixed, so if you must use MySQL 4.x, you're doing it on your own. MySQL 4 is pretty old and buggy so we recommend 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 use mysqld --console
  • Create the wiki database. You can use the name you want for the database, but you will have to set the hibernate configuration file and xwiki.cfg file accordingly.

    You can create the database in several ways. For example use:

    mysql -u root -e "create database xwiki default character set utf8 collate utf8_bin"
  • Give privileges to the xwiki user for accessing and creating databases (for the multi wiki support). Specifically the xwiki users needs permissions to be able to execute CREATE DATABASE, DROP SCHEMA, and then all CRUD operations on tables. Note that the command below should be tuned to be more restrictive as granting all permissions is not required:
    mysql -u root -e "grant all privileges on *.* to xwiki@localhost identified by 'xwiki'"
  • If the above command fails with a password-does-not-meet-requirements error, uninstall the MySQL password_validate plugin or pick a more complex password and update the password used by default in hibernate.cfg.xml:
    mysql -u root -p -e "uninstall plugin validate_password;"
  • 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 the 5.x version or higher. The 3.x version 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.MySQL5InnoDBDialect</property>
    <property name="connection.useUnicode">true</property>
    <property name="connection.characterEncoding">UTF-8</property>
    • By default MySQL only accepts packets that are 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
      or you can modify directly the my.cnf configuration file to set this value permanently.
    • If an empty XWiki starts with no errors, but you are unable to upload the default set of pages (XAR file) try to increase the max_allowed_packet parameter as shown above.


Convert a database from latin1 (or collation utf8_ci) to utf8/utf8_bin



mysql_cmd="mysql -u root"

$mysql_cmd -e "ALTER DATABASE $db CHARACTER SET utf8 COLLATE utf8_unicode_ci;"

TBL_LIST=$($mysql_cmd -N -s -r -e "use $db;show tables;")

for tbl_name in $TBL_LIST;
$mysql_cmd -e "alter table $db.$tbl_name convert to character set $to_character_set collate $to_collation;"

echo "Here the result of the operation:"

Convert from MyISAM to InnoDB



DATABASES=$(mysql -N -s -r -e 'show databases'|grep -v ^information_schema$|grep -v ^mysql$)

for db in $DATABASES

echo "Working on database $db..."
echo ""

TABLES=$(mysql -N -s -r -e "show tables from $db;")

for tb in $TABLES



$MYSQL_COMMAND -e "SELECT table_name,Engine,table_collation FROM information_schema.tables WHERE table_schema = DATABASE();"

echo ""
echo ""



Unable to login to MySQL Console

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) error.
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 also use the -p parameter. Using this you will be prompted to enter the password and be allowed to login to the MySQL console and create the database.

Can't create test file

When running mysqld --console you may get the following (especially if you're on a 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 command 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.

HTTP 500 Error

HTTP Status 500 -

type Exception report


descriptionThe server encountered an internal error () that prevented it from fulfilling this request.


javax.servlet.ServletException: com.xpn.xwiki.XWikiException: Error number 3 in 0: Could not initialize main XWiki context
Wrapped Exception: Error number 3001 in 3: Cannot load class from param
Wrapped Exception: Error number 0 in 3: Exception while hibernate execute
Wrapped Exception: Could not create a DBCP pool. There is an error in the hibernate configuration file, please review it.

root cause

com.xpn.xwiki.XWikiException: Error number 3 in 0: Could not initialize main XWiki context
Wrapped Exception: Error number 3001 in 3: Cannot load class from param
Wrapped Exception: Error number 0 in 3: Exception while hibernate execute
Wrapped Exception: Could not create a DBCP pool. There is an error in the hibernate configuration file, please review it.

In this case, try to disable skip-networking in MySQL *.ini file. Thanks a lot M Rawash (see his comment below).

Unknown database 'xwiki'

If you get the following error:

Caused by: class com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Unknown database 'xwiki'
    at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
    at sun.reflect.NativeConstructorAccessorImpl.newInstance(
    at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(
    at java.lang.reflect.Constructor.newInstance(
    at com.mysql.jdbc.Util.handleNewInstance(
    at com.mysql.jdbc.Util.getInstance(
    at com.mysql.jdbc.SQLError.createSQLException(
    at com.mysql.jdbc.MysqlIO.checkErrorPacket(
    at com.mysql.jdbc.MysqlIO.checkErrorPacket(
    at com.mysql.jdbc.MysqlIO.sendCommand(
    at com.mysql.jdbc.MysqlIO.sqlQueryDirect(
    at com.mysql.jdbc.ConnectionImpl.execSQL(
    at com.mysql.jdbc.ConnectionImpl.setCatalog(
    at org.apache.commons.dbcp.DelegatingConnection.setCatalog(
    at org.apache.commons.dbcp.DelegatingConnection.setCatalog(
    at org.apache.commons.dbcp.PoolingDataSource$PoolGuardConnectionWrapper.setCatalog(
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(
    at java.lang.reflect.Method.invoke(
    at org.hibernate.jdbc.BorrowedConnectionProxy.invoke(
    at com.sun.proxy.$Proxy47.setCatalog(Unknown Source)

It means that XWiki could connect to your database but there's no xwiki schema available there. This is the default name of the schema XWiki is looking for, for the main wiki database. 

It probably means you've created a database named other than xwiki (for example you might have created a database named abcd and set the following connection URL in your hibernate.cfg file: <property name="connection.url">jdbc:mysql://localhost/abcd</property>).

If this is the case you need to tell XWiki that you're using a different schema by setting the xwiki.db configuration property.

MySQLSyntaxErrorException: Row size too large (> 8126)

if you get the following error:

MySQLSyntaxErrorException: Row size too large (> 8126).
Changing some columns to TEXT or BLOB or using ROW_FORMAT=DYNAMIC or ROW_FORMAT=COMPRESSED may help.
In current row format, BLOB prefix of 768 bytes is stored inline.

When you are using a MySQL Server 5.6.20 you can get a "row size too large error."
In the release notes, it is explained that a innodb_log_file_size which is too small will trigger a "Row size too large error."

You can solve the problem by changing the innodb_log_file_size in the my.ini text file.
Find more details in the link below.

Get Connected