cdr change shardCollection

The cdr change shardCollection command changes the sharding definition that determines which database servers are part of the shard cluster.

Syntax

Notes:

¹ See Connect Option.


Element	Description	Restrictions
`ER_group`	The ER-group name of a database server that receives sharded data.	Must be the ER-group name of an existing database server.
`definition_name`	The name of the sharding definition that is modified.	Must be the name of an existing definition.
`expression`	The WHERE-clause expression that is used to select rows or documents by shard key or shard column value.
`partitions`	The number of hashing partitions on each shard server.	Must be a positive integer.
REMAINDER	Specifies the database server that receives rows or documents with shard key values that are not selected by other expressions.	Use only if the sharding definition uses an expression for distributing data.

The following table describes the cdr change shardCollection options.


Long Form	Short Form	Description
--add	-a	Adds a database server to a sharding definition.
--drop	-d	Removes a database server from a sharding definition. If the database server that is removed uses an expression for sharding, the expression is not included in the cdr change shardCollection command.
--partitions=	-p	Changes the number of hashing partitions on each shard server when the sharding strategy is consistent hashing. The more hashing partitions, the more evenly the data is distributed among shard servers. However, if you specify more than 10 hashing partitions, the resulting SQL statement to create the sharded table might fail because it exceeds the maximum character limit for an SQL statement.
--replace	-r	Replaces a sharding definition when the sharding strategy is expression.

Usage

The cdr change shardCollection command can change the database servers that are part of a shard cluster. You cannot use the cdr change shardCollection command to change the sharding strategy of a shard cluster. To change the sharding strategy, you must remove the shard cluster and then re-create it with a different sharding strategy. However, you can change certain properties of the following sharding strategies:

Consistent hash: You can change the number of hashing partitions on each shard server.
Expression: You can change the expression that is used for distributing data.

The cdr change shardCollection command creates a new sharding definition, moves existing data to appropriate shard servers, and then removes the original sharding definition.

To delete a shard server from Enterprise Replication, remove the database server from its shard cluster by running the cdr change shardCollection command and then run the cdr delete server command.

Return codes

A return code of 0 indicates that the command was successful.

If the command is not successful, one of the following error codes is returned: 39, 99, 196, 229.

For information about these error codes, see Return Codes for the cdr Utility.

Example: Adding a database server to a sharding definition that uses a hash algorithm

For this example, you have a sharding definition that is created by the following command:

cdr define shardCollection collection_1 db_1:john.customers_1
   --type=delete --key=state --strategy=hash --versionCol=version 
   g_shard_server_A
   g_shard_server_B
   g_shard_server_C

The following command adds g_shard_server_D to collection_1:

cdr change shardCollection collection_1 --add g_shard_server_D

A new sharding definition is created for collection_1. All data is redistributed to the database servers in the new sharding definition. The old sharding definition is deleted.

Example: Changing the number of hashing partitions on shard servers

For this example, you have a sharding definition with a consistent hashing strategy that is created by the following command:

cdr define shardCollection collection_1 db_1:john.customers   
   --type=delete --key=b --strategy=chash --partitions=3 --versionCol=column_3      
   g_shard_server_1 
   g_shard_server_2 
   g_shard_server_3

The following command changes the number of hashing partitions on each shard server to 4:

cdr change shardCollection collection_1 --partitions=4

The data on each shard server is redistributed into four partitions. A small amount of data might be moved between shard servers.

Example: Adding multiple database servers to a sharding definition that uses an expression

For this example, you have a sharding definition that is created by the following command:

cdr define shardCollection collection_2 db_2:joe.clients
   --type=delete --key=state --strategy=expression --versionCol=version
   g_shard_server_A "IN ('TX','OK')"
   g_shard_server_B "IN ('NY','NJ')"
   g_shard_server_C "IN ('AL','GA')"
   g_shard_server_D  REMAINDER

The following command adds the shard servers g_shard_server_E and g_shard_server_F to collection_2:

cdr change shardCollection collection_2 --add
   g_shard_server_E "IN ('CA','AZ')"
   g_shard_server_F "IN ('WA','ID')"

A new sharding definition is created for collection_2. The appropriate data from g_shard_server_D is redistributed to the new shard servers. The old sharding definition is deleted.

Example: Removing a database server from a sharding definition

For this example, you have a sharding definition that is created by the following command:

cdr define shardCollection collection_3 db_3:john.customers
   --type=delete --key=state --strategy=hash --versionCol=version
   g_shard_server_A
   g_shard_server_B
   g_shard_server_C
   g_shard_server_D

The following command removes g_shard_server_B from collection_3:

cdr change shardCollection collection_3 --drop g_shard_server_B

A new sharding definition is created for collection_3. The data is removed from g_shard_server_B. All the data is redistributed to the database servers in the new sharding definition. The old sharding definition is deleted.

Example: Replacing shard servers

For this example, you have a sharding definition that is created by the following command:

cdr define shardCollection collection_4 db_4:john.customers
   --type=delete --key=state --strategy=hash --versionCol=version
   g_shard_server_A
   g_shard_server_B
   g_shard_server_C
   g_shard_server_D

The following command changes the shard servers for collection_4 to g_shard_server_A, g_shard_server_C, g_shard_server_E, and g_shard_server_F:

cdr change shardCollection collection_4 --replace
   g_shard_server_A
   g_shard_server_C
   g_shard_server_E
   g_shard_server_F

A new sharding definition is created for collection_4. The data is removed from g_shard_server_B and g_shard_server_D. All the data is redistributed to the database servers in the new sharding definition. The old sharding definition is deleted.

Example: Replacing a sharding definition that uses an expression

For this example, you have a sharding definition that is created by the following command:

cdr define shardCollection collection_5 db_5:joe.clients
   -t delete -k unit_number -s expression -v version
   g_shard_server_A "BETWEEN 0 and 100"
   g_shard_server_B "BETWEEN 101 and 200"
   g_shard_server_C "BETWEEN 201 and 300"
   g_shard_server_D  REMAINDER

The following command changes the shard servers and the expression for collection_5:

cdr change shardCollection collection_5 -r
   g_shard_server_E "BETWEEN 0 and 100"
   g_shard_server_F "BETWEEN 101 and 200"
   g_shard_server_G "BETWEEN 201 and 200"
   g_shard_server_C "BETWEEN 301 and 400"
   g_shard_server_D  REMAINDER

A new sharding definition is created for collection_5. The data is removed from g_shard_server_A and g_shard_server_B. All the data is redistributed to the appropriate database servers in the new sharding definition. The old sharding definition is deleted.