Skip to content

Commit 1ee8afb

Browse files
linghengqianlinghengqian
committed
Support for executing DistSQL for ShardingSphere JDBC logical databases
1 parent 27aa738 commit 1ee8afb

File tree

15 files changed

+1518
-76
lines changed

15 files changed

+1518
-76
lines changed

‎docs/document/content/user-manual/shardingsphere-jdbc/distsql/_index.cn.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
+++
2+
title = "DistSQL"
3+
weight = 6
4+
chapter = true
5+
+++
6+
7+
# 背景信息
8+
9+
当前可以通过 ShardingSphere JDBC DataSource 执行 DistSQL，以动态修改 ShardingSphere 配置。
10+
11+
# 配置示例
12+
13+
## 前提条件
14+
15+
在业务项目引入如下依赖，
16+
17+
```xml
18+
<dependency>
19+
<groupId>org.apache.shardingsphere</groupId>
20+
<artifactId>shardingsphere-jdbc</artifactId>
21+
<version>${shardingsphere.version}</version>
22+
</dependency>
23+
<dependency>
24+
<groupId>org.apache.shardingsphere</groupId>
25+
<artifactId>shardingsphere-jdbc-dialect-mysql</artifactId>
26+
<version>${shardingsphere.version}</version>
27+
</dependency>
28+
<dependency>
29+
<groupId>org.apache.shardingsphere</groupId>
30+
<artifactId>shardingsphere-infra-data-source-pool-hikari</artifactId>
31+
<version>${shardingsphere.version}</version>
32+
</dependency>
33+
<dependency>
34+
<groupId>org.apache.shardingsphere</groupId>
35+
<artifactId>shardingsphere-infra-url-classpath</artifactId>
36+
<version>${shardingsphere.version}</version>
37+
</dependency>
38+
<dependency>
39+
<groupId>org.apache.shardingsphere</groupId>
40+
<artifactId>shardingsphere-standalone-mode-repository-memory</artifactId>
41+
<version>${shardingsphere.version}</version>
42+
</dependency>
43+
<dependency>
44+
<groupId>org.apache.shardingsphere</groupId>
45+
<artifactId>shardingsphere-sharding-core</artifactId>
46+
<version>${shardingsphere.version}</version>
47+
</dependency>
48+
<dependency>
49+
<groupId>org.apache.shardingsphere</groupId>
50+
<artifactId>shardingsphere-authority-simple</artifactId>
51+
<version>${shardingsphere.version}</version>
52+
</dependency>
53+
<dependency>
54+
<groupId>com.h2database</groupId>
55+
<artifactId>h2</artifactId>
56+
<version>2.2.224</version>
57+
</dependency>
58+
```
59+
60+
在业务项目的 classpath 上编写 ShardingSphere 数据源的配置文件 `demo.yaml`，
61+
62+
```yaml
63+
props:
64+
sql-show: false
65+
```
66+
67+
## 享受集成
68+
69+
创建 ShardingSphere 的数据源以享受集成，
70+
71+
```java
72+
import com.zaxxer.hikari.HikariConfig;
73+
import com.zaxxer.hikari.HikariDataSource;
74+
import java.sql.Connection;
75+
import java.sql.SQLException;
76+
import java.sql.Statement;
77+
public class ExampleUtils {
78+
void test() throws SQLException {
79+
HikariConfig config = new HikariConfig();
80+
config.setJdbcUrl("jdbc:shardingsphere:classpath:demo.yaml");
81+
config.setDriverClassName("org.apache.shardingsphere.driver.ShardingSphereDriver");
82+
try (HikariDataSource dataSource = new HikariDataSource(config);
83+
Connection connection = dataSource.getConnection();
84+
Statement statement = connection.createStatement()) {
85+
statement.execute("register storage unit if not exists ds_0 (url='jdbc:h2:mem:local_sharding_ds_0;MODE=MYSQL;IGNORECASE=TRUE;CASE_INSENSITIVE_IDENTIFIERS=TRUE',user='sa',password=''), ds_1 (url='jdbc:h2:mem:local_sharding_ds_1;MODE=MYSQL;IGNORECASE=TRUE;CASE_INSENSITIVE_IDENTIFIERS=TRUE',user='sa',password=''), ds_2 (url='jdbc:h2:mem:local_sharding_ds_2;MODE=MYSQL;IGNORECASE=TRUE;CASE_INSENSITIVE_IDENTIFIERS=TRUE',user='sa',password='')");
86+
statement.execute("create default sharding database strategy if not exists (type='standard', sharding_column=user_id,sharding_algorithm(type(name=class_based, properties('strategy'='STANDARD', 'algorithmClassName'='org.apache.shardingsphere.test.natived.commons.algorithm.ClassBasedInlineShardingAlgorithmFixture'))))");
87+
statement.execute("create sharding table rule if not exists t_order (datanodes('<LITERAL>ds_0.t_order, ds_1.t_order, ds_2.t_order'), key_generate_strategy(column=order_id,type(name='SNOWFLAKE'))), t_order_item (datanodes('<LITERAL>ds_0.t_order_item, ds_1.t_order_item, ds_2.t_order_item'), key_generate_strategy(column=order_item_id,type(name='SNOWFLAKE')))");
88+
statement.execute("create broadcast table rule if not exists t_address");
89+
statement.execute("CREATE TABLE IF NOT EXISTS t_order (order_id BIGINT NOT NULL AUTO_INCREMENT,order_type INT(11),user_id INT NOT NULL,address_id BIGINT NOT NULL,status VARCHAR(50),PRIMARY KEY (order_id))");
90+
statement.execute("TRUNCATE TABLE t_order");
91+
statement.execute("INSERT INTO t_order (user_id, order_type, address_id, status) VALUES (1, 1, 1, 'INSERT_TEST')");
92+
statement.execute("SELECT * FROM t_order");
93+
statement.execute("DELETE FROM t_order WHERE user_id=1");
94+
statement.execute("DROP TABLE IF EXISTS t_order");
95+
statement.execute("drop broadcast table rule if exists t_address");
96+
statement.execute("drop sharding table rule if exists t_order, t_order_item");
97+
statement.execute("drop default sharding database strategy if exists");
98+
statement.execute("unregister storage unit if exists ds_0, ds_1, ds_2");
99+
}
100+
}
101+
}
102+
```
103+
104+
# 使用限制
105+
106+
## YAML 限制
107+
108+
使用 ShardingSphere JDBC Driver 前，总是需要创建 YAML 作为配置文件。
109+
110+
## 属性限制
111+
112+
如果需要定义 YAML 配置的 `props` 属性和 `databaseName` 属性，总是需要在 YAML 文件内配置，且无法修改。
113+
可能的配置文件如下，
114+
115+
```yaml
116+
databaseName: logic_db
117+
props:
118+
sql-show: false
119+
```
120+
121+
## SQL 限制
122+
123+
若不在 YAML 配置文件内定义 `databaseName` 属性，则默认的逻辑数据库名为 `logic_db`。
124+
此时，无法针对 ShardingSphere JDBC DataSource 执行 `CREATE DATABASE sharding_db` 或 `USE sharding_db` 这类创建新的逻辑数据库的 SQL。

‎docs/document/content/user-manual/shardingsphere-jdbc/distsql/_index.en.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
+++
2+
title = "DistSQL"
3+
weight = 6
4+
chapter = true
5+
+++
6+
7+
# Background Information
8+
9+
Currently, DistSQL can be executed via ShardingSphere JDBC DataSource to dynamically modify ShardingSphere configuration.
10+
11+
# Configuration Example
12+
13+
## Prerequisites
14+
15+
Include the following dependencies in your business project:
16+
17+
```xml
18+
<dependency>
19+
<groupId>org.apache.shardingsphere</groupId>
20+
<artifactId>shardingsphere-jdbc</artifactId>
21+
<version>${shardingsphere.version}</version>
22+
</dependency>
23+
<dependency>
24+
<groupId>org.apache.shardingsphere</groupId>
25+
<artifactId>shardingsphere-jdbc-dialect-mysql</artifactId>
26+
<version>${shardingsphere.version}</version>
27+
</dependency>
28+
<dependency>
29+
<groupId>org.apache.shardingsphere</groupId>
30+
<artifactId>shardingsphere-infra-data-source-pool-hikari</artifactId>
31+
<version>${shardingsphere.version}</version>
32+
</dependency>
33+
<dependency>
34+
<groupId>org.apache.shardingsphere</groupId>
35+
<artifactId>shardingsphere-infra-url-classpath</artifactId>
36+
<version>${shardingsphere.version}</version>
37+
</dependency>
38+
<dependency>
39+
<groupId>org.apache.shardingsphere</groupId>
40+
<artifactId>shardingsphere-standalone-mode-repository-memory</artifactId>
41+
<version>${shardingsphere.version}</version>
42+
</dependency>
43+
<dependency>
44+
<groupId>org.apache.shardingsphere</groupId>
45+
<artifactId>shardingsphere-sharding-core</artifactId>
46+
<version>${shardingsphere.version}</version>
47+
</dependency>
48+
<dependency>
49+
<groupId>org.apache.shardingsphere</groupId>
50+
<artifactId>shardingsphere-authority-simple</artifactId>
51+
<version>${shardingsphere.version}</version>
52+
</dependency>
53+
<dependency>
54+
<groupId>com.h2database</groupId>
55+
<artifactId>h2</artifactId>
56+
<version>2.2.224</version>
57+
</dependency>
58+
```
59+
60+
Write the ShardingSphere data source configuration file `demo.yaml` on the classpath of your business project.
61+
62+
```yaml
63+
props:
64+
sql-show: false
65+
```
66+
67+
## Enjoy the Integration
68+
69+
Create a ShardingSphere data source to enjoy integration.
70+
71+
```java
72+
import com.zaxxer.hikari.HikariConfig;
73+
import com.zaxxer.hikari.HikariDataSource;
74+
import java.sql.Connection;
75+
import java.sql.SQLException;
76+
import java.sql.Statement;
77+
public class ExampleUtils {
78+
void test() throws SQLException {
79+
HikariConfig config = new HikariConfig();
80+
config.setJdbcUrl("jdbc:shardingsphere:classpath:demo.yaml");
81+
config.setDriverClassName("org.apache.shardingsphere.driver.ShardingSphereDriver");
82+
try (HikariDataSource dataSource = new HikariDataSource(config);
83+
Connection connection = dataSource.getConnection();
84+
Statement statement = connection.createStatement()) {
85+
statement.execute("register storage unit if not exists ds_0 (url='jdbc:h2:mem:local_sharding_ds_0;MODE=MYSQL;IGNORECASE=TRUE;CASE_INSENSITIVE_IDENTIFIERS=TRUE',user='sa',password=''), ds_1 (url='jdbc:h2:mem:local_sharding_ds_1;MODE=MYSQL;IGNORECASE=TRUE;CASE_INSENSITIVE_IDENTIFIERS=TRUE',user='sa',password=''), ds_2 (url='jdbc:h2:mem:local_sharding_ds_2;MODE=MYSQL;IGNORECASE=TRUE;CASE_INSENSITIVE_IDENTIFIERS=TRUE',user='sa',password='')");
86+
statement.execute("create default sharding database strategy if not exists (type='standard', sharding_column=user_id,sharding_algorithm(type(name=class_based, properties('strategy'='STANDARD', 'algorithmClassName'='org.apache.shardingsphere.test.natived.commons.algorithm.ClassBasedInlineShardingAlgorithmFixture'))))");
87+
statement.execute("create sharding table rule if not exists t_order (datanodes('<LITERAL>ds_0.t_order, ds_1.t_order, ds_2.t_order'), key_generate_strategy(column=order_id,type(name='SNOWFLAKE'))), t_order_item (datanodes('<LITERAL>ds_0.t_order_item, ds_1.t_order_item, ds_2.t_order_item'), key_generate_strategy(column=order_item_id,type(name='SNOWFLAKE')))");
88+
statement.execute("create broadcast table rule if not exists t_address");
89+
statement.execute("CREATE TABLE IF NOT EXISTS t_order (order_id BIGINT NOT NULL AUTO_INCREMENT,order_type INT(11),user_id INT NOT NULL,address_id BIGINT NOT NULL,status VARCHAR(50),PRIMARY KEY (order_id))");
90+
statement.execute("TRUNCATE TABLE t_order");
91+
statement.execute("INSERT INTO t_order (user_id, order_type, address_id, status) VALUES (1, 1, 1, 'INSERT_TEST')");
92+
statement.execute("SELECT * FROM t_order");
93+
statement.execute("DELETE FROM t_order WHERE user_id=1");
94+
statement.execute("DROP TABLE IF EXISTS t_order");
95+
statement.execute("drop broadcast table rule if exists t_address");
96+
statement.execute("drop sharding table rule if exists t_order, t_order_item");
97+
statement.execute("drop default sharding database strategy if exists");
98+
statement.execute("unregister storage unit if exists ds_0, ds_1, ds_2");
99+
}
100+
}
101+
}
102+
```
103+
104+
# Usage Restrictions
105+
106+
## YAML Restrictions
107+
108+
A YAML configuration file must always be created before using the ShardingSphere JDBC Driver.
109+
110+
## Property Restrictions
111+
112+
If you need to define the `props` and `databaseName` properties in the YAML configuration, you must configure them within the YAML file and cannot modify them.
113+
A possible configuration file is as follows:
114+
115+
```yaml
116+
databaseName: logic_db
117+
props:
118+
sql-show: false
119+
```
120+
121+
## SQL Restrictions
122+
123+
If the `databaseName` property is not defined in the YAML configuration file,
124+
the default logical database name is `logic_db`.
125+
In this case, you cannot execute SQL statements like `CREATE DATABASE sharding_db` or `USE sharding_db` to create a new logical database against the ShardingSphere JDBC DataSource.

‎jdbc/pom.xml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,11 @@
7373
<artifactId>shardingsphere-sql-federation-core</artifactId>
7474
<version>${project.version}</version>
7575
</dependency>
76+
<dependency>
77+
<groupId>org.apache.shardingsphere</groupId>
78+
<artifactId>shardingsphere-infra-distsql-handler</artifactId>
79+
<version>${project.version}</version>
80+
</dependency>
7681
<dependency>
7782
<groupId>org.apache.shardingsphere</groupId>
7883
<artifactId>shardingsphere-sql-parser-core</artifactId>

0 commit comments

Comments
 (0)