ApsaraDB RDS:Introduction to cloud migration assessment reports

Check rds empty

Check item: Check rds databases

Error message:

error:postgres not empty, check if any table exists

Impact: The migration writes data into the destination RDS instance from scratch. If the destination already contains databases or tables, the migration will fail or produce duplicate data.

Solution:

Delete all databases except template0, template1, and postgres from the ApsaraDB RDS for PostgreSQL instance. Then, in the postgres database, delete all tables except ha_health_check.

Check source connectivity

This check validates network and authentication access between the source self-managed PostgreSQL instance and the destination ApsaraDB RDS for PostgreSQL instance. It runs six sub-checks.

error:XX.XX.XX.XX is unapproachable

error:5432 is unapproachable

error:cannot connect to source database by migratetest:123456

error:migratetest has no replication privilege

error:migratetest has no createrole privilege

ALTER ROLE migratetest CREATEROLE;

error:migratetest should be a member of pg_monitor to monitor replication status

GRANT pg_monitor TO migratetest;

Check source version

Check item: Check major version consistent

Error message:

error:version mismatch, source version:10, current version:13.0

Impact: Cross-major-version migration is not supported. The migration will fail if the source and destination run different major engine versions.

Solution:

Purchase an ApsaraDB RDS for PostgreSQL instance that runs the same major engine version as the self-managed PostgreSQL instance.

Check source glibc version

Check item: Check source glibc version compatible

Warning message:

warning:source glibc version is not compatible with rds pg

Impact: The GNU C Library (glibc) version affects how PostgreSQL sorts characters in UTF-8 encoding. Version 2.28 introduced different collation orders. If the source and destination use different glibc versions, text indexes with non-C collations may return results in an unexpected order after migration, causing query correctness issues.

Solution:

Run the following diagnostic queries in order to assess the actual risk to your data.

1. Check whether the current collation order affects your data:

   • If the result is true, the collation order is not affected. No further action is needed.

   • If the result is false, continue to step 2.

   BEGIN;
   CREATE TEMP TABLE testcollation(id varchar(20) COLLATE "en_US.utf8") ON COMMIT DROP;
   INSERT INTO testcollation VALUES('-1'),('1');
   SELECT id='1' FROM testcollation ORDER BY id LIMIT 1;
   ROLLBACK;

2. Check whether any databases use non-C collations:

   • If no rows are returned, the migration does not have collation risks. No further action is needed.

   • If rows are returned, continue to step 3.

   SELECT datname, datcollate FROM pg_database WHERE datcollate NOT IN ('C', 'POSIX');

3. Identify all indexes with non-C collations across all databases:

   • If no rows are returned, the migration does not have collation risks.

   • If rows are returned, the affected indexes may produce incorrect sort results after migration. Evaluate whether these indexes affect application queries before proceeding.

   WITH result AS (
       WITH defcoll AS (
           SELECT datcollate AS coll
           FROM pg_database
           WHERE datname = current_database()
       )
       SELECT indrelid::regclass::text relname, indexrelid::regclass::text indexname,
           CASE WHEN c.collname = 'default'
               THEN defcoll.coll
               ELSE c.collname
           END AS collation
       FROM (SELECT indexrelid, indrelid, indcollation[i] coll FROM pg_index, generate_subscripts(indcollation, 1) g(i)) s
           JOIN pg_collation c ON coll=c.oid
           CROSS JOIN defcoll
       WHERE collprovider IN ('d', 'c') AND collname NOT IN ('C', 'POSIX')
   )
   SELECT result.relname, result.indexname, result.collation FROM result WHERE result.collation NOT IN ('C', 'POSIX');

Check disk size

Check item: Check disk size enough

Error message:

error:source_db_size > disk_size * 0.95

Impact: The source data must fit within 95% of the destination's available storage. If the destination storage is too small, the full backup transfer will fail partway through, leaving the destination in an incomplete state.

Solution:

1. Check the total data size on the source instance (result is in MB):

   SELECT SUM(pg_database_size(pg_database.datname))/1024/1024 AS size FROM pg_database;

2. Calculate the required storage. The destination storage must be at least 110% of the source data size. For example, if the source uses 100 GB, the destination must have at least 110 GB of available storage.

3. Expand the storage of the ApsaraDB RDS for PostgreSQL instance. For instructions, see Change instance specifications.

Check wal keep size

Check item: Check wal keep size large enough

Warning message:

warning:wal_keep_size X MB is too small. Try to set wal_keep_segments or wal_keep_size large enough ensure pg_basebackup success

Impact: During migration, pg_basebackup transfers a full snapshot of the source database. If the source generates WAL faster than pg_basebackup can copy data, and the source does not retain enough WAL segments, pg_basebackup will fail with a "WAL segment has been removed" error.

Solution:

Increase the WAL retention setting on the ApsaraDB RDS for PostgreSQL instance to reduce the risk of pg_basebackup failure:

• PostgreSQL 13 and later: Increase the value of wal_keep_size.

• Earlier than PostgreSQL 13: Increase the value of wal_keep_segments.

For PostgreSQL versions earlier than 13, the relationship between the two parameters is: wal_keep_size = wal_keep_segments × wal_segment_size.

Check spec params

Check item: Check if spec params too large

Error messages:

error:max_connections too large, value=XXX
error:max_prepared_transactions too large, value=XXX

Impact: If max_connections or max_prepared_transactions on the source instance is more than 100 times the corresponding values on the destination RDS instance, the destination instance may fail to start when the migration service establishes the replication link.

Solution:

Decrease max_connections and max_prepared_transactions on the source instance to bring them within 100 times the destination values.

Changes to max_connections and max_prepared_transactions require a restart of the source PostgreSQL instance to take effect.

Check rds user

Check item: Check if rds system user is occupied

Warning message:

warning:Check if rds system user is occupied ...XXX will be reused in rds

Impact: ApsaraDB RDS for PostgreSQL reserves the accounts aurora, replicator, and pgxxx for internal system use. If these accounts exist in the source instance, the migration may overwrite their configurations on the destination, causing management functions to break.

Solution:

Make sure that you do not use the accounts aurora, replicator, and pgxxx in the self-managed PostgreSQL instance.

Check extensions

This check validates extension compatibility between the source self-managed PostgreSQL instance and the destination ApsaraDB RDS for PostgreSQL instance. It runs three sub-checks.

error:Check source supported extensions XXX not supported

DROP EXTENSION <extension_name>;

error:Check source extensions with higher version XXX

DROP EXTENSION <extension_name>;
CREATE EXTENSION <extension_name> VERSION '<destination_version>';

warning:Check source extensions with lower version XXX

Check Postgres system catalogs

This check inspects the source instance's system catalogs for configurations that are incompatible with ApsaraDB RDS for PostgreSQL. It runs four sub-checks.

error: disallowed language exist in databases [xxx, xxx], the languages allowed are [c, internal, sql, plpgsql, pltcl, plperl].

DROP LANGUAGE <language_name>;

error: large object exist in databases [xxx, xxx].

error: default acl settings exist in databases [xxx, xxx].

warning: Invalid system tables: [pg_parameter_acl, pg_db_role_setting], these system tables should be empty.

Check reserved role permission

Check content: Check whether disallowed reserved role permissions are granted to accounts in the source instance.

Error message:

error: some disallowed reserved roles [pg_write_server_files] are granted to user. you should revoke these roles from their members

Impact: ApsaraDB RDS for PostgreSQL restricts certain built-in roles — such as pg_write_server_files — because they provide access to server file system operations that are not permitted in a managed environment. If these roles are granted to accounts in the source instance, the migration will fail.

Solution:

Revoke the disallowed reserved roles from all accounts in the source instance. For example:

REVOKE pg_write_server_files FROM "user";