Skip to Content

Published

Finish the HSQLDB documentation conversion

Last modified by Eleni Cojocariu on 2026/08/13 16:22

Completes the conversion of HSQLDB Installation into Configure HSQLDB and the pages below it, and finishes the original page. The three converted pages were checked section by section against the legacy source, and the configuration snippets against hibernate.cfg.xml.vm in xwiki-platform-tool-configuration-resources.

Content that had not been converted:

  • The legacy section on letting the servlet container manage the data source was in none of the new pages. It becomes Use a Container-Managed Data Source, the one new page here. It is filed under the database hub rather than under HSQLDB, because the procedure is the same for every database and the HSQLDB page only happens to be the one legacy page that documented it.
  • Two details of that section were corrected on the way: $CATALINA_HOME/common/lib is the Tomcat 5 layout and becomes $CATALINA_HOME/lib, and the legacy text named the resource jdbc/xwiki in its snippet but jcbc/xwikiDs in the prose, so the page now uses jdbc/xwiki throughout, with the JNDI name Tomcat documents (java:comp/env/jdbc/xwiki). This procedure is carried over from the legacy page and has not been re-tested, which is worth a reviewer's eye.
  • The legacy warning that the standalone distribution is not tuned for production is not copied here: Install a Standalone (Demo) Distribution already says so in its FAQ, which is that fact's proper home. Its link to the legacy page now points at HSQLDB Limitations instead.

Documentation Guide fixes on the converted pages:

  • Use a Remote HSQLDB Server ended on "Start or restart XWiki" and now has a result step; its intro links the Explanation rather than the sibling How-to.
  • The Configure HSQLDB FAQ answer on production restated HSQLDB Limitations in different words. It is now a clause with a link, so the fact has one home.
  • Two steps of Configure HSQLDB wrapped a single nested bullet that only restated the step. The step now carries the instruction, and the result step names the files to look for (xwiki_db.script, xwiki_db.properties) instead of "e.g. .script".
  • The WarningWIP banners are dropped from the two child pages: nothing is left to convert in this sub-tree, and their parent has had no banner since the previous change request was merged.
  • Related links added where a genuinely related non-child page exists.

The original page:

  • HSQLDB Installation keeps only a pointer at the pages its content became. It has no attachments to remove.
  • Its four backlinks are repointed: the legacy Installation, Installing XWiki .war package manually and Performance pages, and the FAQ of Install a Standalone (Demo) Distribution, which was the one page of the new tree still linking into the legacy space for this topic.

Not done here: the How-tos carry no screenshots, since every step edits a configuration file or restarts a server and none of them shows an XWiki screen. This is the same reasoning that dropped the Home page screenshot in review of the previous change request on this tree.

All changes

Edition of Configure HSQLDB

Summary

Details

Page properties
Content
... ... @@ -1,11 +1,10 @@
1 -To configure XWiki to use [[HSQLDB as the database>>doc:.hsqldb-limitations.WebHome]], which runs embedded in the same JVM as XWiki:
1 +To configure XWiki to use [[HSQLDB as the database>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.hsqldb-limitations.WebHome]], which runs embedded in the same JVM as XWiki:
2 2  
3 3  1. Make sure you have already installed and [[configured a servlet container>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.WebHome]] for XWiki (e.g. [[Tomcat>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.WebHome]] or [[Jetty>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-jetty.WebHome]]), with the [[XWiki WAR>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.WebHome]] file extracted/deployed.
4 -1. Ensure that the hsqldb*.jar driver is available to XWiki:(((
5 -* Check if the ##hsqldb*.jar## file is already present in ##WEB-INF/lib## of your [[XWiki WAR>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.WebHome]]. If the file ##hsqldb*.jar## is missing, download it from the [[HSQLDB website>>https://hsqldb.org/]] or from the [[Maven Central repository>>https://central.sonatype.com/artifact/org.hsqldb/hsqldb?smo=true]] and copy it to the ##WEB-INF/lib## directory of the expanded XWiki WAR.
4 +1. Check that the ##hsqldb*.jar## driver is present in the ##WEB-INF/lib## directory of the expanded XWiki WAR.(((
5 +If it is missing, download it from the [[HSQLDB website>>https://hsqldb.org/]] or from the [[Maven Central repository>>https://central.sonatype.com/artifact/org.hsqldb/hsqldb?smo=true]] and copy it there.
6 6  )))
7 -1. Configure XWiki to use HSQLDB and tell it where the database files will be created:(((
8 -* Edit the ##WEB-INF/hibernate.cfg.xml## file and uncomment the HSQLDB configuration block. The database files are created under the [[permanent directory>>doc:documentation.xs.admin.configuration.directories.permanent-directory.WebHome]]; replace ##${environment.permanentDirectory}/database/xwiki_db## with an absolute path if you want them elsewhere.(((
7 +1. Edit the ##WEB-INF/hibernate.cfg.xml## file and uncomment the HSQLDB configuration block. The database files are created under the [[permanent directory>>doc:documentation.xs.admin.configuration.directories.permanent-directory.WebHome]]; replace ##${environment.permanentDirectory}/database/xwiki_db## with an absolute path if you want them elsewhere.(((
9 9  {{code language="xml"}}
10 10   <property name="hibernate.connection.url">jdbc:hsqldb:file:${environment.permanentDirectory}/database/xwiki_db;shutdown=true</property>
11 11   <property name="hibernate.connection.username">sa</property>
... ... @@ -17,6 +17,5 @@
17 17   <property name="hibernate.connection.characterEncoding">utf8</property>
18 18  {{/code}}
19 19  )))
20 -)))
21 21  1. Start or restart the application server. The HSQLDB database files are created automatically in the location specified by the ##connection.url## property.
22 -1. Verify that the HSQLDB database files (e.g., ##.script##, ##.properties##) are created in the directory you configured.
20 +1. Verify that the ##xwiki_db.script## and ##xwiki_db.properties## database files exist in the directory you configured.
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,7 +1,7 @@
1 1  == Can I use another HSQLDB setup? ==
2 2  
3 -Yes. You can [[configure a remote HSQLDB database>>doc:.use-remote-hsqldb-server.WebHome]].
3 +Yes. XWiki can also connect to a [[remote HSQLDB server>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.use-remote-hsqldb-server.WebHome]] running as a separate process.
4 4  
5 5  == Can this database be used in production? ==
6 6  
7 -Not really, it has some [[limitations>>doc:.hsqldb-limitations.WebHome]]. If you intend to use HSQLDB in production you should probably tune it for a production usage. We would suggest using a more production-ready database such as [[MariaDB>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-mariadb.WebHome]] or [[PostgreSQL>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-manually.WebHome]] if you can.
7 +It is not recommended: HSQLDB is meant for evaluation rather than production, for the reasons listed in [[HSQLDB Limitations>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.hsqldb-limitations.WebHome]].
Related
... ... @@ -1,0 +1,1 @@
1 +* [[Use a Container-Managed Data Source>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.use-container-managed-data-source.WebHome]]

Edition of HSQLDB Limitations

Summary

Details

Page properties
Content
... ... @@ -1,7 +5,3 @@
1 -{{warning}}
2 -WIP
3 -{{/warning}}
4 -
5 5  [[HSQLDB>>https://hsqldb.org/]] is a relational database written in Java. XWiki can use it [[embedded>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.WebHome]], running inside the XWiki JVM with no server process to install or start, or as a [[remote server>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.use-remote-hsqldb-server.WebHome]] running as a standalone process that XWiki reaches over the network.
6 6  
7 7  Both modes carry the same limitations for a production deployment:
... ... @@ -11,4 +11,3 @@
11 11  * Operational tooling: HSQLDB has no built-in backup, live replication or administration tooling comparable to a production-oriented database, so those have to be covered by your own procedures.
12 12  
13 13  For production, use [[MariaDB>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-mariadb.WebHome]], [[PostgreSQL>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-manually.WebHome]] or [[MySQL>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationMySQL.WebHome]] instead.
14 -
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -5,4 +5,3 @@
5 5  == Is the embedded mode slower than the remote one? ==
6 6  
7 7  No. Embedded mode avoids the network round trip, so it is usually faster. The reason to choose a remote server is operational, such as reaching the database from another host.
8 -
Related
... ... @@ -1,0 +1,1 @@
1 +* [[Install a Standalone (Demo) Distribution>>doc:documentation.xs.admin.installation.methods.install-standalone-demo-distribution.WebHome]]

Summary

Details

Page properties
Content
... ... @@ -1,9 +1,5 @@
1 -{{warning}}
2 -WIP
3 -{{/warning}}
1 +To make XWiki use an HSQLDB server running as a separate process, instead of the [[embedded database>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.WebHome]] and with the same [[limitations>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.hsqldb-limitations.WebHome]]:
4 4  
5 -To use a remote HSQLDB server instead of an [[embedded HSQLDB instance>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.WebHome]]:
6 -
7 7  1. Verify that the major version of the ##hsqldb*.jar## on XWiki's classpath matches the major version of the remote HSQLDB server.
8 8  1. Configure and start the remote HSQLDB server by following the official HyperSQL documentation: [[HyperSQL User Guide - Running and Using HyperSQL>>https://hsqldb.org/doc/guide/]].
9 9  1. In ##WEB-INF/hibernate.cfg.xml##, replace the ##jdbc:hsqldb:file:...## connection URL with a remote server URL. Replace ##HOSTNAME##, ##PORT##, and ##dbname## with the host, port, and database name configured on the HSQLDB server. For example:(((
... ... @@ -12,4 +12,4 @@
12 12  {{/code}}
13 13  )))
14 14  1. Start or restart XWiki.
15 -
11 +1. Verify that XWiki starts and that its tables have been created on the remote server, for example by listing them with an HSQLDB client such as ##DatabaseManagerSwing##.
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -5,4 +5,3 @@
5 5  == Can XWiki and the HSQLDB server run on different hosts? ==
6 6  
7 7  Yes. Use the remote host name in the connection URL and make sure the HSQLDB port is reachable from the XWiki server.
8 -

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Use a Container-Managed Data Source
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,12 @@
1 +By default XWiki opens its own connections to the database, from the settings in its ##WEB-INF/hibernate.cfg.xml## file. To let the [[servlet container>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.WebHome]] manage the connection pool instead, and have XWiki take its connections from a JNDI data source:
2 +
3 +1. Copy the JDBC driver of your [[database>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.WebHome]] 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>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.WebHome]].
4 +1. 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.
5 +1. 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:(((
6 +{{code language="xml"}}
7 +<property name="hibernate.connection.datasource">java:comp/env/jdbc/xwiki</property>
8 +<property name="hibernate.dialect">org.hibernate.dialect.HSQLDialect</property>
9 +{{/code}}
10 +)))
11 +1. Restart the servlet container.
12 +1. Verify that XWiki starts and serves its pages, and that the servlet container reports connections being taken from the ##jdbc/xwiki## data source.
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Do I still need a connection provider class? ==
2 +
3 +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.
4 +
5 +== Do I have to set the dialect? ==
6 +
7 +No. Hibernate detects it from the database it connects to, so set ##hibernate.dialect## explicitly only if you want to pin a specific dialect.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Configure HSQLDB>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.WebHome]]
2 +* [[Configure a Servlet Container>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.WebHome]]
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]

Edition of Install and Configure a Relational Database

Summary

Details

Page properties
Content
... ... @@ -20,6 +20,8 @@
20 20  * [[Configure PostgreSQL Manually>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-manually.WebHome]], or [[Configure PostgreSQL for XWiki in Docker>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-docker.WebHome]].
21 21  * [[Oracle>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationOracle.WebHome]].
22 22  
23 +Whichever database you use, XWiki can also take its connections from a [[data source managed by the servlet container>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.use-container-managed-data-source.WebHome]] instead of opening them itself.
24 +
23 23  XWiki uses Hibernate for persistence, so it may also work with the databases below. They receive no consistent testing, and issues are fixed only when they are easy to resolve or a patch is provided:
24 24  
25 25  * [[H2>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationH2.WebHome]].

Edition of HSQLDB Installation

Summary

Details

Page properties
Content
... ... @@ -1,27 +1,7 @@
1 -{{warning}}
2 -WIP: The page is being refactored at: [[Configure HSQLDB>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.WebHome]].
3 -{{/warning}}
1 +{{info}}
2 +This documentation has moved to [[Configure HSQLDB>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.WebHome]] and to the pages below it:
4 4  
5 -Follow these instructions:
6 -
7 -* HSQLDB is a very simple database to configure as you don't need to install nor to start it before being able to use it. It comes as a single JAR file named ##hsqldb*.jar##. If your XWiki WAR doesn't have it in ##WEB-INF/lib## you'll need to download it and copy it there. You can download it from the [[HSQLDB web site>>http://hsqldb.org/]] or directly from the [[Maven Central Repository>>https://search.maven.org/artifact/org.hsqldb/hsqldb]].
8 -* Once this is done, you need to configure XWiki to use HSQLDB and to tell it where the database files will be created. To do this, edit the ##WEB-INF/hibernate.cfg.xml## file where you have expanded the XWiki WAR file and uncommented the HSQLDB part.
9 -
10 -{{warning}}
11 -If you intend to use HSQLDB in production you should probably tune it for a production usage. If you've installed the XWiki standalone distribution just be aware that it's not tuned to be production-ready. Also note that you would need to find a way to perform backups, live replication, administration tools etc. We would suggest using a more production-ready database such as MySQL or PostgreSQL if you can.
12 -
13 -In addition you should be aware that HSQLDB stores the full database in memory which means you'd need to size your memory accordingly. As an indicator having a wiki with 9 subwikis (default XE pages) takes around 110MB in memory and you'd need to have more than 512MB or you'd quickly get Out of Memory errors when performing some memory-intensive operations (exports, etc).
14 -{{/warning}}
15 -
16 -= Other optional ideas =
17 -
18 -* You can use a remote HSQLDB database instead of embedding it. To do this, just use a URL like ##jdbc:hsqldb:hsql:HOSTNAME...## instead of the ##jdbcc:hsqldb:file:..## URL. The major version of the hsqldb jar file must match the major version that the HSQLDB server is using.
19 -* If you want to use your app server facilities to manage your data sources (generally a better strategy), then you must follow these steps:
20 -** Put the ##hsqldb*.jar## file into your app server class path instead of in your web app (like in ##$CATALINA_HOME/common/lib##)
21 -** In ##hibernate.cfg.xml##, use the following settings in place of the HSQLDB block in the sample file. Specifically, do not set the url, user, etc. here and leave the provider_class unset (i.e. use the default value), since XWiki's implementation does not handle container-managed data sources:(((
22 -{{code}}
23 -<property name="connection.datasource">java:/comp/env/jdbc/xwiki</property>
24 -<property name="dialect">org.hibernate.dialect.HSQLDialect</property>
25 -{{/code}}
26 -)))
27 -** the final step is to manage the data source using app server facilities. With Tomcat, for example, you would map the //resource link// ##jcbc/xwikiDs## to a container-managed data source using the Admin web app or by editing the file ##conf/Catalina/*/xwiki.xml## (i.e. webapp-name + ".xml").
4 +* [[HSQLDB Limitations>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.hsqldb-limitations.WebHome]]
5 +* [[Use a Remote HSQLDB Server>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.use-remote-hsqldb-server.WebHome]]
6 +* [[Use a Container-Managed Data Source>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.use-container-managed-data-source.WebHome]]
7 +{{/info}}

Summary

Details

Page properties
Content
... ... @@ -74,7 +74,7 @@
74 74  
75 75  Install and configure the database you wish to use:
76 76  
77 -* [[HSQL Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationHSQL]]
77 +* [[Configure HSQLDB>>documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.WebHome]]
78 78  * [[MySQL Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationMySQL]]
79 79  * [[MariaDB Installation>>documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-mariadb.WebHome]]
80 80  * [[PostgreSQL Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationPostgreSQL]]

Edition of Installation

Summary

Details

Page properties
Content
... ... @@ -21,7 +21,7 @@
21 21  For testing XWiki, we highly recommend one of the following installation method:
22 22  
23 23  * [[Using XWiki in the cloud>>Hosted.WebHome]]: This is by far the simplest to try XWiki since you don't need to install anything.
24 -* [[Using a standalone distribution >>Documentation.AdminGuide.InstallationStandalone]]: Provides a built-in XWiki, with a portable database (HSQLDB) and a lightweight Java container (Jetty). This standalone distribution is not recommended in a production environment (check the [[DB limitations>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationHSQL.WebHome]]). If you need to use it in a production basis, you may look at the other options.
24 +* [[Using a standalone distribution >>Documentation.AdminGuide.InstallationStandalone]]: Provides a built-in XWiki, with a portable database (HSQLDB) and a lightweight Java container (Jetty). This standalone distribution is not recommended in a production environment (check the [[DB limitations>>documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.hsqldb-limitations.WebHome]]). If you need to use it in a production basis, you may look at the other options.
25 25  * [[Using an official XWiki Docker image>>https://hub.docker.com/_/xwiki/]]: Provides an easy solution to test XWiki, with a configuration very close to a production setup.
26 26  
27 27  For production installations, we recommend the following installation method:

Edition of Performance

Summary

Details

Page properties
Content
... ... @@ -150,7 +150,7 @@
150 150  {{/info}}
151 151  
152 152  {{warning}}
153 -If you use HSQLDB as the wiki database, be aware that the full content of the database is stored in memory and thus the memory requirements are higher. See [[HSQLDB installation page>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationHSQL.WebHome]] for more details.
153 +If you use HSQLDB as the wiki database, be aware that the full content of the database is stored in memory and thus the memory requirements are higher. See [[HSQLDB Limitations>>documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.hsqldb-limitations.WebHome]] for more details.
154 154  {{/warning}}
155 155  
156 156  For your information here are the values used for the xwiki.org site:

Edition of Install a Standalone (Demo) Distribution

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.ThomasMortagne
1 +XWiki.elenicojocariu
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,6 +1,6 @@
1 1  == Is this method of installation suitable for production environments? ==
2 2  
3 -No, because there are some [[database limitations of HSQLDB>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationHSQL.WebHome]]. To see installation methods suitable for production environments you can check the [[installation methods>>documentation.xs.admin.installation.WebHome]].
3 +No, because there are some [[database limitations of HSQLDB>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.hsqldb-limitations.WebHome]]. To see installation methods suitable for production environments you can check the [[installation methods>>documentation.xs.admin.installation.WebHome]].
4 4  
5 5  == What if I already have a Web Server running on port ##8080##? ==
6 6  
Aug 13, 2026, 4:22:50 PM

Approved by Eleni Cojocariu

Approvers

Approvers have not been explicitly defined for this Change Request. Approvers will be based entirely on approval rights.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected