ApsaraDB RDS:Upgrade a major version using blue-green deployment

Prerequisites

Before you begin, make sure that:

• The instance runs ApsaraDB RDS for PostgreSQL 16 or an earlier version

• The instance is not a read-only instance or a dedicated cluster instance

• Babelfish is not enabled on the instance (the minor engine version number does not end with babelfish)

Billing

When you start a blue-green deployment upgrade, the system creates a new instance based on the source instance. Both instances are billed separately until you release the source instance.

After confirming that your services run stably on the new instance, convert the new instance to subscription and release or unsubscribe from the source instance.

Potential impacts

Review the following before starting the upgrade.

Step 1: Run the pre-upgrade check

1. Log on to the ApsaraDB RDS console. In the top navigation bar, select the region where the instance resides. Find the instance and click its ID.

2. (Optional) If read-only instances exist for the source instance, change the read-only instance endpoint in your application to the primary instance endpoint during off-peak hours, then delete the read-only instance.

   Deleting read-only instances before the upgrade is necessary because read-only nodes and replication slots are not automatically transferred to the new instance. After the upgrade, create new read-only instances on the new instance.

3. In the left navigation pane, click Major Version Upgrade.

   If Major Version Upgrade is not visible, verify that your instance meets the prerequisites listed above.

4. On the Upgrade Check tab, click Create upgrade check report.

5. Select the target version, set Upgrade Mode to Blue-green Deployment, and click OK. The instance status changes to Maintaining Instance. After the check completes, the status returns to Running.

6. Review the check report result:

   • Success or Warning: proceed to Step 2.

   • Failed: click View Information, fix the issues identified, and rerun the check.

   Important

   - For a Warning result, fix all flagged items and rerun the check until the result is Success. - If you create a plugin on the primary instance after a successful check, run the check again before proceeding.

What's next

1. If you upgraded using the blue-green deployment (cutover) method, after confirming that your services run stably on the new instance, release the source instance. Convert the new instance's billing method to subscription to save costs.

   Releasing a subscription instance before expiry may result in a financial loss. The new instance does not inherit any discounts from the source instance. Refunds are subject to the actual unsubscription bill and are not processed in real time.

2. (Optional) If you deleted a read-only instance before the upgrade, recreate it on the new instance:

   1. Create a PostgreSQL read-only instance on the new instance.

   2. In your application, update the endpoint to point to the new read-only instance.

API reference

References

• Introduction to major version upgrades

• Perform a major version upgrade using the zero-downtime mode

• Perform a major version upgrade using the in-place upgrade mode

• Interpret the ApsaraDB RDS for PostgreSQL major version upgrade check report

FAQ

Can I modify the instance during a major version upgrade?

No. The instance cannot be modified while an upgrade is in progress. Modifications are available only after the upgrade completes.

Are automatic major version upgrades supported?

No. Major version upgrades must be triggered manually.

Are major version downgrades supported?

No. Downgrading is not supported after a major version upgrade. To run a lower version, purchase a new instance at that version and use Data Transmission Service (DTS) to migrate your data.

After a major version upgrade, I get a `raster_overviews` conflict when creating a view in the new instance. How do I fix this?

This issue occurs when the PostGIS version is earlier than 2.5.2 and you are upgrading from PostgreSQL 10 or 11 to PostgreSQL 12 without first upgrading the PostGIS plugin.

Step 1: Upgrade the PostGIS plugin on the source instance.

Run the following command twice to make sure the upgrade completes successfully:

SELECT PostGIS_Extensions_Upgrade();
SELECT PostGIS_Extensions_Upgrade();

Step 2: Choose the fix based on whether you use the PostGIS Raster plugin.

If the PostGIS Raster plugin is in use:

1. On the source instance, detach the raster_overviews view from the extension and replace it with a placeholder:

   ALTER EXTENSION PostGIS_Raster DROP VIEW raster_overviews;
   CREATE OR REPLACE VIEW raster_overviews AS SELECT 1;

2. Upgrade the PostgreSQL instance to at least PostgreSQL 12.

3. After the upgrade, recreate the view on the new instance:

   CREATE
   OR REPLACE VIEW raster_overviews AS
   SELECT
     current_database() AS o_table_catalog,
     n.nspname AS o_table_schema,
     c.relname AS o_table_name,
     a.attname AS o_raster_column,
     current_database() AS r_table_catalog,
     split_part(
       split_part(s.consrc, '''::name', 1),
       '''',
       2
     )::name AS r_table_schema,
     split_part(
       split_part(s.consrc, '''::name', 2),
       '''',
       2
     )::name AS r_table_name,
     split_part(
       split_part(s.consrc, '''::name', 3),
       '''',
       2
     )::name AS r_raster_column,
     trim(
       both
       from
         split_part(s.consrc, ',', 2)
     )::integer AS overview_factor
   FROM
     pg_class c,
     pg_attribute a,
     pg_type t,
     pg_namespace n,
     (
       SELECT
         connamespace,
         conrelid,
         conkey,
         pg_get_constraintdef(oid) As consrc
       FROM
         pg_constraint
     ) AS s
   WHERE
     t.typname = 'raster'::name
     AND a.attisdropped = false
     AND a.atttypid = t.oid
     AND a.attrelid = c.oid
     AND c.relnamespace = n.oid
     AND c.relkind = ANY(
       ARRAY[ 'r'::char, 'v'::char, 'm'::char,
       'f'::char ]
     )
     AND s.connamespace = n.oid
     AND s.conrelid = c.oid
     AND s.consrc LIKE '%_overview_constraint(%'
     AND NOT pg_is_other_temp_schema(c.relnamespace)
     AND has_table_privilege(c.oid, 'SELECT'::text);
   
   ALTER EXTENSION PostGIS_Raster ADD VIEW raster_overviews;

If the PostGIS Raster plugin is not in use:

1. Drop the plugin on the source instance:

   DROP EXTENSION PostGIS_Raster;

2. Upgrade the PostgreSQL instance to at least PostgreSQL 12.

How do I prevent data inconsistency caused by replication slot preemption during an upgrade?

If the source instance is a replication slot subscriber, the replication slot may be preempted by the new instance during the upgrade, which can cause data inconsistency.

To keep subscription data on the source (lower-version) instance: make sure the source instance does not fail due to excessive load during the upgrade to prevent the replication slot from being preempted. After the upgrade completes, disable the subscription on the new instance:

\c your_database
ALTER SUBSCRIPTION your_subscription_name DISABLE;

To preserve subscription data on the new (higher-version) instance: disable the subscription on the source instance before starting the upgrade, then enable it on the new instance after the upgrade completes.

Disable on the source instance:

\c your_database
ALTER SUBSCRIPTION your_subscription_name DISABLE;

Enable on the new instance:

\c your_database
ALTER SUBSCRIPTION your_subscription_name ENABLE;

For more information, see Logical Subscription and Change Tracking.

How do I handle subscription data inconsistency after an upgrade?

If inconsistency has already occurred, use the following approach to reconcile:

1. On the new instance, delete the affected table data, recreate the subscription with copy_data=true. For details, see ALTER SUBSCRIPTION.

2. Use ON CONFLICT to import data from the source instance. The following example shows how to handle different conflict scenarios:

   CREATE TABLE my_tbl(id INT PRIMARY KEY, t TIMESTAMP, val TEXT);
   
   INSERT INTO my_tbl VALUES (1, CURRENT_TIMESTAMP, 'a');
   INSERT INTO my_tbl VALUES (2, CURRENT_TIMESTAMP, 'b');
   INSERT INTO my_tbl VALUES (3, CURRENT_TIMESTAMP, 'c');
   
   -- Newer timestamp: update the existing row
   INSERT INTO my_tbl VALUES (1, CURRENT_TIMESTAMP, 'd') ON CONFLICT(id) DO UPDATE
       SET t = excluded.t,
           val = excluded.val
       WHERE my_tbl.t < excluded.t;
   
   -- Older timestamp: keep the existing row
   INSERT INTO my_tbl VALUES (2, CURRENT_TIMESTAMP - '10 hours'::interval, 'e') ON CONFLICT(id) DO UPDATE
       SET t = excluded.t,
           val = excluded.val
       WHERE my_tbl.t < excluded.t;
   
   -- New row: insert directly
   INSERT INTO my_tbl VALUES (5, CURRENT_TIMESTAMP - '10 hours'::interval, 'f') ON CONFLICT(id) DO UPDATE
       SET t = excluded.t,
           val = excluded.val
       WHERE my_tbl.t < excluded.t;

Why do I need to delete read-only instances before the upgrade?

Read-only nodes and replication slots on the source instance are not automatically transferred to the new instance after the upgrade. Deleting the read-only instance before the upgrade prevents endpoint conflicts and ensures a clean cutover. After the upgrade, create a new read-only instance on the new instance and update your application endpoint accordingly.