Updated on 2025-08-18 GMT+08:00

Querying Versions That a DB Instance Can Be Upgraded To

Function

This API is used to query versions that a DB instance can be upgraded to. Before calling this API:

Learn how to authenticate this API.

URI

GET https://{Endpoint}/v3/{project_id}/instances/{instance_id}/db-upgrade/candidate-versions

**Table 1** Parameter description
Parameter	Mandatory	Type	Description
project_id	Yes	String	Explanation: Project ID of a tenant in a region. For details about how to obtain the value, see Obtaining a Project ID. Restrictions: None Value range: The value can contain 32 characters. Only letters and digits are allowed. Default value: None
instance_id	Yes	String	Instance ID.

Request Parameters

None

Response Parameters

**Table 2** Response Parameters
Parameter	Type	Description
upgrade_type_list	Array of Table 3 objects	Upgrade types.
rollback_enabled	Boolean	Whether rollback is supported. true: Rollback is supported. false: Rollback is not supported.
source_version	String	Source instance version.
target_version	String	Target version. The target version is only returned when the instance is in the rolling upgrade phase, or no information is returned.
roll_upgrade_progress	Table 5 object	AZ information during the rolling upgrade.
upgrade_candidate_versions	Array of strings	Versions that can be upgraded to, including minor and major versions. An empty array is returned during a rolling upgrade.
hotfix_upgrade_candidate_versions	Array of strings	Hot patch versions that can be updated.
hotfix_rollback_candidate_versions	Array of strings	Hot patch versions that can be rolled back.

**Table 3** upgrade_type_list
Parameter	Type	Description
upgrade_type	String	Upgrade type. grey: Gray upgrade inplace: In-place upgrade hotfix: Hot patch installation
enable	Boolean	Whether the upgrade type is available. true: yes. false: no.
upgrade_action_list	Array of Table 4 objects	Upgrade actions.
is_parallel_upgrade	Boolean	Whether intra-AZ parallel upgrade is supported. true: The current instance is in the rolling upgrade phase of the gray upgrade. The intra-AZ parallel upgrade is supported. Once this parameter is configured, it cannot be changed later. false: The current instance is being upgraded. The intra-AZ parallel upgrade is not supported. Once this parameter is configured, it cannot be changed later. null: The current instance is not in the upgrade process.

**Table 4** upgrade_action_list
Parameter	Type	Description
upgrade_action	String	Upgrade action. upgrade: Rolling upgrade upgradeAutoCommit: Auto-commit commit: Commit rollback: Rollback
enable	Boolean	Whether the upgrade action is available. true: yes. false: no.

**Table 5** roll_upgrade_progress
Parameter	Type	Description
not_fully_upgraded_az	String	AZs that have not been upgraded. Multiple AZs are separated by commas (,).
already_upgraded_az	String	AZs that have upgraded. Multiple AZs are separated by commas (,).
az_description_map	Map<String,String>	AZ description.

Example Request

This API is used to query versions that a DB instance can be upgraded to. Before calling this API:

GET https://gaussdb-opengauss.eu-west-101.myhuaweicloud.eu/v3/0c8243400d37468bb4aed3cc94c2911d/instances/f9b5f9b296ec6808e067in14/db-upgrade/candidate-versions

Example Response

Target version, shard status, and AZ status in the rolling upgrade returned.

{
    "upgrade_type_list": [
        {
            "upgrade_type": "grey",
            "upgrade_action_list": [
                {
                    "upgrade_action": "commit",
                    "enable": false
                },
                {
                    "upgrade_action": "rollback",
                    "enable": false
                },
                {
                    "upgrade_action": "upgrade",
                    "enable": true
                },
                {
                    "upgrade_action": "upgradeAutoCommit",
                    "enable": true
                }
            ],
            "enable": true,
            "is_parallel_upgrade": null
        },
        {
            "upgrade_type": "hotfix",
            "upgrade_action_list": null,
            "enable": false,
            "is_parallel_upgrade": null
        },
        {
            "upgrade_type": "inplace",
            "upgrade_action_list": [
                {
                    "upgrade_action": "upgradeAutoCommit",
                    "enable": true
                }
            ],
            "enable": true,
            "is_parallel_upgrade": null
        }
    ],
    "rollback_enabled": false,
    "source_version": "8.102.0",
    "target_version": null,
    "roll_upgrade_progress": {
        "not_fully_upgraded_az": "cn-southwest-244a,cn-southwest-244b,cn-southwest-244c",
        "already_upgraded_az": "",
        "az_description_map": {
            "cn-southwest-244c": "az3",
            "cn-southwest-244b": "az2",
            "cn-southwest-244a": "az1"
        }
    },
    "upgrade_candidate_versions": [
        "8.300.0",
        "8.103.0"
    ],
    "hotfix_upgrade_candidate_versions": [],
    "hotfix_rollback_candidate_versions": []
}

Status Code

Normal
200
Abnormal
For details, see Status Codes.

Error Code

For details, see Error Codes.

Parent topic: Version Upgrade