This is an automated email from the ASF dual-hosted git repository.
terrymanu 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 66b9b5d0269 Add XML-driven JDBC DistSQL E2E coverage and bilingual
documentation (#40064)
66b9b5d0269 is described below
commit 66b9b5d02695f2d644dd9370425c798e346ae312
Author: Liang Zhang <[email protected]>
AuthorDate: Tue Oct 6 13:27:05 2026 +0800
Add XML-driven JDBC DistSQL E2E coverage and bilingual documentation
(#40064)
* Merge PR and nightly native test workflows
* Rename graalvm.yml to ci-graalvm.yml
* Unify Agent E2E job timeouts
* Add XML-driven JDBC DistSQL E2E coverage and bilingual documentation
---
.../shardingsphere-jdbc/java-api/_index.cn.md | 33 +++++++++++++++++++
.../shardingsphere-jdbc/java-api/_index.en.md | 33 +++++++++++++++++++
.../shardingsphere-proxy/distsql/_index.cn.md | 3 +-
.../shardingsphere-proxy/distsql/_index.en.md | 3 +-
.../param/array/E2ETestParameterGenerator.java | 7 ++--
.../distsql_rdl_empty/create_sharding_rules.xml | 38 ++++++++++++++++++++++
.../distsql_rdl_empty/select_sharding_table.xml | 24 ++++++++++++++
.../test/resources/cases/rdl/e2e-rdl-bootstrap.xml | 37 +++++++++++++++++++++
.../distsql_rdl_empty/data/actual/databases.xml | 19 +++++++++++
.../distsql_rdl_empty/data/expected/databases.xml | 19 +++++++++++
.../env/scenario/distsql_rdl_empty/rules.yaml | 20 ++++++++++++
11 files changed, 232 insertions(+), 4 deletions(-)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/_index.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/_index.cn.md
index 4ebfa8bb457..1f91469f052 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/_index.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/_index.cn.md
@@ -66,3 +66,36 @@ try (
}
}
```
+
+### 执行 DistSQL
+
+ShardingSphere-JDBC 支持通过 JDBC `Statement` 执行 DistSQL，也支持不含参数占位符的
`PreparedStatement`。
+以下示例适用于 `5.5.4-SNAPSHOT` 开发版本，使用 `Statement` 注册存储单元、创建分片规则并查询规则。
+运行示例前，请确保类路径中包含 ShardingSphere-JDBC 及 H2 JDBC 驱动。
+
+`ShardingSphereDataSourceFactory.createDataSource(databaseName, null)`
创建不含存储单元和业务规则的逻辑库。
+运行模式为 `null` 时，默认使用 Standalone 模式和 Memory 元数据仓库，配置不会在应用重启后保留。
+
+```java
+DataSource dataSource =
ShardingSphereDataSourceFactory.createDataSource("jdbc_distsql_demo", null);
+try (Connection connection = dataSource.getConnection(); Statement statement =
connection.createStatement()) {
+ statement.executeUpdate("REGISTER STORAGE UNIT ds_0
(URL='jdbc:h2:mem:jdbc_distsql_demo;MODE=MySQL',USER='sa',PASSWORD='',"
+ + "PROPERTIES('driverClassName'='org.h2.Driver'))");
+ statement.executeUpdate("CREATE SHARDING TABLE RULE t_order
(STORAGE_UNITS(ds_0),"
+ +
"SHARDING_COLUMN=user_id,TYPE(NAME='MOD',PROPERTIES('sharding-count'='1')),"
+ +
"KEY_GENERATE_STRATEGY(COLUMN=order_id,TYPE(NAME='SNOWFLAKE')))");
+ try (ResultSet resultSet = statement.executeQuery("SHOW SHARDING TABLE
RULES")) {
+ while (resultSet.next()) {
+ System.out.println(resultSet.getString("table"));
+ }
+ }
+} finally {
+ ((AutoCloseable) dataSource).close();
+}
+```
+
+使用 `executeUpdate` 执行非查询 DistSQL，使用 `executeQuery` 执行返回结果集的 DistSQL，也可以使用
`execute` 判断是否返回结果集。
+非查询 DistSQL 不能在事务中执行，应使用自动提交的连接执行此类语句。
+具体语句的可用性取决于类路径中的 DistSQL 执行器和运行模式。
+ShardingSphere-JDBC 的默认依赖不包含数据迁移和 CDC 所需的数据管道执行器。
+详细语法请参见 [DistSQL 参考](/cn/user-manual/shardingsphere-proxy/distsql/)。
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/_index.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/_index.en.md
index 36145a4435c..f380b1a36a8 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/_index.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/_index.en.md
@@ -67,3 +67,36 @@ try (
}
}
```
+
+### Execute DistSQL
+
+ShardingSphere-JDBC supports executing DistSQL through JDBC `Statement` and
through `PreparedStatement` using complete SQL strings without parameter
placeholders.
+The following example applies to the `5.5.4-SNAPSHOT` development version and
uses a `Statement` to register a storage unit, create a sharding rule, and
query the rule.
+Ensure that ShardingSphere-JDBC and the H2 JDBC driver are on the classpath
before running the example.
+
+`ShardingSphereDataSourceFactory.createDataSource(databaseName, null)` creates
a logical database without storage units or business rules.
+When the mode configuration is `null`, Standalone mode with a Memory metadata
repository is used by default, and configuration is not retained after the
application restarts.
+
+```java
+DataSource dataSource =
ShardingSphereDataSourceFactory.createDataSource("jdbc_distsql_demo", null);
+try (Connection connection = dataSource.getConnection(); Statement statement =
connection.createStatement()) {
+ statement.executeUpdate("REGISTER STORAGE UNIT ds_0
(URL='jdbc:h2:mem:jdbc_distsql_demo;MODE=MySQL',USER='sa',PASSWORD='',"
+ + "PROPERTIES('driverClassName'='org.h2.Driver'))");
+ statement.executeUpdate("CREATE SHARDING TABLE RULE t_order
(STORAGE_UNITS(ds_0),"
+ +
"SHARDING_COLUMN=user_id,TYPE(NAME='MOD',PROPERTIES('sharding-count'='1')),"
+ +
"KEY_GENERATE_STRATEGY(COLUMN=order_id,TYPE(NAME='SNOWFLAKE')))");
+ try (ResultSet resultSet = statement.executeQuery("SHOW SHARDING TABLE
RULES")) {
+ while (resultSet.next()) {
+ System.out.println(resultSet.getString("table"));
+ }
+ }
+} finally {
+ ((AutoCloseable) dataSource).close();
+}
+```
+
+Use `executeUpdate` for non-query DistSQL and `executeQuery` for DistSQL that
returns a result set, or use `execute` to determine whether a result set is
returned.
+Non-query DistSQL cannot execute within a transaction; use a connection with
auto-commit enabled for these statements.
+The availability of each statement depends on the DistSQL executors on the
classpath and the running mode.
+The default ShardingSphere-JDBC dependencies do not include the data pipeline
executors required for migration and CDC.
+For detailed syntax, see the [DistSQL
Reference](/en/user-manual/shardingsphere-proxy/distsql/).
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/_index.cn.md
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/_index.cn.md
index dc961258b02..b5693466589 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/_index.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/_index.cn.md
@@ -64,7 +64,8 @@ Resource & Rule Utility Language，负责 SQL 解析、SQL 格式化、执行计
## 使用限制
-DistSQL 只能用于 ShardingSphere-Proxy，ShardingSphere-JDBC 暂不提供。
+DistSQL 可用于 ShardingSphere-Proxy 和 ShardingSphere-JDBC。
+ShardingSphere-JDBC 的执行方式和使用限制请参见 [Java API：执行
DistSQL](/cn/user-manual/shardingsphere-jdbc/java-api/)。
## 原理介绍
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/_index.en.md
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/_index.en.md
index 8b52145983c..bd8979e6dde 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/_index.en.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/_index.en.md
@@ -64,7 +64,8 @@ Now, the user experience has been greatly improved:
## Limitations
-DistSQL can be used only with ShardingSphere-Proxy, not with
ShardingSphere-JDBC for now.
+DistSQL can be used with ShardingSphere-Proxy and ShardingSphere-JDBC.
+For JDBC execution and limitations, see [Java API: Execute
DistSQL](/en/user-manual/shardingsphere-jdbc/java-api/).
## How it works
diff --git
a/test/e2e/sql/src/test/java/org/apache/shardingsphere/test/e2e/sql/framework/param/array/E2ETestParameterGenerator.java
b/test/e2e/sql/src/test/java/org/apache/shardingsphere/test/e2e/sql/framework/param/array/E2ETestParameterGenerator.java
index 93c2e8af147..03a1bcd87fd 100644
---
a/test/e2e/sql/src/test/java/org/apache/shardingsphere/test/e2e/sql/framework/param/array/E2ETestParameterGenerator.java
+++
b/test/e2e/sql/src/test/java/org/apache/shardingsphere/test/e2e/sql/framework/param/array/E2ETestParameterGenerator.java
@@ -142,8 +142,11 @@ public final class E2ETestParameterGenerator {
if (sqlStatementClass == RALStatement.class) {
return "empty_rules".equals(scenario);
}
- if (sqlStatementClass == RDLStatement.class ||
"distsql_rdl".equals(scenario)) {
- return sqlStatementClass == RDLStatement.class &&
"distsql_rdl".equals(scenario);
+ if (sqlStatementClass == RDLStatement.class) {
+ return scenarios.isEmpty() ? "distsql_rdl".equals(scenario) :
scenarios.contains(scenario);
+ }
+ if ("distsql_rdl".equals(scenario) ||
"distsql_rdl_empty".equals(scenario)) {
+ return false;
}
if ("empty_rules".equals(scenario)) {
return false;
diff --git
a/test/e2e/sql/src/test/resources/cases/rdl/dataset/distsql_rdl_empty/create_sharding_rules.xml
b/test/e2e/sql/src/test/resources/cases/rdl/dataset/distsql_rdl_empty/create_sharding_rules.xml
new file mode 100644
index 00000000000..40de3ed172e
--- /dev/null
+++
b/test/e2e/sql/src/test/resources/cases/rdl/dataset/distsql_rdl_empty/create_sharding_rules.xml
@@ -0,0 +1,38 @@
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~ contributor license agreements. See the NOTICE file distributed with
+ ~ this work for additional information regarding copyright ownership.
+ ~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~ (the "License"); you may not use this file except in compliance with
+ ~ the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing, software
+ ~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~ See the License for the specific language governing permissions and
+ ~ limitations under the License.
+ -->
+
+<dataset>
+ <metadata>
+ <column name="table" />
+ <column name="actual_data_nodes" />
+ <column name="actual_data_sources" />
+ <column name="database_strategy_type" />
+ <column name="database_sharding_column" />
+ <column name="database_sharding_algorithm_type" />
+ <column name="database_sharding_algorithm_props" />
+ <column name="table_strategy_type" />
+ <column name="table_sharding_column" />
+ <column name="table_sharding_algorithm_type" />
+ <column name="table_sharding_algorithm_props" />
+ <column name="key_generate_column" />
+ <column name="key_generator_type" />
+ <column name="key_generator_props" />
+ <column name="auditor_types" />
+ <column name="allow_hint_disable" />
+ </metadata>
+ <row values="t_order| | ds_0| | | | | STANDARD| user_id| mod|
{"sharding-count":"1"}| order_id| snowflake| | | " />
+</dataset>
diff --git
a/test/e2e/sql/src/test/resources/cases/rdl/dataset/distsql_rdl_empty/select_sharding_table.xml
b/test/e2e/sql/src/test/resources/cases/rdl/dataset/distsql_rdl_empty/select_sharding_table.xml
new file mode 100644
index 00000000000..b3f48f046b5
--- /dev/null
+++
b/test/e2e/sql/src/test/resources/cases/rdl/dataset/distsql_rdl_empty/select_sharding_table.xml
@@ -0,0 +1,24 @@
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~ contributor license agreements. See the NOTICE file distributed with
+ ~ this work for additional information regarding copyright ownership.
+ ~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~ (the "License"); you may not use this file except in compliance with
+ ~ the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing, software
+ ~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~ See the License for the specific language governing permissions and
+ ~ limitations under the License.
+ -->
+
+<dataset>
+ <metadata>
+ <column name="order_id" />
+ <column name="user_id" />
+ </metadata>
+ <row values="1| 1" />
+</dataset>
diff --git a/test/e2e/sql/src/test/resources/cases/rdl/e2e-rdl-bootstrap.xml
b/test/e2e/sql/src/test/resources/cases/rdl/e2e-rdl-bootstrap.xml
new file mode 100644
index 00000000000..cfcd6d82468
--- /dev/null
+++ b/test/e2e/sql/src/test/resources/cases/rdl/e2e-rdl-bootstrap.xml
@@ -0,0 +1,37 @@
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~ contributor license agreements. See the NOTICE file distributed with
+ ~ this work for additional information regarding copyright ownership.
+ ~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~ (the "License"); you may not use this file except in compliance with
+ ~ the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing, software
+ ~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~ See the License for the specific language governing permissions and
+ ~ limitations under the License.
+ -->
+
+<e2e-test-cases>
+ <test-case sql="CREATE SHARDING TABLE RULE t_order
(STORAGE_UNITS(ds_0),SHARDING_COLUMN=user_id,TYPE(NAME='MOD',PROPERTIES('sharding-count'='1')),KEY_GENERATE_STRATEGY(COLUMN=order_id,TYPE(NAME='SNOWFLAKE')));"
+ db-types="H2" adapters="jdbc"
scenario-types="distsql_rdl_empty">
+ <assertion expected-data-file="create_sharding_rules.xml">
+ <initial-sql sql="REGISTER STORAGE UNIT ds_0
(URL='jdbc:h2:mem:distsql_rdl_bootstrap',USER='sa',PASSWORD='',PROPERTIES('driverClassName'='org.h2.Driver'));"
/>
+ <assertion-sql sql="SHOW SHARDING TABLE RULES;" />
+ <destroy-sql sql="DROP SHARDING KEY GENERATE STRATEGY
t_order_order_id;DROP SHARDING TABLE RULE t_order;UNREGISTER STORAGE UNIT
ds_0;" />
+ </assertion>
+ </test-case>
+
+ <test-case sql="INSERT INTO t_order (order_id,user_id) VALUES (1,1);"
db-types="H2" adapters="jdbc" scenario-types="distsql_rdl_empty">
+ <assertion expected-data-file="select_sharding_table.xml">
+ <initial-sql sql="REGISTER STORAGE UNIT ds_0
(URL='jdbc:h2:mem:distsql_rdl_bootstrap',USER='sa',PASSWORD='',PROPERTIES('driverClassName'='org.h2.Driver'));
+ CREATE SHARDING TABLE RULE t_order
(STORAGE_UNITS(ds_0),SHARDING_COLUMN=user_id,TYPE(NAME='MOD',PROPERTIES('sharding-count'='1')),KEY_GENERATE_STRATEGY(COLUMN=order_id,TYPE(NAME='SNOWFLAKE')));
+ CREATE TABLE t_order (order_id BIGINT PRIMARY KEY,user_id INT);" />
+ <assertion-sql sql="SELECT order_id,user_id FROM t_order ORDER BY
order_id;" />
+ <destroy-sql sql="DROP TABLE t_order;DROP SHARDING KEY GENERATE
STRATEGY t_order_order_id;DROP SHARDING TABLE RULE t_order;UNREGISTER STORAGE
UNIT ds_0;" />
+ </assertion>
+ </test-case>
+</e2e-test-cases>
diff --git
a/test/e2e/sql/src/test/resources/env/scenario/distsql_rdl_empty/data/actual/databases.xml
b/test/e2e/sql/src/test/resources/env/scenario/distsql_rdl_empty/data/actual/databases.xml
new file mode 100644
index 00000000000..9d43cb18050
--- /dev/null
+++
b/test/e2e/sql/src/test/resources/env/scenario/distsql_rdl_empty/data/actual/databases.xml
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~ contributor license agreements. See the NOTICE file distributed with
+ ~ this work for additional information regarding copyright ownership.
+ ~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~ (the "License"); you may not use this file except in compliance with
+ ~ the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing, software
+ ~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~ See the License for the specific language governing permissions and
+ ~ limitations under the License.
+ -->
+
+<databases />
diff --git
a/test/e2e/sql/src/test/resources/env/scenario/distsql_rdl_empty/data/expected/databases.xml
b/test/e2e/sql/src/test/resources/env/scenario/distsql_rdl_empty/data/expected/databases.xml
new file mode 100644
index 00000000000..9d43cb18050
--- /dev/null
+++
b/test/e2e/sql/src/test/resources/env/scenario/distsql_rdl_empty/data/expected/databases.xml
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~ contributor license agreements. See the NOTICE file distributed with
+ ~ this work for additional information regarding copyright ownership.
+ ~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~ (the "License"); you may not use this file except in compliance with
+ ~ the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing, software
+ ~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~ See the License for the specific language governing permissions and
+ ~ limitations under the License.
+ -->
+
+<databases />
diff --git
a/test/e2e/sql/src/test/resources/env/scenario/distsql_rdl_empty/rules.yaml
b/test/e2e/sql/src/test/resources/env/scenario/distsql_rdl_empty/rules.yaml
new file mode 100644
index 00000000000..0bd61eb64b1
--- /dev/null
+++ b/test/e2e/sql/src/test/resources/env/scenario/distsql_rdl_empty/rules.yaml
@@ -0,0 +1,20 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+databaseName: distsql_rdl_empty
+dataSources: {}
+rules: []
