HSQLDB Limitations
Last modified by Eleni Cojocariu on 2026/08/13 16:22
Content
Explanation
HSQLDB is a relational database written in Java. XWiki can use it embedded, running inside the XWiki JVM with no server process to install or start, or as a remote server running as a standalone process that XWiki reaches over the network.
Both modes carry the same limitations for a production deployment:
- Memory usage: HSQLDB keeps the whole database in memory, so the Java heap has to be sized for the database rather than only for XWiki. A wiki with 9 subwikis holding the default XWiki pages uses around 110MB, and a heap below 512MB makes memory-intensive operations such as exporting fail with OutOfMemoryError.
- Persistence: data is written to disk periodically rather than on commit, so an undersized heap or an abrupt stop affects durability as well as stability.
- 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.
For production, use MariaDB, PostgreSQL or MySQL instead.
FAQ
Can I migrate from HSQLDB to another database later?
Yes. Export the wiki to a XAR, install XWiki against the new database, then import the XAR. There is no in-place conversion of the HSQLDB files.
Is the embedded mode slower than the remote one?
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.
