Add documentation for P6Spy support

apache · Dec 14, 2024 · ad2cc69 · ad2cc69
1 parent 2c9996e
commit ad2cc69
Show file tree

Hide file tree

Showing 16 changed files with 465 additions and 134 deletions.
diff --git a/...ument/content/user-manual/shardingsphere-jdbc/graalvm-native-image/_index.cn.md b/...ument/content/user-manual/shardingsphere-jdbc/graalvm-native-image/_index.cn.md
@@ -47,7 +47,7 @@ java.beans.Introspector was unintentionally initialized at build time. To see wh
             <plugin>
                 <groupId>org.graalvm.buildtools</groupId>
                 <artifactId>native-maven-plugin</artifactId>
-                <version>0.10.3</version>
+                <version>0.10.4</version>
                 <extensions>true</extensions>
                 <configuration>
                     <buildArgs>
@@ -85,12 +85,12 @@ java.beans.Introspector was unintentionally initialized at build time. To see wh
 
 ```groovy
 plugins {
-   id 'org.graalvm.buildtools.native' version '0.10.3'
+   id 'org.graalvm.buildtools.native' version '0.10.4'
 }
 
 dependencies {
    implementation 'org.apache.shardingsphere:shardingsphere-jdbc:${shardingsphere.version}'
-   implementation(group: 'org.graalvm.buildtools', name: 'graalvm-reachability-metadata', version: '0.10.3', classifier: 'repository', ext: 'zip')
+   implementation(group: 'org.graalvm.buildtools', name: 'graalvm-reachability-metadata', version: '0.10.4', classifier: 'repository', ext: 'zip')
 }
 
 graalvmNative {

diff --git a/...ument/content/user-manual/shardingsphere-jdbc/graalvm-native-image/_index.en.md b/...ument/content/user-manual/shardingsphere-jdbc/graalvm-native-image/_index.en.md
@@ -49,7 +49,7 @@ and the documentation of GraalVM Native Build Tools shall prevail.
              <plugin>
                  <groupId>org.graalvm.buildtools</groupId>
                  <artifactId>native-maven-plugin</artifactId>
-                 <version>0.10.3</version>
+                 <version>0.10.4</version>
                  <extensions>true</extensions>
                  <configuration>
                     <buildArgs>
@@ -89,12 +89,12 @@ Reference https://github.com/graalvm/native-build-tools/issues/572 .
 
 ```groovy
 plugins {
-   id 'org.graalvm.buildtools.native' version '0.10.3'
+   id 'org.graalvm.buildtools.native' version '0.10.4'
 }
 
 dependencies {
    implementation 'org.apache.shardingsphere:shardingsphere-jdbc:${shardingsphere.version}'
-   implementation(group: 'org.graalvm.buildtools', name: 'graalvm-reachability-metadata', version: '0.10.3', classifier: 'repository', ext: 'zip')
+   implementation(group: 'org.graalvm.buildtools', name: 'graalvm-reachability-metadata', version: '0.10.4', classifier: 'repository', ext: 'zip')
 }
 
 graalvmNative {

diff --git a/...ual/shardingsphere-jdbc/unsupported.cn.md → ...rdingsphere-jdbc/unsupported/_index.cn.md b/...ual/shardingsphere-jdbc/unsupported.cn.md → ...rdingsphere-jdbc/unsupported/_index.cn.md
diff --git a/...ual/shardingsphere-jdbc/unsupported.en.md → ...rdingsphere-jdbc/unsupported/_index.en.md b/...ual/shardingsphere-jdbc/unsupported.en.md → ...rdingsphere-jdbc/unsupported/_index.en.md
diff --git a/...document/content/user-manual/shardingsphere-jdbc/unsupported/p6spy/_index.cn.md b/...document/content/user-manual/shardingsphere-jdbc/unsupported/p6spy/_index.cn.md
@@ -0,0 +1,154 @@
++++
+title = "P6Spy"
+weight = 6
++++
+
+## 背景信息
+
+ShardingSphere 通过 `org.apache.shardingsphere:shardingsphere-infra-database-p6spy` 模块，
+对 `com.p6spy.engine.spy.P6SpyDriver` 提供部分支持。
+
+## 前提条件
+
+要在 ShardingSphere 的配置文件为 MySQL Server 数据节点使用 P6Spy， 可能的 Maven 依赖关系如下，
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>org.apache.shardingsphere</groupId>
+        <artifactId>shardingsphere-jdbc</artifactId>
+        <version>${shardingsphere.version}</version>
+    </dependency>
+    <dependency>
+        <groupId>p6spy</groupId>
+        <artifactId>p6spy</artifactId>
+        <version>3.9.1</version>
+    </dependency>
+    <dependency>
+        <groupId>com.mysql</groupId>
+        <artifactId>mysql-connector-j</artifactId>
+        <version>9.1.0</version>
+    </dependency>
+</dependencies>
+```
+
+## 配置示例
+
+### 启动 MySQL Server
+
+编写 Docker Compose 文件来启动 MySQL Server。
+
+```yaml
+services:
+   mysql:
+      image: mysql:9.1.0
+      environment:
+         MYSQL_ROOT_PASSWORD: example
+      volumes:
+         - ./mysql/docker-entrypoint-initdb.d:/docker-entrypoint-initdb.d
+      ports:
+         - "3306:3306"
+```
+
+`./docker-entrypoint-initdb.d` 文件夹包含文件为 `init.sh`，内容如下，
+
+```shell
+#!/bin/bash
+set -e
+
+mysql -uroot -p"$MYSQL_ROOT_PASSWORD" <<EOSQL
+CREATE DATABASE demo_ds_0;
+CREATE DATABASE demo_ds_1;
+CREATE DATABASE demo_ds_2;
+EOSQL
+
+for i in "demo_ds_0" "demo_ds_1" "demo_ds_2"
+do
+mysql -uroot -p"$MYSQL_ROOT_PASSWORD" "$i" <<'EOSQL'
+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)
+);
+EOSQL
+done
+```
+
+### 在业务项目创建 ShardingSphere 数据源
+
+在业务项目引入前提条件涉及的依赖后，在业务项目的 classpath 上编写 ShardingSphere 数据源的配置文件`demo.yaml`，
+
+```yaml
+dataSources:
+  ds_0:
+    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+    driverClassName: com.mysql.cj.jdbc.Driver
+    jdbcUrl: jdbc:p6spy:mysql://localhost:3306/demo_ds_0?sslMode=REQUIRED
+    username: root
+    password: example
+  ds_1:
+    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+    driverClassName: com.mysql.cj.jdbc.Driver
+    jdbcUrl: jdbc:p6spy:mysql://localhost:3306/demo_ds_1?sslMode=REQUIRED
+    username: root
+    password: example
+  ds_2:
+    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+    driverClassName: com.mysql.cj.jdbc.Driver
+    jdbcUrl: jdbc:p6spy:mysql://localhost:3306/demo_ds_2?sslMode=REQUIRED
+    username: root
+    password: example
+rules:
+- !SHARDING
+    tables:
+      t_order:
+        actualDataNodes:
+        keyGenerateStrategy:
+          column: order_id
+          keyGeneratorName: snowflake
+    defaultDatabaseStrategy:
+      standard:
+        shardingColumn: user_id
+        shardingAlgorithmName: inline
+    shardingAlgorithms:
+      inline:
+        type: INLINE
+        props:
+          algorithm-expression: ds_${user_id % 2}
+    keyGenerators:
+      snowflake:
+        type: SNOWFLAKE
+```
+
+### 享受集成
+
+创建 ShardingSphere 的数据源以享受集成，
+
+```java
+import com.zaxxer.hikari.HikariConfig;
+import com.zaxxer.hikari.HikariDataSource;
+import java.sql.Connection;
+import java.sql.SQLException;
+import java.sql.Statement;
+public class ExampleUtils {
+    void test() throws SQLException {
+        HikariConfig config = new HikariConfig();
+        config.setJdbcUrl("jdbc:shardingsphere:classpath:demo.yaml");
+        config.setDriverClassName("org.apache.shardingsphere.driver.ShardingSphereDriver");
+        try (HikariDataSource dataSource = new HikariDataSource(config);
+             Connection connection = dataSource.getConnection();
+             Statement statement = connection.createStatement()) {
+            statement.execute("INSERT INTO t_order (user_id, order_type, address_id, status) VALUES (1, 1, 1, 'INSERT_TEST')");
+            statement.executeQuery("SELECT * FROM t_order");
+            statement.execute("alter table t_order delete where order_id=1");
+        }
+    }
+}
+```
+
+## 使用限制
+
+目前仅支持为 MySQL JDBC Driver 配置 P6Spy。
diff --git a/...document/content/user-manual/shardingsphere-jdbc/unsupported/p6spy/_index.en.md b/...document/content/user-manual/shardingsphere-jdbc/unsupported/p6spy/_index.en.md
@@ -0,0 +1,156 @@
++++
+title = "P6Spy"
+weight = 6
++++
+
+## Background Information
+
+ShardingSphere provides partial support for `com.p6spy.engine.spy.P6SpyDriver` through the
+`org.apache.shardingsphere:shardingsphere-infra-database-p6spy` module.
+
+## Prerequisites
+
+To use P6Spy for MySQL Server data nodes in ShardingSphere's configuration file, 
+the possible Maven dependencies are as follows,
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>org.apache.shardingsphere</groupId>
+        <artifactId>shardingsphere-jdbc</artifactId>
+        <version>${shardingsphere.version}</version>
+    </dependency>
+    <dependency>
+        <groupId>p6spy</groupId>
+        <artifactId>p6spy</artifactId>
+        <version>3.9.1</version>
+    </dependency>
+    <dependency>
+        <groupId>com.mysql</groupId>
+        <artifactId>mysql-connector-j</artifactId>
+        <version>9.1.0</version>
+    </dependency>
+</dependencies>
+```
+
+## Configuration Example
+
+### Start MySQL Server
+
+Write a Docker Compose file to start MySQL Server.
+
+```yaml
+services:
+   mysql:
+      image: mysql:9.1.0
+      environment:
+         MYSQL_ROOT_PASSWORD: example
+      volumes:
+         - ./mysql/docker-entrypoint-initdb.d:/docker-entrypoint-initdb.d
+      ports:
+         - "3306:3306"
+```
+
+The `./docker-entrypoint-initdb.d` folder contains the file `init.sh`, the content is as follows,
+
+```shell
+#!/bin/bash
+set -e
+
+mysql -uroot -p"$MYSQL_ROOT_PASSWORD" <<EOSQL
+CREATE DATABASE demo_ds_0;
+CREATE DATABASE demo_ds_1;
+CREATE DATABASE demo_ds_2;
+EOSQL
+
+for i in "demo_ds_0" "demo_ds_1" "demo_ds_2"
+do
+mysql -uroot -p"$MYSQL_ROOT_PASSWORD" "$i" <<'EOSQL'
+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)
+);
+EOSQL
+done
+```
+
+### Create ShardingSphere data source in business project
+
+After the business project introduces the dependencies involved in the prerequisites, 
+write the ShardingSphere data source configuration file `demo.yaml` on the classpath of the business project.
+
+```yaml
+dataSources:
+  ds_0:
+    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+    driverClassName: com.mysql.cj.jdbc.Driver
+    jdbcUrl: jdbc:p6spy:mysql://localhost:3306/demo_ds_0?sslMode=REQUIRED
+    username: root
+    password: example
+  ds_1:
+    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+    driverClassName: com.mysql.cj.jdbc.Driver
+    jdbcUrl: jdbc:p6spy:mysql://localhost:3306/demo_ds_1?sslMode=REQUIRED
+    username: root
+    password: example
+  ds_2:
+    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+    driverClassName: com.mysql.cj.jdbc.Driver
+    jdbcUrl: jdbc:p6spy:mysql://localhost:3306/demo_ds_2?sslMode=REQUIRED
+    username: root
+    password: example
+rules:
+- !SHARDING
+    tables:
+      t_order:
+        actualDataNodes:
+        keyGenerateStrategy:
+          column: order_id
+          keyGeneratorName: snowflake
+    defaultDatabaseStrategy:
+      standard:
+        shardingColumn: user_id
+        shardingAlgorithmName: inline
+    shardingAlgorithms:
+      inline:
+        type: INLINE
+        props:
+          algorithm-expression: ds_${user_id % 2}
+    keyGenerators:
+      snowflake:
+        type: SNOWFLAKE
+```
+
+### Enjoy integration
+
+Create a ShardingSphere data source to enjoy integration,
+
+```java
+import com.zaxxer.hikari.HikariConfig;
+import com.zaxxer.hikari.HikariDataSource;
+import java.sql.Connection;
+import java.sql.SQLException;
+import java.sql.Statement;
+public class ExampleUtils {
+    void test() throws SQLException {
+        HikariConfig config = new HikariConfig();
+        config.setJdbcUrl("jdbc:shardingsphere:classpath:demo.yaml");
+        config.setDriverClassName("org.apache.shardingsphere.driver.ShardingSphereDriver");
+        try (HikariDataSource dataSource = new HikariDataSource(config);
+             Connection connection = dataSource.getConnection();
+             Statement statement = connection.createStatement()) {
+            statement.execute("INSERT INTO t_order (user_id, order_type, address_id, status) VALUES (1, 1, 1, 'INSERT_TEST')");
+            statement.executeQuery("SELECT * FROM t_order");
+            statement.execute("alter table t_order delete where order_id=1");
+        }
+    }
+}
+```
+
+## Usage Limitations
+
+Currently only supports configuring P6Spy for MySQL JDBC Driver.