Docs

Cache for Redis

Modifying instance configuration

EnableShardedCluster

Call the EnableShardedCluster API to change an instance with sharding cluster disabled to an instance with sharding cluster enabled.

Request type

Asynchronous request.

Precautions

Once instance is changed from sharding cluster disabled to sharding cluster enabled, it cannot be reversed.

Changing the sharding cluster status from disabled to enabled only alters the architecture of the instance, with the instance type, availability zone, connection address, and other attributes remaining unchanged.

After changing instance with sharding cluster disabled to sharding cluster enabled, the instance architecture changes, and there will be differences in limits concerning Lua script usage, multi-key commands, transaction commands, and other commands. For more information about command limits, refer to Command limits.

During the change process, the instance might prompt the error -TRYAGAIN The specific keys are being migrated.\r\n, or experience one or two temporary disconnections, each less than 30 seconds. Proceed with caution. It is recommended to perform configuration changes during off-peak hours and ensure that the client is configured with a proper retry mechanism.

Initiating a configuration change after enabling data flashback will automatically disable the data flashback feature. After the data flashback feature is disabled, previous flashback points will no longer be retained. For more details, refer to Setting data flashback.

Only instances of sharding clusters that are not enabled (i.e. 0 for ShardedCluster) need to call this API. For more details, see Modifying sharding cluster configuration.

Debugging

API Explorer

You can initiate calls online through API Explorer without paying attention to the signature generation process and quickly obtain the call results.

Go to debug

Request parameters

Parameters	Type	Required	Example	Description
InstanceId	String	Yes	redis-cn0212gzmh2xs****	Instance ID. tip You can call the DescribeDBInstances API to query the basic information of all Redis instances in the target region, including the instance ID.
ApplyImmediately	Boolean	Yes	true	Whether to execute the configuration modification immediately. Valid values: true: Execute now. false: Execute modification within the maintenance period. tip For more information on maintenance periods, refer to Setting maintenance period.
ShardedCluster	Integer	Yes	1	Whether to enable sharding cluster. Valid values: 0: Disable. 1: Enable. tip You can only change an instance with sharding cluster disabled to an instance with sharding cluster enabled. Therefore, the value must be 1.
ShardNumber	Integer	Yes	2	Number of shards in the instance. Value range: 2 to 256.
ShardCapacity	Integer	No	1024	Memory capacity of each shard, unit: MiB. Value range: 1024, 2048, 4096, 8192, 16384. tip If this parameter is empty, the original single-shard capacity will be used as the ShardCapacity after enabling the sharding cluster by default. However, the single-shard capacity specifications supported by Redis instances with sharding cluster disabled and enabled are different. If a single-shard capacity not supported by the instances with sharding cluster enabled is used, an error will occur when calling this API. For more details about Redis instance specifications, refer to Product specifications. You can call the DescribeDBInstanceDetail API to query the detailed information of a specified instance, including the current number of nodes in each shard. To reduce the number of shards, ensure that the instance's current used memory does not exceed 85% of the new total memory capacity (total capacity = single shard capacity x shard count). Each instance specification has its corresponding supported shard capacity and bandwidth. When modifying the instance shard capacity, the instance bandwidth and type are modified as well. For more information on Redis instance specifications, refer to Product specifications.
CreateBackup	Boolean	No	true	Whether to create a full backup before the change. Valid values: true: Create a backup. false (default value): Do not create. tip This parameter is only effective for primary-secondary instances (i.e., InstanceClass is PrimarySecondary). Single node instances (i.e., when InstanceClass is Standalone) do not support the backup feature, so this parameter does not need to be set. You can call the DescribeDBInstanceDetail API to query the detailed information of the specified instance, including the instance type.
BackupPointName	String	No	testbackup	Set the backup name for the full backup created before the change. If no backup name is set, the backup ID is used as the name by default. If you need to set a backup name, it must meet the following conditions: It should start with a Chinese character, a letter, or an underscore (_). The length should be between 1 and 128 characters. It can only contain Chinese characters, letters, digits, underscores (_), and hyphens (-). tip This parameter takes effect only when the need to create a backup before the change is selected (that is, CreateBackup is true).
ClientToken	String	No	WbiAlPqJM6tMoSOYhT****	To ensure the idempotence of requests and prevent duplicate submission of requests. The client generates the parameter values to ensure the uniqueness among different requests. Values are case-sensitive, no more than 127 ASCII characters.

Response parameters

Parameters	Type	Example	Description
OrderNO	String	Order716986589022527****	Order ID.

Example

Request example

POST https://redis.cn-beijing.volcengineapi.com/?Action=EnableShardedCluster&Version=2020-12-07 HTTP/1.1​
Host: redis.cn-beijing.volcengineapi.com​
Content-Type: application/json; charset=utf-8​
X-Date: 20201103T104027Z​
Authorization: HMAC-SHA256 Credential=AK****/20201103/cn-beijing/Redis/request,SignedHeaders=content-type;host;x-date,Signature=****​
{​
        "InstanceId": "redis-cn0212gzmh2xs****",​
        "ApplyImmediately": true,​
        "ShardedCluster":1,​
        "ShardNumber":2,​
        "CreateBackup": true​
}​

Response example

{​
        "ResponseMetadata": {​
                "RequestId": "20230509153711EDF4F0D1DBEFA625xxxx",​
                "Action": "EnableShardedCluster",​
                "Version": "2020-12-07",​
                "Service": "Redis",​
                "Region": "cn-beijing"​
        },​
        "Result": {​
                "OrderNO": "Order723108288213844****"​
        }​
}​

Error code

For more details, see Error code.

Last updated: 2026.09.21 15:01:09