You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@shardingsphere.apache.org by pa...@apache.org on 2022/05/12 08:29:50 UTC
[shardingsphere] branch master updated: Add doc for jdbc driver (#17604)
This is an automated email from the ASF dual-hosted git repository.
panjuan 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 f0da47b8fe9 Add doc for jdbc driver (#17604)
f0da47b8fe9 is described below
commit f0da47b8fe99c605158f53c2aa1799939424e6fa
Author: Liang Zhang <zh...@apache.org>
AuthorDate: Thu May 12 16:29:45 2022 +0800
Add doc for jdbc driver (#17604)
---
.../builtin-algorithm/_index.cn.md | 2 +-
.../builtin-algorithm/_index.en.md | 2 +-
.../shardingsphere-jdbc/jdbc-driver/_index.cn.md | 82 ++++++++++++++++++++++
.../shardingsphere-jdbc/jdbc-driver/_index.en.md | 82 ++++++++++++++++++++++
.../user-manual/shardingsphere-jdbc/props.cn.md | 2 +-
.../user-manual/shardingsphere-jdbc/props.en.md | 2 +-
.../shardingsphere-jdbc/special-api/_index.cn.md | 2 +-
.../shardingsphere-jdbc/special-api/_index.en.md | 2 +-
.../spring-boot-starter/_index.cn.md | 2 +-
.../spring-boot-starter/_index.en.md | 2 +-
.../spring-namespace/_index.cn.md | 2 +-
.../spring-namespace/_index.en.md | 2 +-
.../shardingsphere-jdbc/unsupported.cn.md | 2 +-
.../shardingsphere-jdbc/unsupported.en.md | 2 +-
.../jdbc/core/driver/ShardingSphereDriverURL.java | 2 +-
15 files changed, 177 insertions(+), 13 deletions(-)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/_index.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/_index.cn.md
index 97fb0a6cd17..f4c3b240c6f 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/_index.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/_index.cn.md
@@ -1,6 +1,6 @@
+++
title = "内置算法"
-weight = 6
+weight = 7
chapter = true
+++
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/_index.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/_index.en.md
index 57f677d5540..4d0707eb606 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/_index.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/builtin-algorithm/_index.en.md
@@ -1,6 +1,6 @@
+++
title = "Builtin Algorithm"
-weight = 6
+weight = 7
chapter = true
+++
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/jdbc-driver/_index.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/jdbc-driver/_index.cn.md
new file mode 100644
index 00000000000..0ddd6de3893
--- /dev/null
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/jdbc-driver/_index.cn.md
@@ -0,0 +1,82 @@
++++
+title = "JDBC 驱动"
+weight = 3
+chapter = true
++++
+
+## 简介
+
+ShardingSphere-JDBC 提供了 JDBC 驱动,可以仅通过配置变更即可使用,无需改写代码。
+
+## 使用步骤
+
+### 引入 Maven 依赖
+
+```xml
+<dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-jdbc-core</artifactId>
+ <version>${shardingsphere.version}</version>
+</dependency>
+```
+
+### 使用驱动
+
+#### 使用原生驱动
+
+```java
+Class.forName("org.apache.shardingsphere.driver.ShardingSphereDriver"); // 或者使用标准 SPI 注册数据库驱动
+String jdbcUrl = "jdbc:shardingsphere:classpath:config.yaml";
+
+String sql = "SELECT i.* FROM t_order o JOIN t_order_item i ON o.order_id=i.order_id WHERE o.user_id=? AND o.order_id=?";
+try (
+ Connection conn = DriverManager.getConnection(jdbcUrl);
+ PreparedStatement ps = conn.prepareStatement(sql)) {
+ ps.setInt(1, 10);
+ ps.setInt(2, 1000);
+ try (ResultSet rs = preparedStatement.executeQuery()) {
+ while(rs.next()) {
+ // ...
+ }
+ }
+}
+```
+
+#### 使用数据库连接池
+
+```java
+String driverClassName = "org.apache.shardingsphere.driver.ShardingSphereDriver";
+String jdbcUrl = "jdbc:shardingsphere:classpath:config.yaml";
+
+// 以 HikariCP 为例
+HikariDataSource dataSource = new HikariDataSource();
+dataSource.setDriverClassName(driverClassName);
+dataSource.setJdbcUrl(jdbcUrl);
+
+String sql = "SELECT i.* FROM t_order o JOIN t_order_item i ON o.order_id=i.order_id WHERE o.user_id=? AND o.order_id=?";
+try (
+ Connection conn = dataSource.getConnection();
+ PreparedStatement ps = conn.prepareStatement(sql)) {
+ ps.setInt(1, 10);
+ ps.setInt(2, 1000);
+ try (ResultSet rs = preparedStatement.executeQuery()) {
+ while(rs.next()) {
+ // ...
+ }
+ }
+}
+```
+
+### 配置说明
+
+#### 驱动类名称
+
+`org.apache.shardingsphere.driver.ShardingSphereDriver`
+
+#### URL 配置说明
+
+- 以 `jdbc:shardingsphere:` 为前缀
+- 配置文件:`xxx.yaml`,配置文件格式与 [YAML 配置](/cn/user-manual/yaml-config/)一致
+- 配置文件加载规则:
+ - 无前缀表示从绝对路径加载配置文件
+ - `classpath:` 前缀表示从类路径中加载配置文件
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/jdbc-driver/_index.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/jdbc-driver/_index.en.md
new file mode 100644
index 00000000000..57e90f09bde
--- /dev/null
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/jdbc-driver/_index.en.md
@@ -0,0 +1,82 @@
++++
+title = "JDBC Driver"
+weight = 3
+chapter = true
++++
+
+## Overview
+
+ShardingSphere-JDBC provides JDBC driver, it permits user using ShardingSphere by configuration updating only, without any code changes.
+
+## Usage
+
+### Import Maven Dependency
+
+```xml
+<dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-jdbc-core</artifactId>
+ <version>${shardingsphere.version}</version>
+</dependency>
+```
+
+### Driver Usage
+
+#### Native Driver Usage
+
+```java
+Class.forName("org.apache.shardingsphere.driver.ShardingSphereDriver"); // Or use SPI to register database driver
+String jdbcUrl = "jdbc:shardingsphere:classpath:config.yaml";
+
+String sql = "SELECT i.* FROM t_order o JOIN t_order_item i ON o.order_id=i.order_id WHERE o.user_id=? AND o.order_id=?";
+try (
+ Connection conn = DriverManager.getConnection(jdbcUrl);
+ PreparedStatement ps = conn.prepareStatement(sql)) {
+ ps.setInt(1, 10);
+ ps.setInt(2, 1000);
+ try (ResultSet rs = preparedStatement.executeQuery()) {
+ while(rs.next()) {
+ // ...
+ }
+ }
+}
+```
+
+#### 方式 2. 使用数据库连接池
+
+```java
+String driverClassName = "org.apache.shardingsphere.driver.ShardingSphereDriver";
+String jdbcUrl = "jdbc:shardingsphere:classpath:config.yaml";
+
+// Use HikariCP as sample
+HikariDataSource dataSource = new HikariDataSource();
+dataSource.setDriverClassName(driverClassName);
+dataSource.setJdbcUrl(jdbcUrl);
+
+String sql = "SELECT i.* FROM t_order o JOIN t_order_item i ON o.order_id=i.order_id WHERE o.user_id=? AND o.order_id=?";
+try (
+ Connection conn = dataSource.getConnection();
+ PreparedStatement ps = conn.prepareStatement(sql)) {
+ ps.setInt(1, 10);
+ ps.setInt(2, 1000);
+ try (ResultSet rs = preparedStatement.executeQuery()) {
+ while(rs.next()) {
+ // ...
+ }
+ }
+}
+```
+
+### Configuration Explanation
+
+#### Driver Class Name
+
+`org.apache.shardingsphere.driver.ShardingSphereDriver`
+
+#### URL Configuration Explanation
+
+- Use `jdbc:shardingsphere:` as prefix
+- Configuration file: `xxx.yaml`, keep consist format with [YAML Configuration](/en/user-manual/yaml-config/)
+- Configuration file loading rule:
+ - No prefix for loading from absolute path
+ - Prefix with `classpath:` for loading from java class path
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/props.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/props.cn.md
index 7ba7fdc7bbf..8e481b4eb1c 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/props.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/props.cn.md
@@ -1,6 +1,6 @@
+++
title = "属性配置"
-weight = 5
+weight = 6
chapter = true
+++
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/props.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/props.en.md
index 5069681b9c5..dde5084b853 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/props.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/props.en.md
@@ -1,6 +1,6 @@
+++
title = "Properties Configuration"
-weight = 5
+weight = 6
chapter = true
+++
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/special-api/_index.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/special-api/_index.cn.md
index bd0d6f87a67..663bb96808f 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/special-api/_index.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/special-api/_index.cn.md
@@ -1,6 +1,6 @@
+++
title = "特殊 API"
-weight = 7
+weight = 8
chapter = true
+++
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/special-api/_index.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/special-api/_index.en.md
index 0945cf68394..95457705673 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/special-api/_index.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/special-api/_index.en.md
@@ -1,6 +1,6 @@
+++
title = "Special API"
-weight = 7
+weight = 8
chapter = true
+++
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/_index.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/_index.cn.md
index 082ce380b77..29c3b3aaacb 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/_index.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/_index.cn.md
@@ -1,6 +1,6 @@
+++
title = "Spring Boot Starter"
-weight = 3
+weight = 4
chapter = true
+++
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/_index.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/_index.en.md
index e42145508ad..1fb7fe086df 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/_index.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/_index.en.md
@@ -1,6 +1,6 @@
+++
title = "Spring Boot Starter"
-weight = 3
+weight = 4
chapter = true
+++
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/_index.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/_index.cn.md
index d2484ba3875..f3b9ea18266 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/_index.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/_index.cn.md
@@ -1,6 +1,6 @@
+++
title = "Spring 命名空间"
-weight = 4
+weight = 5
chapter = true
+++
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/_index.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/_index.en.md
index 1b1ff32c69f..27ba16a6533 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/_index.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/_index.en.md
@@ -1,6 +1,6 @@
+++
title = "Spring Namespace"
-weight = 4
+weight = 5
chapter = true
+++
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/unsupported.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/unsupported.cn.md
index 02baa8b640a..4e820f461ed 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/unsupported.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/unsupported.cn.md
@@ -1,6 +1,6 @@
+++
title = "不支持项"
-weight = 8
+weight = 9
+++
## DataSource 接口
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/unsupported.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/unsupported.en.md
index d5ae9f693d6..a78c52d4da7 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/unsupported.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/unsupported.en.md
@@ -1,6 +1,6 @@
+++
title = "Unsupported Items"
-weight = 8
+weight = 9
+++
## DataSource Interface
diff --git a/shardingsphere-jdbc/shardingsphere-jdbc-core/src/main/java/org/apache/shardingsphere/driver/jdbc/core/driver/ShardingSphereDriverURL.java b/shardingsphere-jdbc/shardingsphere-jdbc-core/src/main/java/org/apache/shardingsphere/driver/jdbc/core/driver/ShardingSphereDriverURL.java
index 1299271d9e2..b9cecfeab81 100644
--- a/shardingsphere-jdbc/shardingsphere-jdbc-core/src/main/java/org/apache/shardingsphere/driver/jdbc/core/driver/ShardingSphereDriverURL.java
+++ b/shardingsphere-jdbc/shardingsphere-jdbc-core/src/main/java/org/apache/shardingsphere/driver/jdbc/core/driver/ShardingSphereDriverURL.java
@@ -49,5 +49,5 @@ public final class ShardingSphereDriverURL {
*/
public File toConfigurationFile() {
return new File(inClasspath ? Objects.requireNonNull(ShardingSphereDriverURL.class.getResource("/" + file), String.format("Can not find configuration file `%s`", file)).getFile() : file);
- }
+ }
}