Upgrade an instance - Hologres - Alibaba Cloud Documentation Center

Before you begin

Permission requirement

RAM users need the AliyunHologresFullAccess permission to perform upgrades. For more information, see Grant permissions to a RAM user.

Available upgrade methods by instance version

Major version	Minor version	Hot upgrade	Description
V1.1		Not supported	Defaults to a regular upgrade. Can be upgraded to V1.3.62 or later.
V1.3	< V1.3.62	Not supported	Defaults to a regular upgrade. Can be upgraded to V1.3.62 or later.
V1.3	>= V1.3.62	Supported	Defaults to a hot upgrade.
V2.0	< V2.0.46	Not supported	Defaults to a regular upgrade.
V2.0	>= V2.0.46	Supported	Defaults to a hot upgrade.
V2.1	< V2.1.11	Not supported	Defaults to a regular upgrade.
V2.1	>= V2.1.11	Supported	Defaults to a hot upgrade.
V2.1+		Supported	Defaults to a hot upgrade.

Note

You can only upgrade to the next immediate major version.

Hot upgrade impact

Upgrade step	Impact
Pre-checks	No impact.
Backup starts	No impact.
Backup finishes	No impact.
Writes stop	Writes blocked.
Instance version being upgraded	Writes blocked; reads briefly interrupted.
Writes recovered	Reads/writes return to normal.
Post	No impact.
Upgrade complete	No impact.

Procedure

Log on to the Hologres console. In the left navigation menu, click Instances.
Click your instance ID.
On the Instances page, click Upgrade Version in the section.
In the Upgrade Version panel, select a target version, and click Prepare Upgrade.

Select a stable major version or minor version. For more information, see Version details.
Important
The upgrade preparation runs pre-upgrade checks, including query compatibility and performance assessments:
- Instance impact: No disruption to your running instance.
- Duration: Typically 1 to 3 hours, depending on instance specifications and data volume.
- Statuses:
  - Pending Upgrade: All checks passed. You can proceed with the upgrade within 7 days. After 7 days, rerun the preparation.
  - Preparation Failed: Pre-checks identified issues (e.g., SQL compatibility, performance regressions). Submit a ticket for assistance.
After preparation completes, in the Upgrade Version panel, set Upgrade Time and click Upgrade Now.

Options:
- Start Now: Start the upgrade process immediately.
- Custom Time: Schedule when writes will pause for the upgrade. For hot upgrades, all steps before the scheduled time have no impact. Choose an appropriate time to minimize disruption.
In the dialog box, click OK to start the upgrade.

Hot upgrades typically take 10 to 30 minutes, depending on instance specifications and data volume.

Upgrade logs

All manual upgrades are logged. To query these logs, see View operation logs.

Version details

Hologres offers backward compatibility with both major and minor versions:

Major versions: Include new features and optimizations. We provide the latest and most stable major versions. For more information, see Release notes.
Minor versions: Include bug fixes. We provide the latest stable minor version for each major version. For example, if your instance is on V2.1 and Hologres releases V2.1.60, you can upgrade to V2.1.60. For more information, see Bug fixes.

We recommend upgrading regularly to the latest version to improve stability.

Upgrade costs

Upgrading your Hologres instance version is free of charge. No additional fees are incurred for the upgrade operation. Your existing billing plan remains unchanged after the upgrade.

Performance improvements

Upgrading to a later version can improve instance performance in the following ways:

New query execution path: Later versions enable a new query execution engine that replaces the legacy SQE path. This resolves slow query issues, such as queries on external tables that are routed through the old SQE path, and improves both data write and query efficiency.
Bug fixes and stability improvements: Each new version includes fixes for known defects and stability improvements. For details, see Bug fixes.

Post-upgrade parameter configuration

After an upgrade, certain experimental parameters are not enabled by default. If your workload requires specific experimental features, such as hg_experimental_external_catalog_routing, you must manually configure them after the upgrade based on your business requirements.

Hot vs. regular upgrades

Hologres supports two upgrade methods: hot upgrade (minimal downtime) and regular upgrade (service interruption). The following table compares these methods.

Note

Service unavailability during upgrades is not covered by the Service Level Agreement (SLA). Interruption duration depends on instance specifications and data volume.

Upgrade method

Upgrade duration

Impact on the instance

Impact on jobs

Notes

Regular upgrade

5 to 10 minutes

Instance is shut down. Service is unavailable.

Flink:
- For Ververica Runtime (VVR) earlier than 6.0.7 or Apache Flink earlier than 1.4.0, pause jobs writing to Hologres before upgrade and restart them after completion to prevent data loss.
- For other versions, no interruption needed. Automatic failover is provided.
DataWorks: Data integration jobs don't require pausing. Automatic failover is triggered. We recommend setting retry attempts to 10 or more for reliable job resumption.

Versions earlier than V1.3.10 only support regular upgrades.
Endpoints remain unchanged, but IP addresses may change.

Hot upgrade

10 to 30 minutes

Service is read-only during upgrade. Reads may be briefly interrupted.

V1.3.10 and later versions default to hot upgrades.
Endpoints remain unchanged, but IP addresses may change.

Upgrade methods by offering

Upgrade method support varies by instance type:

Hologres offering

Regular upgrade

Hot upgrade

Hologres General-purpose
Hologres Primary/Secondary
Hologres Virtual Warehouse

Supported

Supported (Default)

Note

For primary/secondary instances, Hologres uses a bundled upgrade strategy: the primary instance undergoes a regular upgrade, while the secondary instance undergoes a hot upgrade with brief disconnection. This minimizes disruption.

Hologres Shared Cluster

Supported (Default)

Note

Shared Cluster instances are upgraded centrally at scheduled times. See product announcements for specific times.

Not supported

Troubleshooting: Upgrade preparation errors

Sample error message	Solution
The following databases contain tables using the segment storage format. You cannot upgrade the instance to V2.0 or later. Database: xxx. Number of tables in the Segment format: xxx Database: xxx. Number of tables in the Segment format: xxx	Batch transform tables from segment to row-column format. See Batch transform tables. After transformation completes, click Terminate Upgrade, then submit a new upgrade preparation request.
The instance has a Flink job that reads binary logs using HoloHub. You cannot upgrade the instance to V2.1 or later.	See Solutions for HoloHub binary log jobs. After resolving the issue, terminate the current upgrade and submit a new preparation request.
The instance has a Flink job that accesses Hologres in remote procedure call (RPC) mode. You cannot upgrade the instance to V2.0 or later.	See Solutions for RPC mode jobs. After resolving the issue, terminate the current upgrade and submit a new preparation request.
The service-linked role does not exist. You cannot upgrade the instance to V2.2 or later.	Create a service-linked role. Then click Terminate Upgrade, and submit a new preparation request.

FAQ: Post-upgrade issues

What do I do if my instance experiences performance degradation, frequent crashes (coredump), or FE memory leaks after an upgrade?

If you encounter stability or performance issues after upgrading your Hologres instance, try the following solutions:

Upgrade to a version that includes the relevant fixes

Certain versions include fixes for known post-upgrade issues:

Version	Fix
V4.1.18 or later	Fixes coredump defects that may occur after an upgrade.
V4.1.20 or later	Fixes Frontend (FE) memory leak issues.

Check whether your current version includes these fixes. If not, upgrade to a version that includes them. We recommend that you upgrade during off-peak hours to minimize business impact.

Optimize Flink write performance

If you use Apache Flink to write data to Hologres, adjust the following Flink Sink parameters to reduce write pressure on the instance:

Parameter	Optimization
Sink parallelism	Reduce the parallelism of your Flink Sink task to decrease the number of concurrent write connections.
`sink.insert.batch-size`	Increase the value to buffer more records per batch write, which reduces the frequency of write requests.
`sink.insert.flush-interval-ms`	Increase the value to reduce how frequently data is flushed to Hologres.
`connection.pool.name`	In multi-table sync scenarios, set this parameter to the same value across multiple Sink tasks so that they share a single connection pool. This reduces total connection overhead.

Optimize resources and queries
- Enable elastic resources: Enable the elastic resource feature for your instance to automatically scale resources and handle load fluctuations during peak hours.
- Monitor and optimize queries: Use instance monitoring metrics to identify high-load periods, and optimize resource-intensive SQL queries to reduce system load.