This is an automated email from the ASF dual-hosted git repository.
duanzhengqiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new 2144c7e support sql hint comment doc (#13874)
2144c7e is described below
commit 2144c7ea0003fca3f122b843a560fb397af011e1
Author: tuichenchuxin <[email protected]>
AuthorDate: Thu Dec 2 12:35:13 2021 +0800
support sql hint comment doc (#13874)
* support sql hint comment doc
* support sql hint comment doc
* support sql hint comment doc
* support sql hint comment doc
* support sql hint comment doc
---
.../content/features/sharding/concept/hint.cn.md | 2 +-
.../content/features/sharding/concept/hint.en.md | 2 +-
.../special-api/sharding/hint.cn.md | 45 +++++++++++++++++++++-
.../special-api/sharding/hint.en.md | 45 +++++++++++++++++++++-
.../sql/common/extractor/SQLHintExtractor.java | 2 +-
.../sql/common/extractor/SQLHintExtractorTest.java | 2 +-
6 files changed, 92 insertions(+), 6 deletions(-)
diff --git a/docs/document/content/features/sharding/concept/hint.cn.md
b/docs/document/content/features/sharding/concept/hint.cn.md
index b5e3784..b776c39 100644
--- a/docs/document/content/features/sharding/concept/hint.cn.md
+++ b/docs/document/content/features/sharding/concept/hint.cn.md
@@ -16,6 +16,6 @@ weight = 6
Apache ShardingSphere 使用 `ThreadLocal` 管理分片键值。
可以通过编程的方式向 `HintManager` 中添加分片条件，该分片条件仅在当前线程内生效。
-除了通过编程的方式使用强制分片路由，Apache ShardingSphere 还计划通过 SQL 中的特殊注释的方式引用
Hint，使开发者可以采用更加透明的方式使用该功能。
+除了通过编程的方式使用强制分片路由，Apache ShardingSphere 还可以通过 SQL 中的特殊注释的方式引用
Hint，使开发者可以采用更加透明的方式使用该功能。
指定了强制分片路由的 SQL 将会无视原有的分片逻辑，直接路由至指定的真实数据节点。
diff --git a/docs/document/content/features/sharding/concept/hint.en.md
b/docs/document/content/features/sharding/concept/hint.en.md
index 2a3e0f3..653ed0d 100644
--- a/docs/document/content/features/sharding/concept/hint.en.md
+++ b/docs/document/content/features/sharding/concept/hint.en.md
@@ -16,6 +16,6 @@ So it requires to designate sharding result externally, which
is referred to as
Apache ShardingSphere uses `ThreadLocal` to manage sharding key values.
Users can program to add sharding conditions to `HintManager`, but the
condition is only effective within the current thread.
-In addition to the programming method, Apache ShardingSphere also plans to
cite Hint through special notation in SQL, so that users can use that function
in a more transparent way.
+In addition to the programming method, Apache ShardingSphere is able to cite
Hint through special notation in SQL, so that users can use that function in a
more transparent way.
The SQL designated with sharding hint will ignore the former sharding logic
but directly route to the designated node.
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/special-api/sharding/hint.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/special-api/sharding/hint.cn.md
index 38ab5e7..4991363 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/special-api/sharding/hint.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/special-api/sharding/hint.cn.md
@@ -6,12 +6,14 @@ weight = 1
## 简介
Apache ShardingSphere 使用 ThreadLocal 管理分片键值进行强制路由。
-可以通过编程的方式向 HintManager 中添加分片值，该分片值仅在当前线程内生效。
+可以通过编程的方式向 HintManager 中添加分片值，该分片值仅在当前线程内生效。
+Apache ShardingSphere 还可以通过 SQL 中增加注释的方式进行强制路由。
Hint 的主要使用场景：
* 分片字段不存在 SQL 和数据库表结构中，而存在于外部业务逻辑。
* 强制在主库进行某些数据操作。
+* 强制在指定数据库进行某些数据操作。
## 使用方法
@@ -125,3 +127,44 @@ try (HintManager hintManager = HintManager.getInstance();
}
}
```
+
+### 使用 Hint 路由至指定数据库
+
+#### 使用手动编程的方式
+
+##### 获取 HintManager
+
+与基于 Hint 的数据分片相同。
+
+##### 设置路由至指定数据库
+
+- 使用 `hintManager.setDataSourceName` 设置数据库名称。
+
+##### 完整代码示例
+
+```java
+String sql = "SELECT * FROM t_order";
+try (HintManager hintManager = HintManager.getInstance();
+ Connection conn = dataSource.getConnection();
+ PreparedStatement preparedStatement = conn.prepareStatement(sql)) {
+ hintManager.setDataSourceName("ds_0");
+ try (ResultSet rs = preparedStatement.executeQuery()) {
+ while (rs.next()) {
+ // ...
+ }
+ }
+}
+```
+
+#### 使用 SQL 注释的方式
+
+##### 使用规范
+
+SQL Hint 功能需要用户提前开启解析注释的配置，设置 `sql-comment-parse-enabled` 为
`true`，目前只支持路由至一个数据源。
+注释格式暂时只支持`/* */`，内容需要以`sql hint:`开始，属性名为 `dataSourceName`。
+
+##### 完整示例
+```sql
+/* sql hint: dataSourceName=ds_0 */
+SELECT * FROM t_order;
+```
\ No newline at end of file
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/special-api/sharding/hint.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/special-api/sharding/hint.en.md
index fe61093..1441d9c 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/special-api/sharding/hint.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/special-api/sharding/hint.en.md
@@ -6,12 +6,14 @@ weight = 1
## Introduction
Apache ShardingSphere uses ThreadLocal to manage sharding key value or hint
route.
-Users can add sharding values to HintManager, and those values only take
effect within the current thread.
+Users can add sharding values to HintManager, and those values only take
effect within the current thread.
+Apache ShardingSphere is able to add special comments in SQL to hint route too.
Usage of hint:
* Sharding columns are not in SQL and table definition, but in external
business logic.
* Some operations forced to do in the primary database.
+* Some operations forced to do in the database chosen by yourself.
## Usage
@@ -125,3 +127,44 @@ try (HintManager hintManager = HintManager.getInstance();
}
}
```
+
+### Route to the specified database with Hint
+
+#### Use manual programming
+
+##### Get HintManager
+
+Be the same as sharding based on hint.
+
+##### Configure Database Route
+
+- Use `hintManager.setDataSourceName` to configure database route.
+
+##### Codes:
+
+```java
+String sql = "SELECT * FROM t_order";
+try (HintManager hintManager = HintManager.getInstance();
+ Connection conn = dataSource.getConnection();
+ PreparedStatement preparedStatement = conn.prepareStatement(sql)) {
+ hintManager.setDataSourceName("ds_0");
+ try (ResultSet rs = preparedStatement.executeQuery()) {
+ while (rs.next()) {
+ // ...
+ }
+ }
+}
+```
+
+#### Use special SQL comments
+
+##### Terms of Use
+
+To use SQL Hint function, users need to set `sql-comment-parse-enabled` to
`true`. Currently, only support routing to one data source.
+The comment format only supports `/* */` for now. The content needs to start
with `sql hint:`, and the attribute name needs to be `dataSourceName`.
+
+##### Codes:
+```sql
+/* sql hint: dataSourceName=ds_0 */
+SELECT * FROM t_order;
+```
\ No newline at end of file
diff --git
a/shardingsphere-sql-parser/shardingsphere-sql-parser-statement/src/main/java/org/apache/shardingsphere/sql/parser/sql/common/extractor/SQLHintExtractor.java
b/shardingsphere-sql-parser/shardingsphere-sql-parser-statement/src/main/java/org/apache/shardingsphere/sql/parser/sql/common/extractor/SQLHintExtractor.java
index 7acda03..7388cb3 100644
---
a/shardingsphere-sql-parser/shardingsphere-sql-parser-statement/src/main/java/org/apache/shardingsphere/sql/parser/sql/common/extractor/SQLHintExtractor.java
+++
b/shardingsphere-sql-parser/shardingsphere-sql-parser-statement/src/main/java/org/apache/shardingsphere/sql/parser/sql/common/extractor/SQLHintExtractor.java
@@ -32,7 +32,7 @@ public final class SQLHintExtractor {
private static final String SQL_COMMENT_SUFFIX = "*/";
- private static final String SQL_HINT_TOKEN = "shardingsphere hint:";
+ private static final String SQL_HINT_TOKEN = "sql hint:";
private static final String SQL_HINT_SPLIT = "=";
diff --git
a/shardingsphere-sql-parser/shardingsphere-sql-parser-statement/src/test/java/org/apache/shardingsphere/sql/parser/sql/common/extractor/SQLHintExtractorTest.java
b/shardingsphere-sql-parser/shardingsphere-sql-parser-statement/src/test/java/org/apache/shardingsphere/sql/parser/sql/common/extractor/SQLHintExtractorTest.java
index d2a3172..3c9fb35 100644
---
a/shardingsphere-sql-parser/shardingsphere-sql-parser-statement/src/test/java/org/apache/shardingsphere/sql/parser/sql/common/extractor/SQLHintExtractorTest.java
+++
b/shardingsphere-sql-parser/shardingsphere-sql-parser-statement/src/test/java/org/apache/shardingsphere/sql/parser/sql/common/extractor/SQLHintExtractorTest.java
@@ -36,7 +36,7 @@ public final class SQLHintExtractorTest {
@Test
public void assertFindHintDataSourceNameExist() {
AbstractSQLStatement statement = mock(AbstractSQLStatement.class);
-
when(statement.getCommentSegments()).thenReturn(Collections.singletonList(new
CommentSegment("/* shardingsphere hint: datasourceName=ds_1 */", 0, 0)));
+
when(statement.getCommentSegments()).thenReturn(Collections.singletonList(new
CommentSegment("/* sql hint: datasourceName=ds_1 */", 0, 0)));
Optional<String> dataSourceName =
SQLHintExtractor.findHintDataSourceName(statement);
assertTrue(dataSourceName.isPresent());
assertThat(dataSourceName.get(), is("ds_1"));
