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 849cc42fad4 Add separate documentation for ShardingSphereDriver's URL
configuration (#29730)
849cc42fad4 is described below
commit 849cc42fad482d224a259be784819efe992c6962
Author: Ling Hengqian <[email protected]>
AuthorDate: Mon Jan 15 16:55:32 2024 +0800
Add separate documentation for ShardingSphereDriver's URL configuration
(#29730)
---
.../yaml-config/jdbc-driver/_index.cn.md | 20 ++----------
.../yaml-config/jdbc-driver/_index.en.md | 20 ++----------
.../jdbc-driver/known-implementation/_index.cn.md | 37 ++++++++++++++++++++++
.../jdbc-driver/known-implementation/_index.en.md | 37 ++++++++++++++++++++++
.../jdbc-driver/spring-boot/_index.cn.md | 2 +-
.../jdbc-driver/spring-boot/_index.en.md | 2 +-
.../startup/graalvm-native-image.cn.md | 20 ++++++------
.../startup/graalvm-native-image.en.md | 28 +++++++---------
8 files changed, 102 insertions(+), 64 deletions(-)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/_index.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/_index.cn.md
index 3f3b58f7a9a..5600eac9906 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/_index.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/_index.cn.md
@@ -14,13 +14,9 @@ ShardingSphere-JDBC 提供了 JDBC 驱动，可以仅通过配置变更即可使
`org.apache.shardingsphere.driver.ShardingSphereDriver`
-### URL 配置
+### URL 配置及配置示例
-- 以 `jdbc:shardingsphere:` 为前缀
-- 配置文件：`xxx.yaml`，配置文件格式与 [YAML
配置](/cn/user-manual/shardingsphere-jdbc/yaml-config/)一致
-- 配置文件加载规则：
- - `absolutepath:` 前缀表示从绝对路径中加载配置文件
- - `classpath:` 前缀表示从类路径中加载配置文件
+参考 [已知实现](./known-implementation/_index.cn.md) 。
## 操作步骤
@@ -80,15 +76,3 @@ try (
}
}
```
-
-## 配置示例
-
-加载 classpath 中 config.yaml 配置文件的 JDBC URL：
-```
-jdbc:shardingsphere:classpath:config.yaml
-```
-
-加载绝对路径中 config.yaml 配置文件的 JDBC URL：
-```
-jdbc:shardingsphere:absolutepath:/path/to/config.yaml
-```
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/_index.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/_index.en.md
index cc72a35f61d..cf9d5c10bee 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/_index.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/_index.en.md
@@ -14,13 +14,9 @@ ShardingSphere-JDBC provides a JDBC Driver, which can be
used only through confi
`org.apache.shardingsphere.driver.ShardingSphereDriver`
-### URL Configuration
+### URL Configuration and sample
-- Use jdbc:shardingsphere: as prefix
-- Configuration file: xxx.yaml, keep consist format with [YAML
Configuration](/en/user-manual/shardingsphere-jdbc/yaml-config/)
-- Configuration file loading rule:
- - `absolutepath:` prefix means to load the configuration file from the
absolute path
- - `classpath:` prefix indicates that the configuration file is loaded from
the classpath
+Refer to [known Implementation](./known-implementation/_index.en.md).
## Procedure
@@ -80,15 +76,3 @@ try (
}
}
```
-
-## Sample
-
-Load JDBC URL of config.yaml profile in classpath:
-```
-jdbc:shardingsphere:classpath:config.yaml
-```
-
-Load JDBC URL of config.yaml profile in absolute path
-```
-jdbc:shardingsphere:absolutepath:/path/to/config.yaml
-```
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/known-implementation/_index.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/known-implementation/_index.cn.md
new file mode 100644
index 00000000000..8b0caf285fc
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/known-implementation/_index.cn.md
@@ -0,0 +1,37 @@
++++
+title = "已知实现"
+weight = 4
+chapter = true
++++
+
+## 背景信息
+
+对于 `org.apache.shardingsphere.driver.ShardingSphereDriver` 的驱动类，
+通过实现
`org.apache.shardingsphere.driver.jdbc.core.driver.ShardingSphereURLProvider` 的
SPI，
+可允许从多种来源和 File System 获取并解析为 ShardingSphere 的 YAML 配置文件。
+
+在解析并加载 YAML 文件为 ShardingSphere 的元数据后，
+会再次通过[模式配置](../../../java-api/mode.cn.md)的相关配置决定下一步行为。讨论两种情况：
+1. 元数据持久化仓库中不存在 ShardingSphere 的元数据，本地元数据将被存储到元数据持久化仓库。
+2. 元数据持久化仓库中已存在与本地元数据不同的 ShardingSphere 的元数据，本地元数据将被元数据持久化仓库的元数据覆盖。
+
+对元数据持久化仓库的配置需参考[元数据持久化仓库](../../../../common-config/builtin-algorithm/metadata-repository.cn.md)。
+
+## URL 配置
+
+### 从类路径中加载配置文件
+加载 classpath 中 config.yaml 配置文件的 JDBC URL，通过 `jdbc:shardingsphere:classpath:`
前缀识别。
+配置文件为 `xxx.yaml`，配置文件格式与 [YAML 配置](../../../yaml-config)一致。
+
+用例：
+- `jdbc:shardingsphere:classpath:config.yaml`
+
+### 从绝对路径中加载配置文件
+加载绝对路径中 config.yaml 配置文件的 JDBC URL，通过 `jdbc:shardingsphere:absolutepath:` 前缀识别。
+配置文件为 `xxx.yaml`，配置文件格式与 [YAML 配置](../../../yaml-config)一致。
+
+用例：
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml`
+
+### 其他实现
+具体可参考 https://github.com/apache/shardingsphere-plugin 。
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/known-implementation/_index.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/known-implementation/_index.en.md
new file mode 100644
index 00000000000..9a50599bae5
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/known-implementation/_index.en.md
@@ -0,0 +1,37 @@
++++
+title = "Known Implementation"
+weight = 4
+chapter = true
++++
+
+## Background Information
+
+For the driver class of
`org.apache.shardingsphere.driver.ShardingSphereDriver`,
+by implementing the SPI of
`org.apache.shardingsphere.driver.jdbc.core.driver.ShardingSphereURLProvider`,
+allows YAML configuration files to be fetched from multiple sources and File
Systems and parsed into ShardingSphere.
+
+After parsing and loading the YAML file into ShardingSphere's metadata,
+The next behavior will be determined again through the relevant configuration
of [Mode Configuration](../../../java-api/mode.cn.md). Discuss two situations:
+1. ShardingSphere’s metadata does not exist in the metadata persistence
warehouse, and local metadata will be stored in the metadata persistence
warehouse.
+2. Metadata of ShardingSphere that is different from local metadata already
exists in the metadata persistence warehouse, and the local metadata will be
overwritten by the metadata of the metadata persistence warehouse.
+
+For the configuration of the metadata persistence warehouse, please refer to
[Metadata Persistence
Warehouse](../../../../common-config/builtin-algorithm/metadata-repository.cn.md).
+
+## URL configuration
+
+### Load configuration files from classpath
+Load the JDBC URL of the config.yaml configuration file in classpath,
identified by the `jdbc:shardingsphere:classpath:` prefix.
+The configuration file is `xxx.yaml`, and the configuration file format is
consistent with [YAML configuration](../../../yaml-config).
+
+Example:
+- `jdbc:shardingsphere:classpath:config.yaml`
+
+### Load configuration file from absolute path
+JDBC URL to load the config.yaml configuration file in an absolute path,
identified by the `jdbc:shardingsphere:absolutepath:` prefix.
+The configuration file is `xxx.yaml`, and the configuration file format is
consistent with [YAML configuration](../../../yaml-config).
+
+Example:
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml`
+
+### Other implementations
+For details, please refer to https://github.com/apache/shardingsphere-plugin .
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.cn.md
index 88175b1a857..a6e561297e7 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.cn.md
@@ -29,7 +29,7 @@
spring.datasource.driver-class-name=org.apache.shardingsphere.driver.ShardingSph
spring.datasource.url=jdbc:shardingsphere:classpath:xxx.yaml
```
-`spring.datasource.url` 中的 YAML 配置文件当前支持通过两种方式获取，绝对路径 `absolutepath:` 以及
CLASSPATH `classpath:`，具体可参考
`org.apache.shardingsphere.driver.jdbc.core.driver.ShardingSphereURLProvider`
的实现。
+`spring.datasource.url` 中的 YAML 配置文件当前支持通过多种方式获取，具体可参考
[已知实现](../known-implementation/_index.cn.md) 。
### 使用数据源
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.en.md
index f2a502fa3ac..3ccc1c364ea 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.en.md
@@ -29,7 +29,7 @@
spring.datasource.driver-class-name=org.apache.shardingsphere.driver.ShardingSph
spring.datasource.url=jdbc:shardingsphere:classpath:xxx.yaml
```
-The YAML configuration file in 'spring.datasource.url' currently support in
two ways, the absolute path 'absolutepath:' and CLASSPATH 'classpath:', which
can be referred to
`org.apache.shardingsphere.driver.jdbc.core.driver.ShardingSphereURLProvider`'s
implementation for details.
+The YAML configuration file in 'spring.datasource.url' currently support in
multiple ways, refer to [Known
Implementation](../known-implementation/_index.en.md).
### Use Data Source
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/startup/graalvm-native-image.cn.md
b/docs/document/content/user-manual/shardingsphere-proxy/startup/graalvm-native-image.cn.md
index 22e8b595e1b..06252a38c9f 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/startup/graalvm-native-image.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/startup/graalvm-native-image.cn.md
@@ -124,16 +124,16 @@ services:
## 可观察性
-- 针对 GraalVM Native Image 形态的 ShardingSphere Proxy，其提供的可观察性的能力与
-
https://shardingsphere.apache.org/document/current/cn/user-manual/shardingsphere-proxy/observability/
并不一致。
+针对 GraalVM Native Image 形态的 ShardingSphere Proxy，其提供的可观察性的能力与
+https://shardingsphere.apache.org/document/current/cn/user-manual/shardingsphere-proxy/observability/
并不一致。
-- 你可以使用 https://www.graalvm.org/jdk17/tools/ 提供的一系列命令行工具或可视化工具观察 GraalVM
Native Image 的内部行为，
- 并根据其要求使用 VSCode 完成调试工作。如果你正在使用 IntelliJ IDEA 并且希望调试生成的 GraalVM Native
Image，你可以关注
-
https://blog.jetbrains.com/idea/2022/06/intellij-idea-2022-2-eap-5/#Experimental_GraalVM_Native_Debugger_for_Java
- 及其后继。如果你使用的不是 Linux，则无法对 GraalVM Native Image 进行 Debug，请关注尚未关闭的
- https://github.com/oracle/graal/issues/5648 。
+你可以使用 https://www.graalvm.org/jdk17/tools/ 提供的一系列命令行工具或可视化工具观察 GraalVM Native
Image 的内部行为，
+并根据其要求使用 VSCode 完成调试工作。如果你正在使用 IntelliJ IDEA 并且希望调试生成的 GraalVM Native
Image，你可以关注
+https://blog.jetbrains.com/idea/2022/06/intellij-idea-2022-2-eap-5/#Experimental_GraalVM_Native_Debugger_for_Java
+及其后继。如果你使用的不是 Linux，则无法对 GraalVM Native Image 进行 Debug，请关注尚未关闭的
+https://github.com/oracle/graal/issues/5648 。
-- 对于使用 `ShardingSphere Agent` 等 Java Agent 的情形， GraalVM 的 `native-image`
组件尚未完全支持在构建 Native
- Image 时使用 javaagent，你需要关注尚未关闭的 https://github.com/oracle/graal/issues/1065 。
+对于使用 `ShardingSphere Agent` 等 Java Agent 的情形， GraalVM 的 `native-image`
组件尚未完全支持在构建 Native
+Image 时使用 javaagent，你需要关注尚未关闭的 https://github.com/oracle/graal/issues/1065 。
-- 若用户期望在 ShardingSphere Proxy Native 下使用 OpenTelemetry Java Agent，则需要关注
https://github.com/oracle/graal/pull/8077 涉及的变动。
+若用户期望在 ShardingSphere Proxy Native 下使用这类 Java Agent，则需要关注
https://github.com/oracle/graal/pull/8077 涉及的变动。
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/startup/graalvm-native-image.en.md
b/docs/document/content/user-manual/shardingsphere-proxy/startup/graalvm-native-image.en.md
index 96f95307401..6a9ad55b580 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/startup/graalvm-native-image.en.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/startup/graalvm-native-image.en.md
@@ -133,22 +133,18 @@ services:
## Observability
-- ShardingSphere for GraalVM Native Image form Proxy, which provides
observability capabilities
- with
https://shardingsphere.apache.org/document/current/cn/user-manual/shardingsphere-proxy/observability/
- not consistent.
+ShardingSphere for GraalVM Native Image form Proxy, which provides
observability capabilities
+with
https://shardingsphere.apache.org/document/current/cn/user-manual/shardingsphere-proxy/observability/
+not consistent.
-- You can observe GraalVM Native Image using a series of command line tools or
visualization tools available
- at https://www.graalvm.org/jdk17/tools/, and use VSCode to debug it
according to its requirements.
- If you are using IntelliJ IDEA and want to debug the generated GraalVM
Native Image, You can follow
-
https://blog.jetbrains.com/idea/2022/06/intellij-idea-2022-2-eap-5/#Experimental_GraalVM_Native_Debugger_for_Java
- and its successors. If you are not using Linux, you cannot debug GraalVM
Native Image, please pay attention
- to https://github.com/oracle/graal/issues/5648 which has not been closed yet.
+You can observe GraalVM Native Image using a series of command line tools or
visualization tools available
+at https://www.graalvm.org/jdk17/tools/, and use VSCode to debug it according
to its requirements.
+If you are using IntelliJ IDEA and want to debug the generated GraalVM Native
Image, You can follow
+https://blog.jetbrains.com/idea/2022/06/intellij-idea-2022-2-eap-5/#Experimental_GraalVM_Native_Debugger_for_Java
+and its successors. If you are not using Linux, you cannot debug GraalVM
Native Image, please pay attention
+to https://github.com/oracle/graal/issues/5648 which has not been closed yet.
-- In the case of using APM Java Agent such as `ShardingSphere Agent`,
- GraalVM's `native-image` component is not yet fully supported when building
Native Images
- javaagent, you need to follow https://github.com/oracle/graal/issues/1065
which has not been closed.
+For the use of Java Agents such as `ShardingSphere Agent`, GraalVM's
`native-image` component does not yet fully support building Native
+when using javaagent with Image, you need to pay attention to
https://github.com/oracle/graal/issues/1065 which has not yet been closed.
-- The following sections use the `Apache SkyWalking Java Agent` as an example,
which can be used to track corresponding
- issues from the GraalVM community.
-
-- If users expect to use OpenTelemetry Java Agent under ShardingSphere Proxy
Native, they need to pay attention to the changes involved in
https://github.com/oracle/graal/pull/8077 .
+If users expect to use this type of Java Agent under ShardingSphere Proxy
Native, they need to pay attention to the changes involved in
https://github.com/oracle/graal/pull/8077 .
