Help Center/ GaussDB/ API Reference/ APIs (Recommended)/ Version Upgrade/ Querying Versions That a DB Instance Can Be Upgraded To
Updated on 2025-08-18 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:

URI

GET https://{Endpoint}/v3.1/{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 update

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

Querying versions that a DB instance can be upgraded to

GET https://gaussdb-opengauss.eu-west-101.myhuaweicloud.eu/v3.1/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": "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": []
}

Status Code

Error Code

For details, see Error Codes.

Parent topic: Version Upgrade