ATS Global

Configuring an External MariaDB Database in Liferay DXP

Learn how to connect Liferay DXP to an external MariaDB database for custom application data. This guide explains the database configuration, datasource setup, and an Insurance Self-Service Portal example for managing policy and claim information.

LIFERAY DXPPublished: OCT 29, 20265 min readBy Jyothi N Share
Configuring an External MariaDB Database in Liferay DXP
1. Introduction

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
lportalLiferay portal data and Policy records
insurance_dbClaim 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 FileConfiguration Overview
portal-ext.propertiesDefines the JDBC connection properties, including the database URL, driver, username, and password.
ext-spring.xmlSpring XML Datasource Configuration – Creates the external datasource and exposes it as claimDataSource.
service.xmlService Builder Configuration – Specifies the datasource used by the Claim entity.
module-spring.xmlSpring 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.

Working on something similar? See how ATS Global approaches Liferay DXP development, or browse our case studies.

Found this useful? Share it with your network.

Let’s work together

Ready to build something great?

Tell us about your project. We respond within one business day and can provide a customised quote for your requirements.