Steps

To configure XWiki to use Apache Derby in embedded mode, which runs inside the same JVM as XWiki and needs no database server to install or start:

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. Download the Derby release built for the Java version your servlet container runs, from the Apache Derby website or from the Maven Central repository. Derby 10.17 needs Java 21 or later and Derby 10.16 needs Java 17 or later.
3. Copy derby.jar, derbyshared.jar and derbytools.jar into the WEB-INF/lib directory of the expanded XWiki WAR. XWiki ships none of them.

   $ cp derby.jar derbyshared.jar derbytools.jar /path/to/webapps/xwiki/WEB-INF/lib/

4. Edit the WEB-INF/hibernate.cfg.xml file, comment out the database block that is currently active and uncomment the Derby one, replacing /some/path/xwikidb with the directory where you want the database files.

       <property name="hibernate.connection.url">jdbc:derby:/some/path/xwikidb;create=true</property>
       <property name="hibernate.connection.driver_class">org.apache.derby.jdbc.EmbeddedDriver</property>
       <property name="hibernate.dialect">org.hibernate.dialect.DerbyDialect</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>
   
       <mapping resource="xwiki.derby.hbm.xml"/>
       <mapping resource="feeds.hbm.xml"/>
       <mapping resource="instance.hbm.xml"/>
       <mapping resource="notification-filter-preferences.hbm.xml"/>

5. Add the mail sender mapping to that list, which the shipped Derby block is missing.

       <mapping resource="mailsender.hbm.xml"/>

6. Start or restart the application server. XWiki creates the database directory and its tables on the first run.
7. Verify that the directory you configured now exists and holds Derby's service.properties file and seg0 directory.

   $ ls /some/path/xwikidb
   README_DO_NOT_TOUCH_FILES.txt  db.lck  dbex.lck  log  seg0  service.properties  tmp

FAQ

Why three jar files, when Derby used to be one?

Since Derby 10.15 the embedded engine is split across several jars, and org.apache.derby.jdbc.EmbeddedDriver, the class the configuration names, is the one that moved to derbytools.jar.

Do I have to set a username and a password?

No. Derby requires neither by default, which is why the Derby block declares no hibernate.connection.username and no hibernate.connection.password.

Can the main wiki use a schema other than APP?

Yes. APP is Derby's default schema; set the xwiki.db property in xwiki.cfg to the schema you want instead.

Why does Derby get its own mapping file?

Derby has no VARCHAR longer than 32K and Hibernate maps large fields to VARCHAR rather than to BLOB and CLOB (HHH-2651), so XWiki ships a corrected mapping as xwiki.derby.hbm.xml. It is already in the Derby block.

Related

• Use a Container-Managed Data Source.
• Configure HSQLDB.