Database Configuration
By default for demonstration purposes, Liferay DXP/Portal is configured to use an embedded HSQL database. Beyond demonstration purposes, we recommend using a full-featured, supported RDBMS, such as:
- MariaDB
- MySQL
- Oracle
- PostgreSQL
The Liferay DXP Compatibility Matrix lists the supported databases and versions.
Connecting to a database requires:
Database Configuration
Once you’ve selected a database, follow these steps to configure it:
- Create a Blank Database With UTF-8 Support
- Configure Database User Access
- Configure the Query Result Sort Order (Optional)
Always consult the database vendor’s documentation before modifying the database.
Create a Blank Database With UTF-8 Support
Multilingual character sets require using UTF-8. Create a database that uses UTF-8. Here is a MySQL command example:
create database lportal character set utf8;
Configure Database User Access
Liferay DXP requires database user credentials to persist data. The simplest, easiest way is through a database user that has full database permissions up to and including permissions to create and drop tables. With such a user DXP plugins interact with the database seamlessly and upgrade operations are done automatically. Restricting the database user permissions more than this is not recommended.
However, if your organization requires limiting Liferay DXP database user permissions once the database is initialized, see the high security database user practices next.
High Security Database User Practices
Your organization may have more stringent security policies that require limiting Liferay DXP database user permissions once the database is initialized. If permissions for Select, Insert, Update and Delete operations are the only ones allowed for the user, you must initialize and maintain the database manually. Here’s what’s recommended to accomplish this:
-
Grant full rights for the Liferay DXP database user to do anything to the database.
-
Install Liferay DXP and start it so that it automatically populates the database.
-
Once the database has been populated with the Liferay DXP tables, remove all permissions from the Liferay DXP database user except permissions to perform Select, Insert, Update and Delete operations.
Some Liferay events cause database actions (e.g., creating and dropping tables) that are not compatible with these high security steps. These events require that the Liferay database user has full permissions on the database.
| Event | How to Proceed |
|---|---|
| Publishing Object Definitions | Do not use Objects unless the Liferay database user has full database permissions. |
| Deploying plugins that create tables | Before deploying, grant full rights to the Liferay database user, then re-secure the database once deployed. |
| Upgrading Liferay | Before upgrading, grant full rights to the Liferay database user, then re-secure the database once upgraded. |
Configure the Query Result Sort Order (Optional)
Every database has a default order for sorting results (see this article). If you’re concerned about this order, consult the database vendor documentation to learn its sort order and if necessary, configure the database to use a default query result order you prefer for Liferay DXP entities.
You’ve configured your database server, database, and database user. You’re ready to install a JDBC connecter that Liferay DXP uses to communicate with the database.
Install a JDBC Connector
Liferay DXP requires a JDBC connector for communicating with your database.
Open Source Databases
The Liferay DXP bundle includes several open source JDBC connectors. Connector files are normally provided and installed to a global folder on the application server, such as /lib/ext on Tomcat or /module on JBoss EAP and WildFly.
If you’re connecting to a proprietary database, like Oracle or DB2, download the connector from the vendor and install it to a global folder on the applications server.
Proprietary Databases:
| Database | Connector | Vendor Site | Notes |
|---|---|---|---|
| DB2 | db2jcc4.jar | IBM | The dbc2jcc connector has been deprecated after 3.72. |
| Oracle | ojdbc8.jar | Oracle | The ojdbc8.jar library with at least Oracle 12.2.0.1.0 JDBC 4.2 versioning is required because of data truncation issues that have been detected reading data from CLOB columns. |
Configuring a Data Source
You can configure DXP with a built-in data source connection using one of the methods listed in the table below.
| Method | Available with Docker Image | Recommended for Production |
|---|---|---|
| Docker Environmet Variables | Yes | Yes |
| Portal Properties | Yes* | Yes |
| Setup Wizard | No | No |
Docker Environment Variables
You can configure the built-in data source connection by passing DXP environment variables to your Docker image. Please see Database Templates for examples.
Portal Properties
You can configure the data source connection on a Liferay Tomcat Bundle, application server installation, or Docker image using a portal properties file. See Database Templates for examples.
Using a portal properties file with a Docker image requires passing in the file using a bind mount or volume. See Providing Files to the Container for details.
Setup Wizard
If you’re running DXP for non-production purposes on a Bundle or an application server, you can configure the data source connection during DXP startup using the Setup Wizard.
