Help Center/ GaussDB/ API Reference/ APIs (Recommended)/ Version Upgrade/ Querying Versions That a DB Instance Can Be Upgraded To

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

View PDF

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.
Obtain the required region and endpoint.

URI

GET /v3.1/{project_id}/instances/{instance_id}/db-upgrade/candidate-versions

**Table 1** Parameter description
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID of a tenant in a region. To obtain the value, see Obtaining a Project ID. Constraints N/A Range The value can contain 32 characters. Only letters and digits are allowed. Default Value N/A
instance_id	Yes	String	Definition Instance ID, which uniquely identifies an instance. Constraints N/A Range The value can contain 36 characters. Only letters and digits are allowed. Default Value N/A

Request Parameters

None

Response Parameters

**Table 2** Response parameters
Parameter	Type	Description
upgrade_type_list	Array of Table 3 objects	Definition Upgrade types.
rollback_enabled	Boolean	Definition Whether rollback is supported. Range true: Rollback is supported. false: Rollback is not supported.
source_version	String	Definition Source instance version. Range N/A
target_version	String	Definition Target version. The target version is only returned when the instance is in the rolling upgrade phase, or no information is returned. Range N/A
roll_upgrade_progress	Table 5 object	Definition DN or AZ information during the rolling upgrade.
upgrade_candidate_versions	Array of strings	Definition 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	Definition Hot patch versions that can be updated. An empty array is returned during a rolling upgrade.
hotfix_rollback_candidate_versions	Array of strings	Definition Hot patch versions that can be rolled back. An empty array is returned during a rolling upgrade.
hotfix_upgrade_infos	Array of Table 6 objects	Definition Information about hot patch versions that can be installed.
hotfix_rollback_infos	Array of Table 7 objects	Definition Information about hot patch versions that can be rolled back.

**Table 3** upgrade_type_list
Parameter	Type	Description
upgrade_type	String	Definition Upgrade type. Range grey: Gray upgrade inplace: In-place upgrade hotfix: Hot patch update
enable	Boolean	Definition Whether the upgrade type is available. Range true: yes false: no
upgrade_action_list	Array of Table 4 objects	Definition Upgrade actions.
is_parallel_upgrade	Boolean	Definition Whether intra-AZ parallel upgrade is supported. Range 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	Definition Upgrade action. Range upgrade: Rolling upgrade upgradeAutoCommit: Auto-commit commit: Commit rollback: Rollback
enable	Boolean	Definition Whether the upgrade action is available. Range true: yes false: no

**Table 5** roll_upgrade_progress
Parameter	Type	Description
upgraded_dn_group_numbers	String	Definition Number of shards that have been upgraded. Range N/A
total_dn_group_numbers	String	Definition Total number of shards. Range N/A
not_fully_upgraded_az	String	Definition AZs that have not been upgraded. Multiple AZs are separated by commas (,). For instances in the independent deployment, null is returned. Range N/A
already_upgraded_az	String	Definition AZs that have been upgraded. Multiple AZs are separated by commas (,). For instances in the independent deployment, null is returned. Range N/A
az_description_map	Map<String,String>	Definition AZ description.

**Table 6** hotfix_upgrade_infos
Parameter	Type	Description
version	String	Definition Hot patch version. Range N/A
common_patch	String	Definition Patch type. Range common: common patch certain: custom patch
backup_sensitive	Boolean	Definition Whether the patch is related to backups. Range N/A
descripition	String	Definition Description of the patch. Range N/A

**Table 7** hotfix_rollback_infos
Parameter	Type	Description
version	String	Definition Hot patch version. Range N/A
common_patch	String	Definition Patch type. Range common: common patch certain: custom patch
backup_sensitive	Boolean	Definition Whether the patch is related to backups. Range N/A
descripition	String	Definition Description of the patch. Range N/A

Example Request

Querying versions that a DB instance can be upgraded to

GET https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0483b6b16e954cb88930a360d2c4e663/instances/cc6fd964d93f4003851dfc29d57d30a5in14/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": "V2.0-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": [
        "V2.0-8.300.0",
        "V2.0-8.103.0"
    ],
    "hotfix_upgrade_candidate_versions": [],
    "hotfix_rollback_candidate_versions": [],
    "hotfix_upgrade_infos": [],
    "hotfix_rollback_infos": []
}