Skip to Content

Published

Correct the PostgreSQL manual-configuration documentation

Last modified by Eleni Cojocariu on 2026/08/14 19:35

Reviews Configure PostgreSQL Manually and its four children against the legacy source (PostgreSQL Installation at revision 25.1) and against the platform sources at 18.7.0-SNAPSHOT, and corrects what the conversion got wrong.

A note on overlap: the open change request "Fix the install-xwiki-war documentation tree" also carries file changes for these pages, but its proposed content for all five is identical to what is published, so it fixes none of the below. Two things in it are worth a look while this is reviewed: its file change for Install and Configure a Relational Database predates the HSQLDB merge and would revert the published paragraph about container-managed data sources, and its file change for PostgreSQL Checkpoints and Performance Tuning repoints the history-tab link at documentation.xs.user.base.page.view-page.view-history.history-tab, which does not exist, whereas the published documentation.xs.user.base.page.view.view-history.history-tab does.

Corrections cross-checked against the source:

  • The CREATE DATABASE step only worked on PostgreSQL 17 and later. The legacy page carried the note that older versions need LOCALE = 'C.utf8' and no LOCALE_PROVIDER as part of the step itself, and the conversion dropped it, so the command a reader on a supported PostgreSQL 13 to 16 runs fails. It is back in the step, as a conditional instruction and not as an explanation. The FAQ entry on CREATE DATABASE errors is untouched: it answers a different, diagnostic question and the FAQ is its right home. The rule is confirmed by DatabaseContainerExecutor, which picks the builtin locale provider from 17 up and the plain locale below it. It is back in the step.
  • The hibernate.cfg.xml step told the reader to uncomment the PostgreSQL section but quoted only its properties. In hibernate.cfg.xml.vm that section also contains the xwiki.postgresql.hbm.xml and feeds.hbm.xml mapping entries, inside the same comment, so uncommenting what the page showed left the mappings out. The block now includes them and the step says "in full". A step to comment out the database that is active in a stock WAR was added before it.
  • The FAQ on using a different database name said to change the creation steps and the connection URL. The shipped file's own note adds that the xwiki.db property in xwiki.cfg has to be set too when the main wiki's database is not named xwiki; without it the instance does not work. Added.
  • "Hibernate Sequence already Exists" PostgreSQL Warning explained the message from XWikiHibernateBaseStore, which has been deprecated since 11.5RC1, and said XWiki creates the sequence without checking first. The live path is HibernateStore.createSequenceIfMissing, which does query the schema and skips the creation when the sequence is there, creating it blindly only when that query itself fails, and then not reporting the failure as an error. The root cause is Hibernate's HHH-13464, not the "hard to check in a database-independent way" framing of XWIKI-14055, which is closed as won't fix. Rewritten.
  • Support for Multiple Wikis in PostgreSQL gave the reason database mode is unsupported as the JDBC driver lacking setCatalog. XWIKI-8753 does not say that, and the shipped configuration states the limitation as database mode not supporting database creation. The page now says what those two say, and keeps the same conclusion.
  • PostgreSQL Checkpoints and Performance Tuning ended on a bare max_wal_size and checkpoint_timeout block without saying where the parameters go. It now names postgresql.conf and the configuration reload, and says the values are a starting point rather than a recommendation.
  • CONNECTION_LIMIT = -1 is dropped from CREATE DATABASE: it is PostgreSQL's default and was not in the legacy recipe. The step granting privileges on the public schema now says why it is needed, which is PostgreSQL 15 and later no longer granting them implicitly.

Documentation Guide fixes:

  • The WIP warning banners are dropped from all five pages and from Configure PostgreSQL for XWiki in Docker: nothing in this sub-tree is left to convert.
  • Related links added on the three pages that had none, so the troubleshooting siblings cross-link.
  • Internal references given their doc: prefix, and the "CONFIG WAL CHECKPOINTS" related-link label replaced by the page's actual subject.
  • No FAQ entry is removed, and nothing explanatory is added inside a step. Where a step needed a version-dependent variation it is phrased as an instruction; the reasons stay in the FAQ, per the guide's rule that steps carry no extra explanations.

Two fixes just outside the sub-tree:

  • Configure PostgreSQL for XWiki in Docker quoted the connection URL property without its hibernate. prefix; the shipped file uses hibernate.connection.url, which the manual page already had right. The two pages contradicted each other.
  • The legacy PostgreSQL Installation page pointed "Configure PostgreSQL Manually" at the support-multiple-wikis child rather than at the How-to. It resolved, so no broken-link check saw it. Its WIP banner and the stale "Using Docker" link label are fixed too.

Not done here: no screenshots. Every step of both How-tos edits a configuration file or runs a shell command, and the result step is a wiki home page that looks no different served from PostgreSQL than from any other database. The result-step screenshot the guide asks for is therefore still missing, and is worth deciding on in review rather than assuming.

All changes

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.superadmin
1 +XWiki.elenicojocariu
Content
... ... @@ -1,11 +5,7 @@
1 -{{warning}}
2 -WIP
3 -{{/warning}}
4 -
5 5  To configure PostgreSQL for XWiki:
6 6  
7 7  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.
8 -1. Install [[PostgreSQL>>http://www.postgresql.org/]]. Make sure you download a [[supported version>>dev:Community.SupportStrategy.DatabaseSupportStrategy]].
4 +1. Install [[PostgreSQL>>https://www.postgresql.org/]]. Make sure you download a [[supported version>>dev:Community.SupportStrategy.DatabaseSupportStrategy]].
9 9  1. Download the [[PostgreSQL JDBC driver>>https://jdbc.postgresql.org/download/]].
10 10  1. Copy the JDBC driver JAR into the XWiki web application's ##WEB-INF/lib## directory of the [[servlet container>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.WebHome]], or into the container's common library directory.
11 11  1. Start PostgreSQL.
... ... @@ -17,9 +17,10 @@
17 17  LOCALE_PROVIDER = 'builtin'
18 18  LOCALE = 'C.UTF-8'
19 19  TABLESPACE = pg_default
20 -TEMPLATE = template0
21 -CONNECTION_LIMIT = -1;
16 +TEMPLATE = template0;
22 22  {{/code}}
18 +
19 +On PostgreSQL versions before 17, omit the ##LOCALE_PROVIDER## line and use ##LOCALE = 'C.utf8'##.
23 23  )))
24 24  1. Verify that the database was created and is listed in the available databases:(((
25 25  {{code language="none"}}
... ... @@ -51,9 +51,8 @@
51 51  GRANT ALL ON SCHEMA public TO xwiki;
52 52  {{/code}}
53 53  )))
54 -1. Configure XWiki to use PostgreSQL.(((
55 -Edit the ##WEB-INF/hibernate.cfg.xml## file (search for the "##PostgreSQL configuration##" section in the file), uncomment it:
56 -
51 +1. Comment out the configuration section of the database currently active in the ##WEB-INF/hibernate.cfg.xml## file of the expanded XWiki WAR.
52 +1. Uncomment the "##PostgreSQL configuration##" section of the same file, in full, including the mapping entries at its end.(((
57 57  {{code language="xml"}}
58 58   <property name="hibernate.connection.url">jdbc:postgresql://localhost:5432/xwiki</property>
59 59   <property name="hibernate.connection.username">xwiki</property>
... ... @@ -65,8 +65,11 @@
65 65   <property name="hibernate.connection.charSet">UTF-8</property>
66 66   <property name="hibernate.connection.useUnicode">true</property>
67 67   <property name="hibernate.connection.characterEncoding">utf8</property>
64 +
65 + <mapping resource="xwiki.postgresql.hbm.xml"/>
66 + <mapping resource="feeds.hbm.xml"/>
68 68  {{/code}}
69 69  )))
69 +1. Review the ##hibernate.connection.url## property, and the user name and password, against the database you created.
70 70  1. Start XWiki.
71 71  1. Open your wiki in a browser. XWiki connects to PostgreSQL, creates its tables on first start, and serves the wiki without a database error.
72 -
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -12,7 +12,7 @@
12 12  
13 13  == Can I use a different database name or user? ==
14 14  
15 -Yes. Replace ##xwiki## with your preferred names in the creation steps and in the ##hibernate.connection.url## property.
15 +Yes. Replace ##xwiki## with your own names in the creation steps and in the ##hibernate.connection.url##, ##hibernate.connection.username## and ##hibernate.connection.password## properties. If the main wiki's database is not named ##xwiki##, also set the ##xwiki.db## property in the ##WEB-INF/xwiki.cfg## file.
16 16  
17 17  == How can I remove the XWiki database? ==
18 18  
... ... @@ -21,4 +21,3 @@
21 21  == How are subwikis stored? ==
22 22  
23 23  Each subwiki uses [[its own schema in the same database>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-manually.support-multiple-wikis.WebHome]].
24 -
Related
... ... @@ -1,3 +1,2 @@
1 1  * [[Configure PostgreSQL for XWiki in Docker>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-docker.WebHome]].
2 2  * [[Run XWiki (PostgreSQL on Tomcat) using Docker Run>>doc:documentation.xs.admin.installation.methods.install-xwiki-docker.docker-run.run-xwiki-postgresql-tomcat.WebHome]].
3 -

Edition of "Hibernate Sequence already Exists" PostgreSQL Warning

Summary

Details

Page properties
Content
... ... @@ -1,7 +5,3 @@
1 -{{warning}}
2 -WIP
3 -{{/warning}}
4 -
5 5  When starting XWiki with PostgreSQL, you may encounter the following message in the PostgreSQL logs:
6 6  
7 7  {{code language="none"}}
... ... @@ -10,9 +10,8 @@
10 10  
11 11  === Cause ===
12 12  
13 -This message is expected and usually harmless. Because of a Hibernate limitation, XWiki attempts to create the ##hibernate_sequence## sequence during startup from {{scm path="xwiki-platform-core/xwiki-platform-oldcore/src/main/java/com/xpn/xwiki/store/XWikiHibernateBaseStore.java"}}##XWikiHibernateBaseStore##{{/scm}}, [[without first checking>>https://jira.xwiki.org/browse/XWIKI-14055]] whether it already exists in a database-independent way. If the sequence already exists, PostgreSQL reports the warning in the logs.
9 +XWiki lets Hibernate generate the identifiers of a few tables, and on PostgreSQL and Oracle Hibernate does that from a sequence named ##hibernate_sequence##. Hibernate would normally create that sequence itself when it updates the schema, but because of [[HHH-13464>>https://hibernate.atlassian.net/browse/HHH-13464]] it skips the creation as soon as a sequence of that name exists in //any// schema, which leaves subwikis without one. XWiki therefore creates the sequence itself, in {{scm path="xwiki-platform-core/xwiki-platform-oldcore/src/main/java/com/xpn/xwiki/internal/store/hibernate/HibernateStore.java"}}##HibernateStore##{{/scm}}: it first asks the schema whether the sequence is already there and skips the creation if it is, and only when that query itself fails does it attempt the creation blindly. PostgreSQL then logs this message, which was reported as [[XWIKI-14055>>https://jira.xwiki.org/browse/XWIKI-14055]] and closed as //won't fix// because it is harmless.
14 14  
15 15  === Solution ===
16 16  
17 -No action is required. This message can safely be ignored as long as XWiki starts correctly and operates normally.
18 -
13 +No action is required. XWiki does not report the failed creation as an error in this case, and the wiki starts and operates normally.
DocApp.Code.DocumentationClass[0]
Related
... ... @@ -1,0 +1,2 @@
1 +* [[PostgreSQL JDBC Driver Compatibility Issues>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-manually.postgresql-jdbc-driver-compatibility-issues.WebHome]].
2 +* [[Support for Multiple Wikis in PostgreSQL>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-manually.support-multiple-wikis.WebHome]].

Edition of PostgreSQL Checkpoints and Performance Tuning

Summary

Details

Page properties
Content
... ... @@ -1,7 +5,3 @@
1 -{{warning}}
2 -WIP
3 -{{/warning}}
4 -
5 5  When running XWiki with PostgreSQL, you may notice log messages similar to the following in the PostgreSQL logs:
6 6  
7 7  {{code language="none"}}
... ... @@ -11,19 +11,19 @@
11 11  2013-04-03 18:46:05 EEST HINT: Consider increasing the configuration parameter "checkpoint_segments".
12 12  {{/code}}
13 13  
14 -This indicates that PostgreSQL is triggering checkpoints too often. Frequent checkpoints can negatively impact XWiki performance, especially during operations that generate many database writes, such as:
10 +This indicates that PostgreSQL is triggering checkpoints too often, which increases disk activity and slows the database down. XWiki reaches that point during the operations that generate many database writes at once, such as:
15 15  
16 -* [[Importing large wiki Pages>>documentation.xs.admin.imports.WebHome]],
17 -* [[Installing extensions>>extensions:Extension.Extension Manager Application||anchor="HInstall"]],
18 -* [[Rolling back document versions>>documentation.xs.user.base.page.view.view-history.history-tab.WebHome]],
12 +* [[Importing large wiki Pages>>doc:documentation.xs.admin.imports.WebHome]],
13 +* [[Installing extensions>>doc:extensions:Extension.Extension Manager Application||anchor="HInstall"]],
14 +* [[Rolling back document versions>>doc:documentation.xs.user.base.page.view.view-history.history-tab.WebHome]],
19 19  * Rebuilding indexes,
20 20  * Bulk updates or migrations.
21 21  
22 -If the checkpoint configuration is too aggressive for the workload generated by XWiki, PostgreSQL performs checkpoints more frequently than recommended, which increases disk activity and reduces performance.
18 +The parameter the hint names, ##checkpoint_segments##, was removed in PostgreSQL 9.5 and replaced by ##max_wal_size##, so on any supported version the setting to raise is that one. Both it and ##checkpoint_timeout## live in ##postgresql.conf##, and PostgreSQL applies them on a configuration reload:
23 23  
24 -Older PostgreSQL versions commonly suggested tuning the ##checkpoint_segments## parameter. Starting with PostgreSQL 9.5, this parameter was replaced by ##max_wal_size##. For modern PostgreSQL versions, consider increasing:
25 -
26 26  {{code language="none"}}
27 27  max_wal_size = 2GB
28 28  checkpoint_timeout = 15min
29 29  {{/code}}
24 +
25 +Those values are a starting point rather than a recommendation: the right ones depend on how much write traffic the wiki produces and on how much disk space the write-ahead log may occupy.
DocApp.Code.DocumentationClass[0]
Related
... ... @@ -1,3 +1,2 @@
1 1  * [[Tuning Your PostgreSQL Server>>https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server]].
2 -* [[CONFIG WAL CHECKPOINTS>>https://www.postgresql.org/docs/current/runtime-config-wal.html#RUNTIME-CONFIG-WAL-CHECKPOINTS]].
3 -
2 +* [[WAL Checkpoint Configuration>>https://www.postgresql.org/docs/current/runtime-config-wal.html#RUNTIME-CONFIG-WAL-CHECKPOINTS]].

Edition of PostgreSQL JDBC Driver Compatibility Issues

Summary

Details

Page properties
Content
... ... @@ -1,7 +5,3 @@
1 -{{warning}}
2 -WIP
3 -{{/warning}}
4 -
5 5  When starting XWiki with PostgreSQL, you may encounter the following error:
6 6  
7 7  {{code language="none"}}
... ... @@ -22,4 +22,3 @@
22 22  1. Restart the servlet container. XWiki starts and connects to PostgreSQL without the error.
23 23  
24 24  If the driver came from a Linux distribution package rather than a manual download, upgrade that package instead, so that the package manager keeps managing the file.
25 -
DocApp.Code.DocumentationClass[0]
Related
... ... @@ -1,0 +1,2 @@
1 +* [["Hibernate Sequence already Exists" PostgreSQL Warning>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-manually.hibernate-sequence-exists-warning.WebHome]].
2 +* [[Configure PostgreSQL Manually>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-manually.WebHome]].

Summary

Details

Page properties
Content
... ... @@ -1,12 +1,7 @@
1 -{{warning}}
2 -WIP
3 -{{/warning}}
1 +XWiki supports setups with [[multiple wikis>>doc:documentation.xs.user.base.wikis.WebHome]] on PostgreSQL by giving each wiki its own [[PostgreSQL schema>>https://www.postgresql.org/docs/current/ddl-schemas.html]] inside a single database. This is what the following property of ##WEB-INF/hibernate.cfg.xml## selects, and it is the value the shipped file already carries:
4 4  
5 -XWiki supports setups with [[multiple wikis>>documentation.xs.user.base.wikis.WebHome]] with PostgreSQL by using the [[schema mode>>https://www.postgresql.org/docs/current/ddl-schemas.html]]. XWiki achieves this separation by creating one PostgreSQL schema per wiki. This behavior is controlled through the following property in ##hibernate.cfg.xml##:
6 -
7 -{{code language="none"}}
3 +{{code language="xml"}}
8 8  <property name="xwiki.virtual_mode">schema</property>
9 9  {{/code}}
10 10  
11 -XWiki currently supports only the schema-based approach with PostgreSQL. The alternative [[##database mode## is not supported>>https://jira.xwiki.org/browse/XWIKI-8753]] because the PostgreSQL JDBC driver does not provide the functionality required by XWiki for switching catalogs dynamically (##setCatalog## support).
12 -
7 +The property also accepts ##database##, which would represent each wiki as a separate database rather than a schema, but that mode is incomplete on PostgreSQL: it cannot create the databases it would need. Use ##schema## until [[XWIKI-8753>>https://jira.xwiki.org/browse/XWIKI-8753]] is resolved.
DocApp.Code.DocumentationClass[0]
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Configure PostgreSQL Manually>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-manually.WebHome]].
2 +* [[Wikis>>doc:documentation.xs.user.base.wikis.WebHome]].

Edition of Configure PostgreSQL for XWiki in Docker

Summary

Details

Page properties
Content
... ... @@ -1,7 +5,3 @@
1 -{{warning}}
2 -WIP
3 -{{/warning}}
4 -
5 5  To configure PostgreSQL for XWiki using Docker:
6 6  
7 7  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.
... ... @@ -27,7 +27,7 @@
27 27  1. Uncomment the PostgreSQL configuration section.
28 28  1. Configure the PostgreSQL connection URL, using ##localhost## if XWiki runs directly on the host, or the PostgreSQL container/service name if XWiki also runs in Docker on a shared network.(((
29 29  {{code language="xml"}}
30 - <property name="connection.url">jdbc:postgresql://localhost:5432/xwiki</property>
26 +<property name="hibernate.connection.url">jdbc:postgresql://localhost:5432/xwiki</property>
31 31  {{/code}}
32 32  )))
33 33  1. Save the configuration changes.

Edition of PostgreSQL Installation

Summary

Details

Page properties
Content
... ... @@ -4,22 +4,13 @@
4 4  
5 5  = Installation =
6 6  
7 -You have 2 options:
8 -
9 -* Install PostgreSQL on your machine manually
10 -* Use the official PostgreSQL docker image
11 -
12 12  == Manual Installation ==
13 13  
14 -{{warning}}
15 -WIP: documentation refactoring at: [[Configure PostgreSQL Manually>>documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-manually.WebHome]].
16 -{{/warning}}
9 +See [[Configure PostgreSQL Manually>>documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-manually.WebHome]].
17 17  
18 -See [[Configure PostgreSQL Manually>>documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-manually.support-multiple-wikis.WebHome]].
19 -
20 20  == Using Docker ==
21 21  
22 -See [[Configure PostgreSQL for XWiki Using Docker>>documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-docker.WebHome]].
13 +See [[Configure PostgreSQL for XWiki in Docker>>documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-docker.WebHome]].
23 23  
24 24  = Multiwiki Status =
25 25  
... ... @@ -27,7 +27,7 @@
27 27  
28 28  = Performance Tuning =
29 29  
30 -See [[PostgreSQL Checkpoints and Performance Tuning>>documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-manually.checkpoints-performance-tuning.WebHome]].
21 +See [[PostgreSQL Checkpoints and Performance Tuning>>documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-postgresql-manually.checkpoints-performance-tuning.WebHome]].
31 31  
32 32  = Troubleshooting =
33 33  
Aug 14, 2026, 7:34:55 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