Submit Feedback
Knowledge Base
Published Aug. 15, 2025

Migrating Your Database to PostgreSQL

Written By

Abhner Ramos Barbosa

How To articles are not official guidelines or officially supported documentation. They are community-contributed content and may not always reflect the latest updates to Liferay DXP. We welcome your feedback to improve How to articles!

While we make every effort to ensure this Knowledge Base is accurate,it may not always reflect the most recent updates or official guidelines.We appreciate your understanding and encourage you to reach out with any feedback or concerns.

Introduction

Liferay adopted PostgreSQL as the default database for PaaS and SaaS projects in October 2024. Since then, all new Liferay PaaS and SaaS deployments use PostgreSQL. To maintain compatibility and ensure optimal performance, consider migrating your existing databases.

This recipe walks you through the migration process using Liferay's built-in migration tools available in Liferay DXP 2024.Q4 and later. You'll learn how to export your data, import it into a PostgreSQL database, and configure your Liferay instance to connect to PostgreSQL.

The steps outlined in this article apply only to self-hosted Liferay DXP environments. For Liferay PaaS, contact Liferay Support for database migration guidance.

Prerequisites

  • Self-Hosted Liferay DXP environment

  • PostgreSQL database

  • A user who has administrative access to the database

  • A user who has administrative access to Liferay's Control Panel

Steps

Liferay DXP Instance

  1. Sign in to your Liferay DXP instance.

  2. Open the Global Menu (ICON), navigate to Control Panel, and click System Settings.

  3. Under Platform, click Upgrades.
    Under Platform, click Upgrades.

  4. Go to the Database Migration Schema Export tab.

    If you don't see it, enable the Database Migration Schema Export System Settings (LPD-23840) feature flag. Open the Global Menu, go to Control Panel > System Settings > Feature Flags > Beta. After enabling it, refresh the Upgrades page.

    Go to the Database Migration Schema Export tab.

  5. Specify the desired path in the Export Files Path field where the generated output files will be saved.
    Specify the desired path in the Export Files Path field where the generated output files will be saved.

  6. Click Save.
    A success message appears and several log messages are generated in your application server logs. Examples:

    2025-07-01 14:26:00.110 INFO  [CM Event Dispatcher (Fire ConfigurationEvent: pid=com.liferay.portal.db.migration.schema.exporter.internal.configuration.DBMigrationSchemaExportConfiguration)][DBMigrationSchemaExport:103] Start database schema definition export
2025-07-01 14:26:00.303 INFO  [CM Event Dispatcher (Fire ConfigurationEvent: pid=com.liferay.portal.db.migration.schema.exporter.internal.configuration.DBMigrationSchemaExportConfiguration)][DBMigrationSchemaExport:120] Finished database schema definition export to /home/me/database-recipe
    On Liferay versions earlier than 2025.Q2, migrating Commerce data may trigger a bug (see LPD-53545). This recipe will be updated once the fix is backported to 2025.Q1.

  7. Check the export report for errors. You'll find the report and database scripts in the directory you specified for export, which includes the following files:

    1. tables.sql: This file has the table creation script.

    2. indexes.sql: This file has the index creation script.

    3. db_migration_schema_export_report: This is the report generated during the export.

  8. Shut down all Liferay nodes connected to the old database.

The import tool requires the server to be stopped during the final copy to prevent users from inserting data during the process. Keep in mind that querying data may impact the source database's performance.

PostgreSQL server 

  1. Once the Liferay nodes are shut down, ensure that your PostgreSQL database is up and running.

  2. Create an empty database in the PostgreSQL server to import your liferay database schema.

  3. Navigate to the .../bundles/tools/portal-tools-db-schema-importer directory and run the db_schema_importer.sh script, replacing the placeholders with your environment-specific settings. For example, when migrating from MySQL:

    ./db_schema_importer.sh --path /home/[PATH-TO-EXPORTED-SCRIPTS] --source-jdbc-url jdbc:mysql://[MY-MYSQL-SERVER]:3306/[NAME-OF-MYSQL-DB] --source-user [MYSQL-USER-NAME] --source-password [MYSQL-PASSWORD] --target-jdbc-url jdbc:postgresql://[MY-POSTGRESQL-SERVER]:5432/[NAME-OF-MY-POSTGRESQL-DB] --target-user [POSTGRESQL-USER] --target-password [POSTGRESQL-PASSWORD]
    Windows support for this tool is not yet available.

  4. Review the db_schema_import_report file, generated in the specified path, for any errors.

    The import process duration depends on the database size and the configuration of the old and new servers.

Portal-ext.properties Config

  1. Configure your Liferay node(s) to use the new PostgreSQL database by editing the portal-ext.properties file. Replace the old configurations with the appropriate PostgreSQL settings, as shown in the example below.

    Replace the placeholder values with your own.

    # PostgreSQL Database Configuration
	jdbc.default.driverClassName=[POSTGRESQL_DRIVER_CLASS_NAME]
	jdbc.default.url=jdbc:postgresql://[MY-POSTGRESQL-SERVER]:5432/[NAME-OF-MY-POSTGRESQL-DB]
	jdbc.default.username=[POSTGRESQL-USER]
	jdbc.default.password=[POSTGRESQL-PASSWORD]

    This configures the connection between Liferay and the PostgreSQL database.

    Make sure all Liferay nodes are configured to use the new PostgreSQL database and not the old database. Additionally, create a PostgreSQL backup after migration but before launching Liferay to ensure a fallback restore point if needed.

  2. After updating portal-ext.properties, start your first Liferay node up.

  3. Once the server(s) have completed startup, open a browser and navigate to your Liferay DXP instance to confirm the migration was successful.

Conclusion

Congratulations, you've successfully migrated your database to PostgreSQL.

Tips

  • The migration time largely depends on the size of your existing database. Reducing its size can help speed up the process.

  • Stop your old database before launching the Liferay node(s) to prevent any missed nodes from connecting to it. Keep the old database as a fallback, but ensure Liferay cannot connect to and use it.

  • The import tool only reads from the old database, so configuring it for read-only access can improve performance. For more details, refer to your database type's official documentation.

  • The import tool writes data to PostgreSQL but does not read from it. For excessive runtimes, optimize configurations that prioritize writing while disabling unnecessary validations. The following settings have proven effective:

    max_connections = 100
shared_buffers = 1024MB
synchronous_commit = off
wal_writer_delay = 1000ms
wal_writer_flush_after = 10MB
max_wal_size = 1GB
min_wal_size = 80MB
    Use this only for excessive runtimes, and be sure to restore the original configuration after the migration is complete.

  • Start the migration on lower environments (development or test servers) and gradually move to higher environments as each migration succeeds. By the time you migrate the production instance, you'll have a clear understanding of the process, minimizing surprises.

Did this article resolve your issue ?
Knowledge Base
Did this article resolve your issue ?