TeslaCN commented on code in PR #19791: URL: https://github.com/apache/shardingsphere/pull/19791#discussion_r935323101
########## docs/blog/content/material/2022_04_13_A_Practical_Guide_to_Apache_ShardingSphere's_HINT.en.md: ########## @@ -0,0 +1,382 @@ ++++ +title = "A Practical Guide to Apache ShardingSphere’s HINT" +weight = 49 +chapter = true ++++ + +## Background +[Apache ShardingSphere](https://shardingsphere.apache.org/) has gradually introduced various features based on practical user requirements, such as data sharding and read/write splitting. + +The data sharding feature contains many practical sharding strategies such as Standard Sharding Strategy and Complex Sharding Strategy, and users can easily configure the corresponding sharding algorithms. + +When it comes to Read/Write Splitting, Apache ShardingSphere provides users with two types called Static and Dynamic, and abundant load balancing algorithms. + +Sharding and Read/Write Splitting functions of ShardingSphere are already very useful, but scenarios are ever-changing. + +Take a multi-tenant case as an example: a user expects to shard data according to the tenant to which the login account belongs, but the tenant information does not exist in every business SQL. In this case, the algorithm for extracting sharding fields from SQL is not feasible. + +Additionally, in most read/write splitting scenarios, users want to route queries to the secondary database for execution, but in some scenarios with a requirement for real-time operations, users want to route SQL to the primary database for execution. Currently, read/write splitting cannot meet business requirements. + +Considering the above-mentioned pain points, Apache ShardingSphere created the `Hint` function to allow users to utilize different logic rather than SQL to implement forced routing or sharding. + +Currently, ShardingSphere provides users with two `Hint` methods. One is a manual programming method with Java API and uses `HintManager` for forced routing and sharding. This method is very friendly to applications programmed with JDBC because developers don’t need to write too much code and can easily implement SQL-independent sharding or forced routing functions. + +Based on distributed SQL ([DistSQL](https://opensource.com/article/21/9/distsql), ShardingSphere designed `SQL HINT` and `DistSQL HINT` to provide users with sharding and forced routing functions that can be implemented without coding. The method is more friendly to database administrators (DBAs). + +Next, let’s take a close look at the two methods. + +## Manual Programming Based on HintManager + +ShardingSphere can implement the functions of forced route and sharding via the `HintManager` objects. With `HintManager`, users can complete data sharding without SQL. It also allows users to shard data or force routing more flexibly, greatly expanding user scenarios. + +At the moment, with the help of `HintManager`, users can utilize ShardingSphere’s built-in or custom `Hint` algorithms to implement the sharding function, and can set specified data source or force primary database to do read/write splitting to implement the forced routing function. + +I’d like to explain its basic implementation principle first to help you gain a better understanding of `HintManager`. + +- **The Implementation of HintManager** +The code snippet below can help you quickly understand the principle of `HintManager`. + +``` +@NoArgsConstructor(access = AccessLevel.PRIVATE) +public final class HintManager implements AutoCloseable { + + private static final ThreadLocal<HintManager> HINT_MANAGER_HOLDER = new ThreadLocal<>(); +} +``` + +As shown above, ShardingSphere implements the function of `HintManager` with `ThreadLocal`: as long as they are in the same thread, user’s sharding settings are preserved. Therefore, the user only needs to call relevant `HintManager` functions before executing SQL statements, and then ShardingSphere can obtain the sharding or mandatory routing conditions set by the user in the current thread so as to perform sharding or routing operations. + +Next, let’s learn how to use it. + +- **How to Use HitManager** + +1. Use `HINT` for Sharding +To use the `Hint Sharding Algorithm`, users are required to implement the interface `org.apache.shardingsphere.sharding.api.sharding.hint.HintShardingAlgorithm`. When Apache ShardingSphere performs routing, it will obtain shard values from `HintManager` for routing operations. + +> **The configuration is as follows:** + +``` +rules: +- !SHARDING + tables: + t_order: + actualDataNodes: demo_ds_${0..1}.t_order_${0..1} + databaseStrategy: + hint: + algorithmClassName: xxx.xxx.xxx.HintXXXAlgorithm + tableStrategy: + hint: + algorithmClassName: xxx.xxx.xxx.HintXXXAlgorithm + defaultTableStrategy: + none: + defaultKeyGenerateStrategy: + type: SNOWFLAKE + column: order_id + +props: + sql-show: true +``` + +> **Get the HintManager instance:** + +``` Review Comment: ```suggestion ```java ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
