Solution overview-PolarDB(PolarDB)-阿里云帮助中心

Supported upgrade paths

Source version	Supported targets
PolarDB for PostgreSQL 14	15, 16, 17
PolarDB for PostgreSQL 11	14, 15, 16, 17
Standard Edition (any version)	Enterprise Edition

How it works

Major version upgrades use logical migration via DTS. The upgrade runs in two phases:

Full data synchronization — DTS copies the schema and all existing data from the source cluster to the new destination cluster.
Incremental data synchronization — DTS continuously applies ongoing changes from the source cluster to the destination cluster until you initiate the switchover.

During the switchover, services pause briefly (less than 10 minutes) to prevent new writes, and the endpoints swap between the source and destination clusters. After the switchover, the destination cluster serves traffic under the original endpoint.

Key benefits

Benefit	Details
Zero endpoint changes	The original database endpoint is retained. No application connection configuration changes are needed.
Free migration	The DTS synchronization task is free. You are only charged for the destination PolarDB cluster.
Zero data loss	The migration process guarantees no data is lost.
Minimal downtime	Less than 10 minutes of downtime during the service switchover.
Single disconnection	Only one transient disconnection occurs when the service switches from the source to the destination cluster.
Rollback support	If the upgrade fails, you can roll back within 10 minutes.

Before you start

Review these conditions before starting the upgrade. Some conditions block the upgrade entirely; others require action before or during the process.

Conditions that block the upgrade

The following configurations prevent the upgrade from starting. Resolve them first.

Condition	Action required
Source cluster has triggers	Delete all triggers before starting.
Source cluster has SSL encryption enabled	Major version upgrades are not supported. See SSL link encryption.
Source cluster has TDE enabled	Major version upgrades are not supported. See Configure TDE.
Source cluster is part of a global database network (GDN)	Major version upgrades are not supported for clusters in a GDN.

WAL log requirements

Configure the following on the source cluster before the upgrade:

Set the wal_level parameter to logical.
During full data synchronization, set the WAL log retention period to more than 7 days. During incremental synchronization, set it to more than 24 hours. An insufficient retention period may cause the synchronization task to fail, or in extreme cases, lead to data inconsistency or loss.
Check for long-running transactions on the source cluster. Long-running transactions cause WAL logs to accumulate and consume significant disk space.

Table requirements

Tables being synchronized must have a primary key or a UNIQUE constraint. Tables without these constraints may have data duplication.

For new tables or tables rebuilt using the RENAME command in the schema being synchronized, run the following command before writing data to the table:

ALTER TABLE schema.table REPLICA IDENTITY FULL;

This ensures synchronization consistency. Do not perform any table locking operations while this command is running — doing so causes a deadlock. Run this command during off-peak hours.

Restrictions during the upgrade

Do not perform the following actions while the upgrade is in progress:

Do not change parameters on the source cluster.
Do not change the zone or endpoint of the source cluster.
Do not write data to the destination cluster through any means other than DTS. Doing so causes data inconsistency.
Do not change the password or delete the migration account (dts_clone%) that the system creates on the destination cluster during the upgrade. Doing so causes DTS synchronization to fail. You can modify or delete the account after the migration is complete.

The following configurations are also not supported:

Cross-region upgrades are not supported.

If no data other than DTS data is written to the destination database, you can use Data Management (DMS) to perform online DDL operations. For more information, see Perform lock-free schema changes using lock-free change tickets.

Impact on the source cluster

Performance overhead

DTS reads from the source cluster during synchronization, which increases read load. Perform the upgrade during off-peak hours.

Temporary objects created by DTS

DTS creates the following temporary objects on the source cluster:

Temporary tables in the public schema: public.dts_pg_class, public.dts_pg_attribute, public.dts_pg_type, public.dts_pg_enum, public.dts_postgres_heartbeat, public.dts_ddl_command, and public.dts_args_session. These tables support data synchronization and heartbeat recording. Do not delete them during synchronization — doing so causes the DTS task to fail. They are automatically deleted after the DTS instance is released.
Replication slots with the prefix dts_sync_. DTS automatically cleans up historical replication slots every 120 minutes to prevent disk space accumulation.

Do not manually delete the temporary tables or replication slots. The system cleans them up automatically after the task completes.

After the DTS instance is released, DTS automatically deletes the replication slot. If you change the database password or remove the DTS IP address from the whitelist during synchronization, the replication slot cannot be deleted automatically. In this case, manually delete it from the source database to prevent disk space consumption and source cluster unavailability. When the synchronization task is released or fails, DTS automatically cleans up the replication slot. If a primary/secondary switchover occurs on the source cluster, log on to the secondary database and manually clean up the slot to prevent WAL log accumulation.

DDL operations synchronized during the upgrade

Operation type	SQL statements
DML	INSERT, UPDATE, DELETE
DDL	CREATE TABLE, DROP TABLE
DDL	ALTER TABLE (including RENAME TABLE, ADD COLUMN, ADD COLUMN DEFAULT, ALTER COLUMN TYPE, DROP COLUMN, ADD CONSTRAINT, ADD CONSTRAINT CHECK, and ALTER COLUMN DROP DEFAULT)
DDL	TRUNCATE TABLE (source PostgreSQL version 11 or later)
DDL	CREATE INDEX ON TABLE

Important

Additional clauses in DDL statements, such as CASCADE or RESTRICT, are not synchronized.
DDL operations are not supported in sessions configured with SET session_replication_role = replica.
If a single transaction on the source database contains both DML and DDL statements, the DDL statement is not synchronized.
If a single transaction on the source database contains DDL for objects outside the synchronization scope, the DDL statement is not synchronized.

DTS only verifies data content. It does not verify the metadata of database objects such as sequences. After the upgrade, manually update sequences to avoid primary key conflicts. See Update sequences manually.

Post-upgrade checklist

Complete the following after the upgrade and before switching services.

Update sequences manually

DTS does not synchronize the current value of sequences. Before switching services, run the following query on the source cluster to generate update commands for all sequences. After the switchover, run these commands on the destination cluster to avoid primary key conflicts.

DO LANGUAGE plpgsql $$
DECLARE
  nsp NAME;
  rel NAME;
  val INT8;
BEGIN
  FOR nsp, rel IN SELECT nspname, relname FROM pg_class t2, pg_namespace t3 WHERE t2.relnamespace = t3.oid AND t2.relkind = 'S' LOOP
    EXECUTE format($_$SELECT last_value FROM %I.%I$_$, nsp, rel) INTO val;
    RAISE NOTICE '%', format($_$SELECT setval('%I.%I'::regclass, %s);$_$, nsp, rel, val + 1);
  END LOOP;
END;
$$;

Check destination cluster disk usage

During full data synchronization, table fragmentation can occur. As a result, the tablespace usage on the destination cluster may be larger than on the source cluster. This is expected behavior.

Endpoint switchover

Upgrades between PolarDB clusters support endpoint switchover. The system automatically swaps the endpoints of the source and destination clusters. The following diagram shows the endpoint mapping:

Note the following when using the endpoint switchover feature:

The endpoint switchover swaps only the domain names of the source and destination clusters. Configurations such as VSwitches and virtual IP addresses (VIPs) are not switched.
Endpoints can be swapped only if both clusters have corresponding endpoints. By default, only private endpoints support switchover.

If the source cluster has a public endpoint, create a corresponding public endpoint for the destination cluster before the switchover to ensure it succeeds.

When you select endpoint switchover, the primary endpoints of the source and destination clusters are always switched. Switching other endpoint groups is optional.
To switch other endpoints, create the corresponding endpoints before the switchover. Endpoints not created before the switchover will not be switched.
The endpoint switchover does not switch ports. Make sure the source and destination clusters use the same connection port. The default port for PolarDB is 5432.
After the domain name is switched, DNS cache issues may occur. Before the cache expires, you may be unable to connect to the database, or the database may become read-only. Refresh the DNS cache on your server.

FAQ

Do I need to purchase a PolarDB for PostgreSQL cluster before the upgrade?

No. A new PolarDB cluster with the same data as the source cluster is created automatically during the upgrade process.

Will the upgrade affect normal operations on the source cluster?

The upgrade does not interrupt operations on the source cluster. However, DTS reads from the source cluster during synchronization, which consumes some query performance. Some parameters also require modification, and certain operational restrictions apply during the upgrade. For details, see Impact on the source cluster.

How long is the service downtime during the upgrade?

The downtime is less than 10 minutes. During this period, services pause to prevent new writes, but the database is not shut down. Rollback is also supported if needed.

Are cross-version upgrades supported, for example from PostgreSQL 11 to PostgreSQL 16?

Yes, cross-version upgrades are supported. See Supported upgrade paths for all valid combinations.

If a DTS data synchronization task is already running on the source cluster, will the upgrade affect it?

No. During the upgrade, DTS copies full data from the source cluster to a new PolarDB cluster and then synchronizes incremental data. The existing DTS task on the source cluster continues to read from the source cluster without interruption.

However, after the migration is complete and you switch services to the new cluster, the existing DTS task does not automatically update its data source. Create a new DTS synchronization task and set the data source to the new PolarDB cluster.