Liferay DXP uses a relational database to store portal and application data. However, certain applications may require custom data to be stored separately from the primary Liferay database.
Liferay supports configuring additional datasources, allowing custom Service Builder entities to use different databases based on application requirements.
In this article, we explore how to integrate an external MariaDB database with Liferay DXP using a simple Insurance Self-Service Portal example.
The application manages two entities:
- Policy: Stored in the primary Liferay database.
- Claim: Stored in a separate external MariaDB database.
This approach demonstrates how Liferay can manage application data across multiple databases while maintaining a single user interface.
2. Why Use an External Database?
In real-world applications, different types of data may need to be stored and managed separately. Using an external database helps organize application-specific data without placing everything in the primary Liferay database.
For example, in an insurance application, customer and policy information may be stored in the primary Liferay database, while claim records are maintained in a separate database. This allows the application to manage its data independently while accessing both through a single interface.
Some benefits include:
- Data separation: Keeps application-specific data separate from core portal data.
- Flexible architecture: Allows different application modules to use different datasources.
- Better data organization: Maintains a clear separation between different types of application data.
- Independent management: Supports separate database backup and maintenance strategies.
The decision to use an external database depends on the application's requirements, infrastructure, and data management needs.
3. Understanding the Architecture
In our Insurance Self-Service Portal, two MariaDB databases are used.
| DatabaseData Stored | |
lportal | Liferay portal data and Policy records |
insurance_db | Claim records |
The Policy and Claim entities are implemented using separate Service Builder modules.
The Policy Service Builder uses Liferay's default datasource, while the Claim Service Builder uses an additional datasource configured for the external database.
The MVC Portlet provides a common interface for managing both entities.
Application flow:
Insurance Management MVC Portlet
→ Policy Service Builder → Primary Liferay Database (lportal)
→ Claim Service Builder → External MariaDB Database (insurance_db)
Although the data is stored in separate databases, the application can access both through their respective Service Builder services.
4. Configuring the External Database
Integrating an external database with Liferay DXP requires configuring the database connection and associating it with the appropriate Service Builder module.
The configuration involves the following files:
| Configuration File | Configuration Overview |
portal-ext.properties | Defines the JDBC connection properties, including the database URL, driver, username, and password. |
ext-spring.xml | Spring XML Datasource Configuration – Creates the external datasource and exposes it as claimDataSource. |
service.xml | Service Builder Configuration – Specifies the datasource used by the Claim entity. |
module-spring.xml | Spring XML Persistence Configuration – Connects the datasource to the Claim persistence layer, which uses Hibernate for ORM and database operations. |
The external datasource is identified by the name claimDataSource.
The Claim Service Builder references this datasource to store Claim records in the external MariaDB database. The Policy Service Builder continues to use Liferay's default datasource.
Configuration Flow:
portal-ext.properties → ext-spring.xml → service.xml → module-spring.xml → Hibernate Persistence → External MariaDB
Each configuration file has a specific responsibility in establishing the connection between the external database and the Service Builder persistence layer.
Important: Defining an additional database connection does not automatically associate a Service Builder entity with that database. The datasource must be properly configured and referenced by the corresponding persistence layer.
5. How Policy and Claim Data Are Stored
When a user creates a Policy through the MVC Portlet, the application calls PolicyLocalService.
The Policy Service Builder persistence layer stores the record in the primary lportal database.
When a user submits a Claim, the application calls ClaimLocalService.
The Claim Service Builder persistence layer uses claimDataSource to store the record in the external insurance_db database.
The application also validates the associated Policy before saving the Claim.
This validation is important because the Policy and Claim records are stored in different databases.
6. Displaying Data Through a Single Liferay Interface
Even though the Policy and Claim records are stored separately, users can manage them through the same Insurance Management interface.
The MVC Portlet acts as the application layer. It calls the appropriate Service Builder service depending on the user's action.
For example:
- Policy operations use
PolicyLocalService. - Claim operations use
ClaimLocalService. - Claim submission validates the related Policy using
PolicyLocalService.
This allows the application to work with data from both databases without requiring the MVC Portlet to connect directly to MariaDB.
7. Testing and Verification
The integration can be verified through the Liferay user interface and the MariaDB databases.
The following checks confirm that the configuration is working as expected:
- Create a Policy through the Liferay interface and verify that the record is stored in the primary database.
- Submit a Claim associated with the Policy and verify that the record is stored in the external database.
- Confirm that both records are accessible through their respective Service Builder services.
- Verify the database tables and records directly in MariaDB.
The expected result is that Policy records are stored in lportal, while Claim records are stored in insurance_db.
8. Conclusion
Integrating an external MariaDB database with Liferay DXP provides a flexible way to manage custom application data separately from the primary portal database.
Using the Insurance Self-Service Portal example, we demonstrated how two Service Builder modules can use different datasources while being accessed through a single MVC Portlet interface.This approach helps maintain a clear separation of application data while continuing to use Liferay's Service Builder architecture.
The key takeaway: Before implementing external database integration in a production environment, ensure database compatibility, security, backup strategies, transaction handling, and schema management are properly addressed.



