Steps

To configure XWiki to use IBM DB2 on a database server you administer:

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. On the database machine, create an operating-system user named xwiki with your usual tool, and give it a password. DB2 authenticates against operating-system users, so this is the account XWiki will connect with. The steps below use xwiki as the password to keep them readable; pick a real one for anything but a test instance.
3. Download the IBM Data Server Driver for JDBC and SQLJ, either from IBM or from the Maven Central repository, and copy its jar into the WEB-INF/lib directory of the expanded XWiki WAR. XWiki ships no DB2 driver.

   $ cp jcc-*.jar /path/to/webapps/xwiki/WEB-INF/lib/

4. Open a DB2 command line processor by running db2, which answers with a db2 => prompt, and create the database.

   db2 => create database xwiki

5. Connect to it to continue the configuration.

   db2 => connect to xwiki

6. Create a 32K bufferpool and a 32K tablespace. DB2 pages are 4K by default and a few XWiki tables have rows wider than that, so the default tablespace cannot hold them.

   db2 => create bufferpool BFP32K immediate size 1024 pagesize 32k
   db2 => create tablespace TSXWIKI pagesize 32k bufferpool BFP32K

7. Grant the xwiki user the privileges it needs on the database and on that tablespace.

   db2 => grant connect, createtab, implicit_schema on database to user xwiki
   db2 => grant use of tablespace TSXWIKI to user XWIKI

8. Release the connection and leave the command line processor.

   db2 => connect reset
   db2 => quit

9. Edit the WEB-INF/hibernate.cfg.xml file of the expanded XWiki WAR, comment out the database block that is currently active, and add the block below inside <session-factory>. DB2 is the one database with no commented-out block of its own in that file, so you write it rather than uncomment it. Replace localhost with the host running DB2 if it is not the XWiki machine.

       <property name="hibernate.connection.url">jdbc:db2://localhost:50000/xwiki</property>
       <property name="hibernate.connection.username">xwiki</property>
       <property name="hibernate.connection.password">xwiki</property>
       <property name="hibernate.connection.driver_class">com.ibm.db2.jcc.DB2Driver</property>
       <property name="hibernate.dialect">org.hibernate.dialect.DB2Dialect</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.db2.hbm.xml"/>
       <mapping resource="feeds.hbm.xml"/>
       <mapping resource="instance.hbm.xml"/>
       <mapping resource="notification-filter-preferences.hbm.xml"/>
       <mapping resource="mailsender.hbm.xml"/>

10. Start or restart the application server. XWiki creates its tables on the first run.
11. Verify that the tables are there, by listing the ones created under the XWIKI schema.

    $ db2 connect to xwiki
    $ db2 "list tables for schema XWIKI"
    
    Table/View        Schema    Type  Creation time
    ----------------- --------- ----- --------------------------
    XWIKIDOC          XWIKI     T     2026-10-23-19.42.11.284000
    XWIKIATTACHMENT   XWIKI     T     2026-10-23-19.42.12.067000
    XWIKIOBJECTS      XWIKI     T     2026-10-23-19.42.12.591000

FAQ

Do I need to download a Hibernate mapping file for DB2?

No. XWiki ships xwiki.db2.hbm.xml inside itself and keeps it in step with the schema, so the <mapping resource="xwiki.db2.hbm.xml"/> line above is all you need. Copies of that file offered for download elsewhere are old forks of it, and an instance started against one of them misses the tables XWiki has added since.

Why does a wiki search fail with DB2 reporting SQLCODE: -440?

Because the search ran through XWiki's database-backed search page, which matches with upper() over the column holding a document's content. DB2 stores that column as a CLOB and its UPPER() only handles short values, so the query is rejected. The search XWiki ships enabled is the Solr Search Application, which has its own index and never asks the database to do this, so keep that one rather than switching to the database-backed search.

Related

• Configure Derby
• Configure H2
• Use a Container-Managed Data Source