PostgreSQL(DBaaS), EPAS(DBaaS) Migration

Overview

This guide provides the procedure and tasks for migrating PostgreSQL(DBaaS), EPAS(DBaaS) services created on Samsung Cloud Platform to Samsung Cloud Platform v2.

Samsung Cloud Platform v2 provides a feature to configure a replica using the Streaming Replication method during migration and promote it to a master server at the time of switching, minimizing downtime during migration. This allows users to perform migration tasks more easily.

Pre-migration Tasks

To migrate PostgreSQL(DBaaS), EPAS(DBaaS), a target cluster must exist on Samsung Cloud Platform v2, and access to the DB of the source cluster on Samsung Cloud Platform must be possible.

By default, network communication must be possible for the following ports:

• Source cluster DB port: Target cluster IP (in case of HA, Active server IP / Standby server IP / VIP) -> Source cluster IP (in case of HA, Active server IP / Standby server IP / VIP)

This guide assumes that the server and network are normally configured in advance and provides items to be checked before migration.

Target Server Check

When migrating PostgreSQL(DBaaS), EPAS(DBaaS) services, the configuration parameters set in the original are used as is. In addition, due to the automation processing of various functions of the service, it is recommended to configure the target cluster with the same configuration as the source cluster, and the following items should be checked:

• The memory of the target cluster server must be larger or the same as that of the source cluster.
• The data block storage capacity of the target cluster server must be larger or the same as that of the source cluster.
• The following configuration information of the target cluster must be the same as that of the source cluster:
  • Image version
  • Database name
  • Database username
  • Database port number
  • Database encoding
  • DB locale
  • Time zone
• The target cluster must have the following configurations set to unused:
  • Backup
  • Audit log settings

Migration Configuration DB User Check

The source DB user required for replication for migration must have login, replication, pg_read_all_settings, and pg_hba_file_rules view query permissions.

If you use an existing DB user in the source DB, please refer to the following content to grant permissions:

ALTER USER user_name WITH LOGIN REPLICATION;

GRANT pg_read_all_settings TO user_name;

GRANT SELECT ON pg_hba_file_rules TO user_name;
GRANT EXECUTE ON FUNCTION pg_hba_file_rules TO user_name;

If you create a new DB user in the source DB and use it, please refer to the following content to create and grant permissions:

CREATE USER user_name WITH LOGIN REPLICATION PASSWORD 'user_password';

GRANT pg_read_all_settings TO user_name;

GRANT SELECT ON pg_hba_file_rules TO user_name;
GRANT EXECUTE ON FUNCTION pg_hba_file_rules TO user_name;

DB Access Control Registration Check

To configure replication for migration, the DB’s access control (pg_hba) rules must be applied to the source DB so that the target DB can access it. However, registering access control rules is difficult for users to do directly due to OS access restrictions. A rule registration request is required through Samsung Cloud Platform 1:1 inquiry.

If the rule registration is done, you can check it using the following SQL statement:

SELECT * FROM pg_hba_file_rules WHERE database = 'replication';

Source DB - Target DB Communication Check

After setting DB user permissions and DB access control, the target DB can access the source DB.

You can check the availability of DB access using PostgreSQL’s Foreign-Data Wrapper (FDW). For more information, please refer to PostgreSQL Document - postgres_fdw.

Checking for Additional Installed Extensions

In the PostgreSQL (DBaaS) and EPAS (DBaaS) services, if you are using extensions that are not installed by default but are installed separately, there may be issues when configuring migration. Especially, if an extension is loaded at DB startup due to the shared_preload_libraries parameter setting and the required module is not installed, DB startup will not be possible. Therefore, before configuring migration, you need to check which extensions are in use and take action if there are any additional installed extensions.

• Install additional extensions on the target cluster - Install extension modules and set the shared_preload_libraries parameter

  or

• Disable additional extensions on the source cluster - Delete extensions and set the shared_preload_libraries parameter

Migration Procedure

Migration Configuration

Migration configuration can be requested through the following menu.

• PostgreSQL (DBaaS): Database > PostgreSQL (DBaaS) > PostgreSQL (DBaaS) List > PostgreSQL (DBaaS) Details > Migration Configuration
• EPAS (DBaaS): Database > EPAS (DBaaS) > EPAS (DBaaS) List > EPAS (DBaaS) Details > Migration Configuration

You can start the migration configuration by clicking the Migration Configuration menu at the top right of the target cluster Details page.

When you click the Migration Configuration menu, the Migration Configuration page appears, and you can enter information about the source DB.

• Source DB Database Name: Required value. Enter a value that starts with a letter and is between 1 and 63 characters long.
• Source DB IP: Required value. Enter an IP address in the format (e.g., 192.168.10.1).
• Source DB Port: Required value. The port input range is 1024-65535.
• Source DB Username: Required value. Enter a value that starts with a letter and is between 1 and 63 characters long.
• Source DB Password: Required value. Enter a value that includes letters, numbers, and special characters (excluding “) and is between 8 and 30 characters long.

Cancel

If you select the Cancel button, the migration configuration will be canceled, and you will return to the previous screen.

Connection Check

After entering the source DB information, click the Connection Check button to check the connection to the source DB, DB user privileges, database information, and other constraints specified in this guide. If the constraints are not met, the connection check will fail, and you will need to check the error message and take action.

Completing Migration Configuration

If the connection check is successful, the Complete button will be activated. Clicking the Complete button will start the data migration configuration from the source DB, and the entire data will be migrated once, followed by a successful replication connection. This step may take several hours or more, depending on the size of the data. During migration, the cluster status will be displayed as Migrating, and you will not be able to perform modification work on the target cluster. When you click the Complete button, all existing data in the target DB will be deleted.

Service Status Synchronization

When the migration configuration is complete, and the target cluster status is Running, and the Master Promotion button is activated, the migration has been performed normally. You can check the details in Database > PostgreSQL (DBaaS) > PostgreSQL (DBaaS) List > PostgreSQL (DBaaS) Details > Work History > Work Details or Database > EPAS (DBaaS) > EPAS (DBaaS) List > EPAS (DBaaS) Details > Work History > Work Details. To check the current replication status, click the Service Status Synchronization button at the top right of the target DB details page and check the replication status. Additionally, you can execute the following query directly in the DB to check the detailed replication status.

• Source Cluster

  SELECT * FROM pg_stat_replication;
  

• Target Cluster

  SELECT * FROM pg_stat_wal_receiver;
  

Master Promotion

After checking the replication status at the cutover point, click the Master Promotion button to switch the DB to the primary server, completing the migration. As shown in the figure, Migration Configuration Complete, click the Master Promotion button at the top right of the target DB details page. After master promotion, you can change setting values on the PostgreSQL (DBaaS) Details page or EPAS (DBaaS) Details page, just like a normal cluster.

Constraints

• The following Target clusters cannot perform Migration configuration:

  • If the instance type is Replica
  • If it is a Master cluster with a Replica
  • If it is not in a Running state
  • If it is before performing Migration configuration and Master promotion (in the case of a cluster type of Migration)

• The Target cluster can perform migration after turning off Audit logs and Backup settings.

• Once Migration is configured, modification work (such as Spec change, Disk addition, Parameter management, etc.) on the server is not possible.

  • After Master promotion, please modify the Target cluster.