Database Configuration for XWiki in Docker
Explanation
When running XWiki with a relational database in Docker using Docker Run, the configuration depends on the database engine used. MySQL and MariaDB share similar behavior, while PostgreSQL differs in several aspects.
Character Encoding and Collation
XWiki requires the database to store text as UTF-8 and to compare it case-sensitively. Database containers do not do this by default, which is why the examples pass extra options when starting them. These options are not optional, and they only take effect when the database itself is created, so they must be in place before the database container is started for the first time.
For MySQL and MariaDB, the server is started with --character-set-server=utf8mb4 and --collation-server=utf8mb4_bin. The utf8mb4 character set covers the whole Unicode range, including characters outside the Basic Multilingual Plane such as emoji, and the binary collation compares strings byte by byte, so values differing only in case, such as two page names, stay distinct.
For PostgreSQL, the POSTGRES_INITDB_ARGS environment variable is set to --encoding=UTF8 --locale-provider=builtin --locale=C.UTF-8. The encoding covers the whole Unicode range, and the builtin C.UTF-8 locale orders text by code point rather than by language rules. With a language-dependent order, PostgreSQL sorts document names differently from Solr, and XWiki then re-indexes a large part of the wiki at every restart. The builtin locale provider requires PostgreSQL 17 or later.
MySQL and MariaDB
Run XWiki (MySQL on Tomcat) Using Docker Run and Run XWiki (MariaDB on Tomcat) Using Docker Run use a similar initialization and storage model.
When starting a container for the database, it is common to mount two directories:
- One directory is used during database initialization to provide SQL files, such as permission setup scripts.
- One directory is used to store the database data files so that the database content is preserved when the container is stopped, removed, or restarted.
The initialization SQL file (init.sql inside /my/path/mysql-init or /my/path/mariadb-init) grants additional privileges to the XWiki database user. This allows the user to create new databases, which is required for features such as sub-wikis.
When mounting directories into the container, always use fully-qualified absolute paths. Relative paths may lead to unexpected behavior depending on how Docker is executed.
PostgreSQL
PostgreSQL follows a different approach compared to MySQL and MariaDB.
Run XWiki (PostgreSQL on Tomcat) Using Docker Run mounts a single directory, used to persist the database data files. Its path inside the container changed in PostgreSQL 18.
No initialization script is mounted, because XWiki stores each sub-wiki as a schema of the same database rather than as a separate database: the database user owns that database and can already create schemas, so there are no extra privileges to grant. Creating the database and its user is handled entirely through environment variables.
Connecting to the Database from the Command Line
To run SQL queries against the XWiki database, start a database client inside the database container. Find the name or id of that container with docker ps, or with docker compose ps when you started XWiki with Docker Compose, and pass the values you set for DB_USER, DB_PASSWORD and DB_DATABASE (all three are xwiki in the examples).
For MySQL:
docker exec -it <container> mysql --user=xwiki --password=xwiki xwikiFor MariaDB, use the mariadb client, as the MariaDB image no longer provides a mysql command:
docker exec -it <container> mariadb --user=xwiki --password=xwiki xwikiFor PostgreSQL:
docker exec -it <container> psql --username=xwiki xwikiYou can also open a shell inside the container with docker exec -it <container> bash and run the client from there.
