MySQL Installation
Compatibility Considerations
See Database support strategy for the supported versions.
XWiki expects the database to use utf8 or utf8mb4 encoding with collation *_bin and it's highly recommended to use utf8mb4 (and utf8mb4_bin) which is the default since MySQL 8.
MyISAM storage engine
MyISAM (the default storage engine for MySQL until release 5.5.5 in 2010) does not support transactions. If there is an error while data is being saved to the database, XWiki will attempt to roll back 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.
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.
MySQL versions older than 5.7 and utf8mb4
If you use utf8mb4 encoding, you won't be able to use a version of MySQL older than 5.7 out of the box because of a limitation in the default maximum size of the keys and the default row format.
JDBC Driver Version
- It's recommended to use the latest version of the MySQL JDBC driver (8.x).
Installation Steps
Follow these instructions:
- Install MySQL 5.7 or greater and start it. It's always recommended to use the best method depending on your environment (for example a package on a Linux server), you can download it on MySQL if you want to manually install it.
- 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 utf8mb4 collate utf8mb4_bin" - Create the xwiki user with password xwikimysql -u root -e "CREATE USER 'xwiki'@'localhost' IDENTIFIED BY 'xwiki'";
- In XWiki, each subwiki has its own dedicated database, therefore, to use this feature, you will need to give privileges to the xwiki user for accessing and creating any database databases. 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 could be tuned to be more restrictive depending on your need:mysql -u root -e "grant all privileges on *.* to xwiki@localhost"
- 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.
- 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.cj.jdbc.Driver</property>
<property name="connection.useUnicode">true</property>
<property name="connection.characterEncoding">UTF-8</property>
Indexes
create index xwl_value on xwikilargestrings (xwl_value(50));
create index xwd_parent on xwikidoc (xwd_parent(50));
create index xwd_class_xml on xwikidoc (xwd_class_xml(20));
create index xda_docid1 on xwikiattrecyclebin (xda_docid);
create index solr_iterate_all_documents on xwikidoc (XWD_WEB(500), XWD_NAME(253), XWD_LANGUAGE(5), XWD_VERSION(10));
// Only required if you use stats (feature is off by default)
create index xws_number on xwikistatsdoc (XWS_NUMBER);
create index xws_classname on xwikistatsdoc (XWS_CLASSNAME);
create index xwr_number on xwikistatsreferer (XWR_NUMBER);
create index xwr_classname on xwikistatsreferer (XWR_CLASSNAME);
create index xwr_referer on xwikistatsreferer (XWR_REFERER(50));
create index xwv_user_agent on xwikistatsvisit (XWV_USER_AGENT(255));
create index xwv_cookie on xwikistatsvisit (XWV_COOKIE(255));
create index xwv_classname on xwikistatsvisit (XWV_CLASSNAME);
create index xwv_number on xwikistatsvisit (XWV_NUMBER);
Tips
MySQL 8
- If you're using MySQL 8+ you'll need to configure MySQL with native password: default-authentication-plugin=mysql_native_password.
- You'll also be able to switch from com.mysql.jdbc.Driver to com.mysql.cj.jdbc.Driver JDBC driver (since the previous driver class is now deprecated).
- If you get the following error then you'll need to force the timezone to use either by setting it in:
- The MySQL conf file on the server
- In the XWiki hibernate.cfg.xml file in the hibernate.connection.serverTimezone property (e.g. <property name="hibernate.connection.serverTimezone">Europe/Berlin</property>).
- In the XWiki hibernate.cfg.xml file inside the JDBC URL string as in jdbc:mysql://localhost:3306/myschema?serverTimezone=UTC
The server timezone value 'CDT' is unrecognized or represents more than one timezone. You must configure either the server or JDBC driver (via the serverTimezone configuration property) to use a more specifc timezone value if you want to utilize timezone support.For more details see this explanation post.
Convert a database to utf8mb4/utf8mb4_bin
db="${1:-xwiki}"
to_character_set=utf8mb4
to_collation=utf8mb4_bin
mysql_cmd="mysql -u root"
echo "Changing ($db) character to $to_collation."
$mysql_cmd -e "ALTER DATABASE $db CHARACTER SET $to_character_set COLLATE $to_collation;"
TBL_LIST=$($mysql_cmd -N -s -r -e "use $db;show tables;")
for tbl_name in $TBL_LIST;
do
$mysql_cmd -e "SET FOREIGN_KEY_CHECKS=0; alter table $db.$tbl_name convert to character set $to_character_set collate $to_collation; SET FOREIGN_KEY_CHECKS=1;"
done
echo "Here the result of the operation:"
$mysql_cmd -e "USE $db;SELECT TABLE_CATALOG, TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, COLLATION_NAME FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA=DATABASE();"
ALTER TABLE xwikistatsreferer MODIFY XWR_REFERER LONGTEXT;
ALTER TABLE xwikistatsvisit MODIFY XWV_USER_AGENT LONGTEXT, MODIFY XWV_COOKIE LONGTEXT;
ALTER TABLE xwikipreferences MODIFY XWP_LEFT_PANELS LONGTEXT, MODIFY XWP_RIGHT_PANELS LONGTEXT, MODIFY XWP_DOCUMENT_BUNDLES LONGTEXT;
You can also look at this snippet to perform this conversion inside XWiki.
Convert from MyISAM to InnoDB
MYSQL_COMMAND=mysql
TO_ENGINE=INNODB
DATABASES=$(mysql -N -s -r -e 'show databases'|grep -v ^information_schema$|grep -v ^mysql$)
for db in $DATABASES
do
echo "Working on database $db..."
echo ""
TABLES=$(mysql -N -s -r -e "show tables from $db;")
for tb in $TABLES
do
$MYSQL_COMMAND -e "ALTER TABLE $db.$tb ENGINE = $TO_ENGINE;"
done
$MYSQL_COMMAND -e "SELECT table_name,Engine,table_collation FROM information_schema.tables WHERE table_schema = DATABASE();"
echo ""
echo ""
done
Troubleshooting
"Incorrect string value" error with MySQL connector between 8.0.29 and 8.0.32
There seems to be a regression in MySQL connector 8.0.29 that leads to using the default encoding even when it's explicitly indicated in the hibernate.cfg.xml file (which is what you have in the MySQL configuration recommendation provided by XWiki). We are currently searching what could be the cause and find a workaround in https://jira.xwiki.org/browse/XWIKI-19853 but in the (and in general) it's recommended to make sure that you are running XWiki with the right default Java encoding. You can do that by making sure Java is run with -Dfile.encoding=utf8 (this is generally the default in standard Tomcat packages of various Linux distribution, but it might not always be the case).
Unable to login to MySQL Console
When running mysql -u root -e "create database xwiki default character set utf8mb4
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
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:
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.
range value adjusted for column 'XWD_HIDDEN' at row 1
at com.mysql.jdbc.PreparedStatement.executeBatch(PreparedStatement.java:894)
at org.apache.commons.dbcp.DelegatingStatement.executeBatch(DelegatingStatement.java:294)
at org.apache.commons.dbcp.DelegatingStatement.executeBatch(DelegatingStatement.java:294)
at org.hibernate.jdbc.BatchingBatcher.doExecuteBatch(BatchingBatcher.java:48)
at org.hibernate.jdbc.AbstractBatcher.executeBatch(AbstractBatcher.java:246)
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
type Exception report
message
descriptionThe server encountered an internal error () that prevented it from fulfilling this request.
exception
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 com.xpn.xwiki.store.migration.hibernate.XWikiHibernateMigrationManager from param xwiki.store.migration.manager.class
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 com.xpn.xwiki.store.migration.hibernate.XWikiHibernateMigrationManager from param xwiki.store.migration.manager.class
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:
at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:57)
at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
at java.lang.reflect.Constructor.newInstance(Constructor.java:526)
at com.mysql.jdbc.Util.handleNewInstance(Util.java:408)
at com.mysql.jdbc.Util.getInstance(Util.java:383)
at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:1062)
at com.mysql.jdbc.MysqlIO.checkErrorPacket(MysqlIO.java:4226)
at com.mysql.jdbc.MysqlIO.checkErrorPacket(MysqlIO.java:4158)
at com.mysql.jdbc.MysqlIO.sendCommand(MysqlIO.java:2615)
at com.mysql.jdbc.MysqlIO.sqlQueryDirect(MysqlIO.java:2776)
at com.mysql.jdbc.ConnectionImpl.execSQL(ConnectionImpl.java:2834)
at com.mysql.jdbc.ConnectionImpl.setCatalog(ConnectionImpl.java:5456)
at org.apache.commons.dbcp.DelegatingConnection.setCatalog(DelegatingConnection.java:374)
at org.apache.commons.dbcp.DelegatingConnection.setCatalog(DelegatingConnection.java:374)
at org.apache.commons.dbcp.PoolingDataSource$PoolGuardConnectionWrapper.setCatalog(PoolingDataSource.java:333)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
at java.lang.reflect.Method.invoke(Method.java:606)
at org.hibernate.jdbc.BorrowedConnectionProxy.invoke(BorrowedConnectionProxy.java:74)
at com.sun.proxy.$Proxy47.setCatalog(Unknown Source)
at com.xpn.xwiki.store.XWikiHibernateBaseStore.setDatabase(XWikiHibernateBaseStore.java:729)
at com.xpn.xwiki.store.XWikiHibernateBaseStore.beginTransaction(XWikiHibernateBaseStore.java:911)
at com.xpn.xwiki.store.XWikiHibernateBaseStore.beginTransaction(XWikiHibernateBaseStore.java:843)
at com.xpn.xwiki.store.XWikiHibernateStore.loadXWikiDoc(XWikiHibernateStore.java:830)
...
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:
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.
http://dev.mysql.com/doc/relnotes/mysql/5.6/en/news-5-6-20.html
