Advanced Shard Routing
Available in 8.0.4 and later.
This feature will only work when the connectors are in Proxy Mode.
Advanced Shard Routing is a Connector feature that lets you route connections to different, independent clusters based on the connect-string syntax supplied by the application. It requires that your application is shard-aware — that is, it knows which service to connect to for a given operation — and enables sharding of data across clusters for greater scaling of large datasets. There is no limit to the number of clusters a Connector can route to.
Configuring the Connector
To allow a connector to route to different clusters, the connector configuration will need to include the appropriate mappings, for example, if you have 3 clusters that you want the connector to route between, your configuration may look something like:
[defaults]
user=tungsten
install-directory=/opt/continuent
profile-script=~/.bash_profile
application-user=app_user
application-password=secret
application-port=3306
rest-api-admin-user=apiuser
rest-api-admin-password=secret
connector-rest-api-address=0.0.0.0
connector-bridge-mode=false
[shard1]
topology=clustered
master=shard1_1
members=shard1_1,shard1_2,shard1_3
connectors=connshard1_1,connshard1_2,connshard1_3
[shard2]
topology=clustered
master=shard2_1
members=shard2_1,shard2_2,shard2_3
connectors=connshard2_1,connshard2_2,connshard2_3
[shard3]
topology=clustered
master=shard3_1
members=shard3_1,shard3_2,shard3_3
connectors=connshard3_1,connshard3_2,connshard3_3
Show argument definitions
user=tungstenOS System User, for example tungsten. DO NOT use root.install-directory=/opt/continuentInstallation directory.profile-script=~/.bash_profileAppend commands to include env.sh in this profile script.application-user=app_userDatabase username for the connector.application-password=secretDatabase password for the connector.application-port=3306Port for the connector to listen on.rest-api-admin-user=apiuserSpecify the initial Admin Username for API access.Available from v7.0.0rest-api-admin-password=secretSpecify the initial Admin User Password for API access. rest-api-admin-password alias only available from version 7.1.2 onwards.Available from v7.0.0connector-rest-api-address=0.0.0.0Address for the API to bind too.Available from v7.0.0connector-bridge-mode=falseEnable the Tungsten Connector bridge mode.Next you will need to update the user.map configuration. Ensuring an entry exists for any users that you intend to use the shard routing feature for. This entry
can either be in the format [user password service] or [user password], for example:
app_user secret shard1
or
app_user secret
With ONLY the [user password] example, ALL subsequent calls to the database via the connector must use the shard routing syntax to connect. A connection without specifying the additional routing syntax would error with a message similar to the following:
mysql: [Warning] Using a password on the command line interface can be insecure.
ERROR 8 (HY000): Could not authorize the user 'app_user'
Attempt to connect to the server failed.
Data Service 'shard1' does not exist.
Contact your Tungsten administrator.
With the [user password service] example, any call that does NOT specify the routing, will connect to the default service defined in the user.map entry.
Finally, you must manually update the dataservices.properties file to list every available data service. After initial installation, this file only contains an
entry for the cluster associated with the Connector host (based on the tungsten.ini configuration). Using the example above, connshard1_[1..3] will only have an entry for
shard1, connshard2_[1..3] for shard2, and so on.
To update this, edit /opt/continuent/tungsten/cluster-home/dataservices.properties. Based on the example ini configuration above, the file on ALL connector hosts will
look like the following:
shard1=shard1_1,shard1_2,shard1_3
shard2=shard2_1,shard2_2,shard2_3
shard3=shard3_1,shard3_2,shard3_3
For ease of support and debugging, it is strongly advised that the dataservices.properties file be kept in sync and identical across all connector hosts
After making all of these changes, restart the connector:
shell> connector restart
The Connectors will now allow the selection of the data service name at connection time.
Routing connections
Routing is controlled by embedding the cluster service name (e.g., shard1, shard2, or shard3 from the example above) in the connection string alongside the schema name, using the
syntax <schema>[@|#]dataservice=<service>&[Additional Optionl Routing Syntax]. For example:
shell> mysql -u app_user -psecret -h connshard1_1 -Dtest@dataservice=shard3 -P 3306
The above connects to schema test on the shard3 data service via the connector on connshard1_1.
Either the @ symbol or the # symbol can be used interchangeably.
Additional routing options can also be supplied, for example to specify the qos:
shell> mysql -u app_user -psecret -h connshard1_1 -Dtest@dataservice=shard3\&qos=RW_STRICT -P 3306
On command line calls, the & will need to be escaped as per the above example. Connection strings embedded within your applications will need to use the appropritae syntax for the libraries and language being used.
The tpm connector command will NOT work when the Advanced Shard Routing feature is configured with only the [user password] user.map syntax unless additional routing information is supplied,
for example, you will see the following error:
shell> tpm connector
mysql: [Warning] Using a password on the command line interface can be insecure.
ERROR 8 (HY000): Could not authorize the user 'app_user'
Attempt to connect to the server failed.
No data service specified. Provide it in user.map, or pass it in the database name (e.g. mydb#dataservice=<service>)
Therefore use the following syntax instead, or ensure the default service is supplied in the [user password service] format in the user.map file:
shell> tpm connector -Dtest#dataservice=shard3