Steps

o use MySQL as XWiki's database, the database has to use the InnoDB storage engine and a UTF-8 character set with a binary collation, for the reasons given in MySQL Storage Engine and Character Set.

1. Make sure you have already installed and configured a servlet container for XWiki (e.g. Tomcat or Jetty), with the XWiki WAR file extracted/deployed.
2. Install MySQL using whatever method suits your platform: a distribution package, MySQL's own installer, or a container image. See the Database support strategy for the supported versions.
3. Download the MySQL JDBC driver and copy it into the XWiki webapp's WEB-INF/lib directory.

   Get it from the MySQL Connector/J page or from Maven Central, and use the latest version. The JAR file is named mysql-connector-j-*.jar, from the com.mysql:mysql-connector-j artifact.

4. Create the xwiki database with the required encoding. Log in as root with mysql -u root -p, then run:

   CREATE DATABASE xwiki CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;

   The database may have another name, but that name must then also be set as the xwiki.db property in the WEB-INF/xwiki.cfg file, as described in the names of the database schemas.

5. Create the xwiki database user:

   CREATE USER 'xwiki'@'localhost' IDENTIFIED BY 'xwiki';

   Outside an evaluation setup, replace 'xwiki' with a strong password.

6. Grant that user privileges on every database:

   GRANT ALL PRIVILEGES ON *.* TO 'xwiki'@'localhost';
   FLUSH PRIVILEGES;

7. Configure XWiki to use MySQL. Open WEB-INF/hibernate.cfg.xml, uncomment the MySQL configuration block, comment out the other database configurations, and set the connection values:

       <property name="hibernate.connection.url">jdbc:mysql://localhost/xwiki?useSSL=false</property>
       <property name="hibernate.connection.username">xwiki</property>
       <property name="hibernate.connection.password">xwiki</property>
       <property name="hibernate.connection.driver_class">com.mysql.cj.jdbc.Driver</property>
       <property name="hibernate.dbcp.poolPreparedStatements">true</property>
       <property name="hibernate.dbcp.maxOpenPreparedStatements">20</property>
   
       <property name="hibernate.connection.charSet">UTF-8</property>
       <property name="hibernate.connection.useUnicode">true</property>
       <property name="hibernate.connection.characterEncoding">utf8</property>

   Adjust the host, port or database name if your setup differs, and configure SSL for a production environment.

8. Restart XWiki to apply the changes.
9. Open your wiki in a browser. XWiki connects to MySQL, creates its tables on the first start, and serves the wiki without a database error.

FAQ

Why is my "mysql -u root" connection refused?

Because a password is set for the MySQL root user and none was supplied, which MySQL reports as ERROR 1045 (28000): Access denied for user 'root'@'localhost' (using password: NO). Add the -p parameter, which prompts for the password.

Do I need the hibernate.connection.driver_class property?

No. A MySQL 8+ JDBC driver registers itself, so the property is not needed and only produces a warning, as the comment in the shipped hibernate.cfg.xml says.

Can the xwiki user be granted less than all privileges?

Yes, as long as it keeps CREATE DATABASE, DROP SCHEMA and full read/write rights on its own tables: XWiki gives every subwiki a database of its own, and creating one is what needs those rights.

XWiki does not start on MySQL. Where do I look?

The log names the failure, and each of the usual ones has its own page: an unreachable server, an unknown database, an unrecognized server time zone, a query that is too large and a row that is too large.

More

To find more about the current topic, you can search, select an highlighted topic, or use the table below and filter the columns to narrow your choices.

Related

• Install and Configure a Relational Database.
• Configure MariaDB.
• Database Administration.
• Database Support Strategy.