Use a Container-Managed Data Source
Last modified by Eleni Cojocariu on 2026/10/29 11:10
Steps
Take XWiki's database connections from a JNDI data source managed by the servlet container, instead of the pool XWiki opens itself from WEB-INF/hibernate.cfg.xml.
- Copy the JDBC driver of your database into the library directory of the servlet container rather than into the WEB-INF/lib directory of the XWiki web application, for example $CATALINA_HOME/lib on Tomcat.
- Declare a data source named jdbc/xwiki in the servlet container. On Tomcat, declare it as a resource, either from the Manager web application or in the conf/Catalina/<host>/<webapp-name>.xml file.
- Give that data source the settings XWiki's own pool was providing, since they do not travel with the connections: an isolation level of READ COMMITTED, at least 50 connections and a cache of 20 prepared statements per connection, which are the values XWiki ships in WEB-INF/hibernate.cfg.xml. READ COMMITTED is a requirement rather than a preference: at the REPEATABLE READ that MySQL and MariaDB default to, an XClass saved while a document using it is being loaded is cached as non-existing. The option names are the container's own, and Declare an XWiki Data Source in WildFly and Declare an XWiki Data Source in GlassFish give them for those two.
- Replace the connection settings in your database's block of WEB-INF/hibernate.cfg.xml with the name of that data source, removing the hibernate.connection.url, hibernate.connection.username, hibernate.connection.password and hibernate.connection.driver_class properties:
<property name="hibernate.connection.datasource">java:comp/env/jdbc/xwiki</property> <property name="hibernate.dialect">org.hibernate.dialect.HSQLDialect</property> - Restart the servlet container.
- Verify that XWiki starts and serves its pages, and that the servlet container reports connections being taken from the jdbc/xwiki data source.
FAQ
Do I still need a connection provider class?
No. Leave hibernate.connection.provider_class unset, so that Hibernate uses its own data source provider. XWiki's DBCPConnectionProvider builds its own pool from the connection URL and does not handle container-managed data sources.
Do I have to set the dialect?
No. Hibernate detects it from the database it connects to, so set hibernate.dialect explicitly only if you want to pin a specific dialect.
