PostgreSQL(DBaaS), EPAS(DBaaS) migration

Overview

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

In Samsung Cloud Platform v2, to minimize downtime during migration, it provides a feature that configures replicas using Streaming Replication and promotes them to the master server at the switchover point. Through this, users can perform migration tasks more easily.

Preliminary work

PostgreSQL(DBaaS) and EPAS(DBaaS) migration requires that a target cluster exists in Samsung Cloud Platform v2 and that the source cluster’s database in Samsung Cloud Platform is accessible.

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

• Source cluster DB Port : Target cluster IP (if HA, Active server IP / Standby server IP / VIP) -> Source cluster IP (if HA, Active server IP / Standby server IP / VIP)

This guide assumes that the server and network are properly configured in advance and outlines the items to verify before the migration.

Check Target server

When migrating PostgreSQL (DBaaS) and EPAS (DBaaS) services, the configuration parameters set in the source are taken as‑is and used. In addition, due to the automation of various service functions, we recommend configuring the Target cluster with the same setup as the Source cluster, and please review the items below.

• The Memory of the target cluster server must be greater than or equal to that of the source cluster.
• The DATA block storage capacity of the target cluster server must be greater than or equal to 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 configuration set to unused.
  • Backup
  • Audit Log Settings

Check DB user for migration configuration

The Source DB user required for migration Replication must have login replication pg_read_all_settings pg_hba_file_rules view query privileges.

If you use an existing database user in the source DB, refer to the information below to grant permissions. Please refer to the constraints below.

• username : 2~20 characters, lowercase English letters only
• password : combination of letters, numbers, and special characters, 8~30 characters

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 for the source DB, refer to the information below to create the user and grant permissions. Please refer to the constraints below.

• username : 2~20 characters, lowercase English letters only
• password : combination of letters, numbers, and special characters, 8~30 characters

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;

Check DB access control registration

For migration Replication configuration, the database’s own access control (pg_hba) rules must be applied to the Source DB for access from the Target DB. Access control rule registration can be done in the “DB Access Control Management” feature that appears when you click the three-dot button on the Source DB detail screen. After entering the screen for this function, press the [Search] button, then fill in/select the information as shown below, and click the [Add] button.

• Name: Enter in English, 3–20 characters
• Access purpose: Select Replication
• DB username: select the appropriate db user * If the DB username is not visible, please refer to the guidance message below.
• IP Address: Enter the IP required for access control registration in the specified format (e.g., 11.22.33.44/32)
• Remarks (optional): Enter appropriate content manually

If a rule has been registered, you can verify it using the following SQL statement.

SELECT * FROM pg_hba_file_rules WHERE database = 'replication';

After migration, the Target DB’s access control list matches the Source DB’s, and since each customer has distinct connection information, 0.0.0.0/0 will be automatically added if it is not already present in the access control entries. Customers who manage access control separately can, after the migration is completed, use the access control feature to exclude 0.0.0.0/0 and then appropriately register individual access controls.

Source DB - Target DB communication check

After setting DB user permissions and DB access control, access from the Target DB to the Source DB is possible.

You can use PostgreSQL’s Foreign Data Wrapper (FDW) to check whether the DB is accessible. For more details, see the PostgreSQL Document - postgres_fdw.

Check additional installed Extension

If you are using extensions that were separately requested and installed, beyond the default extensions provided with PostgreSQL (DBaaS) and EPAS (DBaaS) services, they may cause problems during migration configuration. In particular, for extensions added to the shared_preload_libraries parameter and loaded when the database starts, the database cannot start if the required module is not installed. Therefore, before configuring the migration, verify the extensions in use, and if any additional extensions have been installed, take action first.

• Install additional Extension on target cluster - Install Extension module and set shared_preload_libraries parameter

  or

• Disable additional Extension on the source cluster - Delete the Extension 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

On the top right of the Target cluster Detail page, click the Migration configuration menu to begin the migration setup.

When you click the Migration configuration menu, the Migration configuration page is displayed and you can enter information about the Source DB.

• Source DB Database name : required value. - Start with an English character and enter between 1 and 63 characters.
• Source DB IP : required value. - IP format (e.g. - Enter as 192.168.10.1)
• Source DB Port : required value. - The allowable range for port input is 1024 to 65535.
• Source DB username : required value. - Begin with an English letter and enter between 1 and 63 characters.
• Source DB password: required value. - Enter 8~30 characters, including letters, numbers, and special characters (excluding " and ‘).

Cancel

Cancel button, when selected, cancels the Migration configuration and returns to the previous screen.

Connection check

After entering the Source DB information, clicking the Check Connection button first checks the connection to the Source DB, DB user permissions, Database information, and other constraints specified in this guide. If the constraints are not met, the connection check will fail, and you must review the error message and take action.

Migration configuration complete

If the connection check succeeds, the Complete button becomes active. Complete button, when clicked, initiates the data migration setup from the Source DB; after transferring all data once, the migration configuration is considered complete only after the Replication connection succeeds. This step may take several hours or more depending on the size of the data. During migration, the cluster status is shown as Migrating, and while Migrating, you cannot perform modification operations on the Target cluster. Clicking the Migration configuration complete button will delete all data currently present in the Target DB.

Service status synchronization

After the migration configuration is completed and the target cluster’s status becomes Running, and the Master promotion button is enabled, the migration has been performed successfully. Please check the detailed information in Database > PostgreSQL(DBaaS) > PostgreSQL(DBaaS) List > PostgreSQL(DBaaS) Details > Operation History > Click Operation History > Operation History Details or Database > EPAS(DBaaS) > EPAS(DBaaS) List > EPAS(DBaaS) Details > Operation History > Click Operation History > Operation History Details. To check the current replication status, go to the detail screen of the Target DB, click the Service Status Sync button at the top right, and then you can view the replication status.

Additionally, you can run the following query directly on 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 verifying the replication status at the cut‑over point, click the Master promotion button to switch the DB to the primary server, completing the migration. The figure above. After completing the Migration configuration, go to the detail page and click the ‘Promote to Master’ button at the top right of the Target DB detail screen. After a master promotion, you can change settings on the PostgreSQL(DBaaS) Details page or the EPAS(DBaaS) Details page, just like with a regular cluster.

Constraints

• The Target cluster(s) listed below cannot be used for Migration configuration.

  • When the instance type is Replica
  • When the Master cluster has a replica
  • When not in Running state
  • When the Migration configuration has been performed but before promoting the Master (in the case where the cluster type is Migration)

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

• Once a migration is configured, modifications to the server (such as spec changes, disk addition, parameter management, etc.) are not possible.

  • After Master promotion, modify the Target cluster.