This is an automated email from the ASF dual-hosted git repository.
sunnianjun 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 da496acca5c Update docs for storage unit RDL (#33203)
da496acca5c is described below
commit da496acca5cba9edfb70ffa007765b02ee06d93e
Author: Raigor <[email protected]>
AuthorDate: Thu Oct 10 16:59:11 2024 +0800
Update docs for storage unit RDL (#33203)
* Update docs for storage unit RDL
* Update RELEASE-NOTES
---
RELEASE-NOTES.md | 1 +
.../alter-storage-unit.cn.md | 28 ++++++++++--
.../alter-storage-unit.en.md | 53 +++++++++++++++-------
.../register-storage-unit.cn.md | 28 ++++++++++--
.../register-storage-unit.en.md | 31 +++++++++++--
.../unregister-storage-unit.cn.md | 16 ++-----
.../unregister-storage-unit.en.md | 28 ++++++------
7 files changed, 131 insertions(+), 54 deletions(-)
diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md
index 0d570ccdebf..0d801677fe2 100644
--- a/RELEASE-NOTES.md
+++ b/RELEASE-NOTES.md
@@ -13,6 +13,7 @@
1. DistSQL: Support running DistSQL under Proxy Native in the form of GraalVM
Native Image - [#33095](https://github.com/apache/shardingsphere/pull/33095)
1. DistSQL: Support connecting to Postgres via DistSQL in Proxy Native -
[#33124](https://github.com/apache/shardingsphere/pull/33124)
1. DistSQL: Check duplicate actual data nodes when creating or altering
sharding table rule -
[#33138](https://github.com/apache/shardingsphere/pull/33138)
+1. DistSQL: Check user privilege when registering or altering storage unit -
[#32172](https://github.com/apache/shardingsphere/pull/32172)
### Bug Fix
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/alter-storage-unit.cn.md
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/alter-storage-unit.cn.md
index efd493917c4..68a1ddcc01d 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/alter-storage-unit.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/alter-storage-unit.cn.md
@@ -13,7 +13,10 @@ weight = 2
{{% tab name="语法" %}}
```sql
AlterStorageUnit ::=
- 'ALTER' 'STORAGE' 'UNIT' storageUnitDefinition (',' storageUnitDefinition)*
+ 'ALTER' 'STORAGE' 'UNIT' storageUnitsDefinition (',' checkPrivileges)?
+
+storageUnitsDefinition ::=
+ storageUnitDefinition (',' storageUnitDefinition)*
storageUnitDefinition ::=
storageUnitName '(' ('HOST' '=' hostName ',' 'PORT' '=' port ',' 'DB' '='
dbName | 'URL' '=' url) ',' 'USER' '=' user (',' 'PASSWORD' '=' password)? (','
propertiesDefinition)?')'
@@ -47,6 +50,12 @@ key ::=
value ::=
literal
+
+checkPrivileges ::=
+ 'CHECK_PRIVILEGES' '=' privilegeType (',' privilegeType)*
+
+privilegeType ::=
+ identifier
```
{{% /tab %}}
{{% tab name="铁路图" %}}
@@ -60,7 +69,8 @@ value ::=
- `ALTER STORAGE UNIT`不允许改变该存储单元关联的真实数据源（通过 host、port 和 db 判断）；
- `ALTER STORAGE UNIT`会发生连接池的切换，这个操作可能对进行中的业务造成影响，请谨慎使用；
- 请确认修改的存储单元是可以正常连接的， 否则将不能修改成功；
-- `PROPERTIES` 为可选参数，用于自定义连接池属性，`key` 必须和连接池参数名一致。
+- `PROPERTIES` 为可选参数，用于自定义连接池属性，`key` 必须和连接池参数名一致;
+- 可通过 `CHECK_PRIVILEGES` 指定注册时校验存储单元用户的权限，`privilegeType` 支持的类型有
`SELECT`、`XA`、`PIPELINE`、`NONE`，缺省值为 `SELECT`，当类型列表中包含 `NONE` 时，跳过权限校验。
### 示例
@@ -100,9 +110,21 @@ ALTER STORAGE UNIT ds_2 (
);
```
+- 修改存储单元时检查 `SELECT`、`XA` 和 `PIPELINE` 权限
+
+```sql
+ALTER STORAGE UNIT ds_2 (
+
URL="jdbc:mysql://127.0.0.1:3306/db_2?serverTimezone=UTC&useSSL=false&allowPublicKeyRetrieval=true",
+ USER=root,
+ PASSWORD=root,
+ PROPERTIES("maximumPoolSize"=10,"idleTimeout"="30000"),
+ CHECK_PRIVILEGES=SELECT,XA,PIPELINE
+);
+```
+
### 保留字
-`ALTER`、`STORAGE`、`UNIT`、`HOST`、`PORT`、`DB`、`USER`、`PASSWORD`、`PROPERTIES`、`URL`
+`ALTER`、`STORAGE`、`UNIT`、`HOST`、`PORT`、`DB`、`USER`、`PASSWORD`、`PROPERTIES`、`URL`、`CHECK_PRIVILEGES`
### 相关链接
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/alter-storage-unit.en.md
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/alter-storage-unit.en.md
index 6c7aee224e4..e05cc4aefeb 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/alter-storage-unit.en.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/alter-storage-unit.en.md
@@ -13,7 +13,10 @@ The `ALTER STORAGE UNIT` syntax is used to alter storage
units for the currently
{{% tab name="Grammar" %}}
```sql
AlterStorageUnit ::=
- 'ALTER' 'STORAGE' 'UNIT' storageUnitDefinition (',' storageUnitDefinition)*
+ 'ALTER' 'STORAGE' 'UNIT' storageUnitsDefinition (',' checkPrivileges)?
+
+storageUnitsDefinition ::=
+ storageUnitDefinition (',' storageUnitDefinition)*
storageUnitDefinition ::=
storageUnitName '(' ('HOST' '=' hostName ',' 'PORT' '=' port ',' 'DB' '='
dbName | 'URL' '=' url) ',' 'USER' '=' user (',' 'PASSWORD' '=' password)? (','
propertiesDefinition)?')'
@@ -47,6 +50,12 @@ key ::=
value ::=
literal
+
+checkPrivileges ::=
+ 'CHECK_PRIVILEGES' '=' privilegeType (',' privilegeType)*
+
+privilegeType ::=
+ identifier
```
{{% /tab %}}
{{% tab name="Railroad diagram" %}}
@@ -56,14 +65,12 @@ value ::=
### Supplement
-- Before altering the storage units, please confirm that a database exists in
Proxy, and execute the `use` command to
- select a database;
+- Before altering the storage units, please confirm that a database exists in
Proxy, and execute the `use` command to select a database;
- `ALTER STORAGE UNIT` is not allowed to change the real data source
associated with this storageUnit (determined by host, port and db);
-- `ALTER STORAGE UNIT` will switch the connection pool. This operation may
affect the ongoing business, please use it with
- caution;
+- `ALTER STORAGE UNIT` will switch the connection pool. This operation may
affect the ongoing business, please use it with caution;
- Please confirm that the storage unit to be altered can be connected
successfully, otherwise the altering will fail;
-- `PROPERTIES` is optional, used to customize connection pool properties,
`key` must be the same as the connection pool
- property name.
+- `PROPERTIES` is optional, used to customize connection pool properties,
`key` must be the same as the connection pool property name;
+- `CHECK_PRIVILEGES` can be specified to check privileges of the storage unit
user. The supported types of `privilegeType` are `SELECT`, `XA`, `PIPELINE`,
and `NONE`. The default value is `SELECT`. When `NONE` is included in the type
list, the privilege check is skipped.
### Example
@@ -71,11 +78,11 @@ value ::=
```sql
ALTER STORAGE UNIT ds_0 (
- HOST=127.0.0.1,
+ HOST="127.0.0.1",
PORT=3306,
- DB=db_0,
- USER=root,
- PASSWORD=root
+ DB="db_0",
+ USER="root",
+ PASSWORD="root"
);
```
@@ -83,29 +90,41 @@ ALTER STORAGE UNIT ds_0 (
```sql
ALTER STORAGE UNIT ds_1 (
- HOST=127.0.0.1,
+ HOST="127.0.0.1",
PORT=3306,
- DB=db_1,
- USER=root,
- PASSWORD=root
+ DB="db_1",
+ USER="root",
+ PASSWORD="root",
PROPERTIES("maximumPoolSize"=10)
);
```
- Alter storage unit and set connection pool properties using URL method
+```sql
+ALTER STORAGE UNIT ds_2 (
+
URL="jdbc:mysql://127.0.0.1:3306/db_2?serverTimezone=UTC&useSSL=false&allowPublicKeyRetrieval=true",
+ USER="root",
+ PASSWORD="root",
+ PROPERTIES("maximumPoolSize"=10,"idleTimeout"="30000")
+);
+```
+
+- Check `SELECT`, `XA` and `PIPELINE` privileges when altering
+
```sql
ALTER STORAGE UNIT ds_2 (
URL="jdbc:mysql://127.0.0.1:3306/db_2?serverTimezone=UTC&useSSL=false&allowPublicKeyRetrieval=true",
USER=root,
PASSWORD=root,
- PROPERTIES("maximumPoolSize"=10,"idleTimeout"="30000")
+ PROPERTIES("maximumPoolSize"=10,"idleTimeout"="30000"),
+ CHECK_PRIVILEGES=SELECT,XA,PIPELINE
);
```
### Reserved word
-`ALTER`, `STORAGE`, `UNIT`, `HOST`, `PORT`, `DB`, `USER`, `PASSWORD`,
`PROPERTIES`, `URL`
+`ALTER`, `STORAGE`, `UNIT`, `HOST`, `PORT`, `DB`, `USER`, `PASSWORD`,
`PROPERTIES`, `URL`, `CHECK_PRIVILEGES`
### Related links
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/register-storage-unit.cn.md
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/register-storage-unit.cn.md
index 85723ee7ef7..9b66100eac6 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/register-storage-unit.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/register-storage-unit.cn.md
@@ -13,7 +13,10 @@ weight = 1
{{% tab name="语法" %}}
```sql
RegisterStorageUnit ::=
- 'REGISTER' 'STORAGE' 'UNIT' ifNotExists? storageUnitDefinition (','
storageUnitDefinition)*
+ 'REGISTER' 'STORAGE' 'UNIT' ifNotExists? storageUnitsDefinition (','
checkPrivileges)?
+
+storageUnitsDefinition ::=
+ storageUnitDefinition (',' storageUnitDefinition)*
storageUnitDefinition ::=
storageUnitName '(' ('HOST' '=' hostName ',' 'PORT' '=' port ',' 'DB' '='
dbName | 'URL' '=' url) ',' 'USER' '=' user (',' 'PASSWORD' '=' password)? (','
propertiesDefinition)?')'
@@ -50,6 +53,12 @@ key ::=
value ::=
literal
+
+checkPrivileges ::=
+ 'CHECK_PRIVILEGES' '=' privilegeType (',' privilegeType)*
+
+privilegeType ::=
+ identifier
```
{{% /tab %}}
{{% tab name="铁路图" %}}
@@ -64,7 +73,8 @@ value ::=
- `storageUnitName` 区分大小写；
- `storageUnitName` 在当前逻辑库中需要唯一；
- `storageUnitName` 命名只允许使用字母、数字以及 `_` ，且必须以字母开头；
-- `PROPERTIES` 为可选参数，用于自定义连接池属性，`key` 必须和连接池参数名一致。
+- `PROPERTIES` 为可选参数，用于自定义连接池属性，`key` 必须和连接池参数名一致；
+- 可通过 `CHECK_PRIVILEGES` 指定注册时校验存储单元用户的权限，`privilegeType` 支持的类型有
`SELECT`、`XA`、`PIPELINE`、`NONE`，缺省值为 `SELECT`，当类型列表中包含 `NONE` 时，跳过权限校验。
### 示例
@@ -116,9 +126,21 @@ REGISTER STORAGE UNIT IF NOT EXISTS ds_0 (
);
```
+- 注册时校验 `SELECT`、`XA` 和 `PIPELINE` 权限
+
+```sql
+REGISTER STORAGE UNIT ds_3 (
+
URL="jdbc:mysql://127.0.0.1:3306/db_3?serverTimezone=UTC&useSSL=false&allowPublicKeyRetrieval=true",
+ USER="root",
+ PASSWORD="root",
+ PROPERTIES("maximumPoolSize"=10,"idleTimeout"="30000"),
+ CHECK_PRIVILEGES=SELECT,XA,PIPELINE
+);
+```
+
### 保留字
-`REGISTER`、`STORAGE`、`UNIT`、`HOST`、`PORT`、`DB`、`USER`、`PASSWORD`、`PROPERTIES`、`URL`
+`REGISTER`、`STORAGE`、`UNIT`、`HOST`、`PORT`、`DB`、`USER`、`PASSWORD`、`PROPERTIES`、`URL`、`CHECK_PRIVILEGES`
### 相关链接
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/register-storage-unit.en.md
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/register-storage-unit.en.md
index 369ac975566..44992f1e4cd 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/register-storage-unit.en.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/register-storage-unit.en.md
@@ -13,7 +13,10 @@ The `REGISTER STORAGE UNIT` syntax is used to register
storage unit for the curr
{{% tab name="Grammar" %}}
```sql
RegisterStorageUnit ::=
- 'REGISTER' 'STORAGE' 'UNIT' ifNotExists? storageUnitDefinition (','
storageUnitDefinition)*
+ 'REGISTER' 'STORAGE' 'UNIT' ifNotExists? storageUnitsDefinition (','
checkPrivileges)?
+
+storageUnitsDefinition ::=
+ storageUnitDefinition (',' storageUnitDefinition)*
storageUnitDefinition ::=
storageUnitName '(' ('HOST' '=' hostName ',' 'PORT' '=' port ',' 'DB' '='
dbName | 'URL' '=' url) ',' 'USER' '=' user (',' 'PASSWORD' '=' password)? (','
propertiesDefinition)?')'
@@ -50,6 +53,12 @@ key ::=
value ::=
literal
+
+checkPrivileges ::=
+ 'CHECK_PRIVILEGES' '=' privilegeType (',' privilegeType)*
+
+privilegeType ::=
+ identifier
```
{{% /tab %}}
{{% tab name="Railroad diagram" %}}
@@ -59,14 +68,14 @@ value ::=
### Supplement
-- Before register storage units, please confirm that a database has been
created in Proxy, and execute the `use` command to
- successfully select a database;
+- Before register storage units, please confirm that a database has been
created in Proxy, and execute the `use` command to successfully select a
database;
- Confirm that the registered storage unit can be connected normally,
otherwise it will not be added successfully;
- `storageUnitName` is case-sensitive;
- `storageUnitName` needs to be unique within the current database;
- `storageUnitName` name only allows letters, numbers and `_`, and must start
with a letter;
- `PROPERTIES` is optional, used to customize connection pool properties,
`key` must be the same as the connection pool
- property name.
+ property name;
+- `CHECK_PRIVILEGES` can be specified to check privileges of the storage unit
user. The supported types of `privilegeType` are `SELECT`, `XA`, `PIPELINE`,
and `NONE`. The default value is `SELECT`. When `NONE` is included in the type
list, the privilege check is skipped.
### Example
@@ -118,9 +127,21 @@ REGISTER STORAGE UNIT IF NOT EXISTS ds_0 (
);
```
+- Check `SELECT`, `XA` and `PIPELINE` privileges when registering
+
+```sql
+REGISTER STORAGE UNIT ds_3 (
+
URL="jdbc:mysql://127.0.0.1:3306/db_3?serverTimezone=UTC&useSSL=false&allowPublicKeyRetrieval=true",
+ USER="root",
+ PASSWORD="root",
+ PROPERTIES("maximumPoolSize"=10,"idleTimeout"="30000"),
+ CHECK_PRIVILEGES=SELECT,XA,PIPELINE
+);
+```
+
### Reserved word
-`REGISTER`, `STORAGE`, `UNIT`, `HOST`, `PORT`, `DB`, `USER`, `PASSWORD`,
`PROPERTIES`, `URL`
+`REGISTER`, `STORAGE`, `UNIT`, `HOST`, `PORT`, `DB`, `USER`, `PASSWORD`,
`PROPERTIES`, `URL`, `CHECK_PRIVILEGES`
### Related links
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/unregister-storage-unit.cn.md
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/unregister-storage-unit.cn.md
index cdef6a5b472..d6b556ac095 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/unregister-storage-unit.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/unregister-storage-unit.cn.md
@@ -13,22 +13,16 @@ weight = 3
{{% tab name="语法" %}}
```sql
UnregisterStorageUnit ::=
- 'UNREGISTER' 'STORAGE' 'UNIT' ifExists? storageUnitName (','
storageUnitName)* (ignoreSingleTables | ignoreBroadcastTables |
ignoreSingleAndBroadcastTables)?
-
-ignoreSingleTables ::=
- 'IGNORE' 'SINGLE' 'TABLES'
-
-ignoreBroadcastTables ::=
- 'IGNORE' 'BROADCAST' 'TABLES'
-
-ignoreSingleAndBroadcastTables ::=
- 'IGNORE' ('SINGLE' ',' 'BROADCAST' | 'BROADCAST' ',' 'SINGLE') 'TABLES'
+ 'UNREGISTER' 'STORAGE' 'UNIT' ifExists? storageUnitName (','
storageUnitName)* ignoreTables?
ifExists ::=
'IF' 'EXISTS'
storageUnitName ::=
identifier
+
+ignoreTables ::=
+ 'IGNORE' ('SINGLE')? (',')? ('BROADCAST')? 'TABLES'
```
{{% /tab %}}
{{% tab name="铁路图" %}}
@@ -83,7 +77,7 @@ UNREGISTER STORAGE UNIT IF EXISTS ds_0;
### 保留字
-`DROP`、`STORAGE`、`UNIT`、`IF`、`EXISTS`、`IGNORE`、`SINGLE`、`BROADCAST`、`TABLES`
+`UNREGISTER`、`STORAGE`、`UNIT`、`IF`、`EXISTS`、`IGNORE`、`SINGLE`、`BROADCAST`、`TABLES`
### 相关链接
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/unregister-storage-unit.en.md
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/unregister-storage-unit.en.md
index 88805066ca8..bf2d12112e9 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/unregister-storage-unit.en.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/rdl/storage-unit-definition/unregister-storage-unit.en.md
@@ -13,22 +13,16 @@ The `UNREGISTER STORAGE UNIT` syntax is used to unregister
storage unit from the
{{% tab name="Grammar" %}}
```sql
UnregisterStorageUnit ::=
- 'UNREGISTER' 'STORAGE' 'UNIT' ifExists? storageUnitName (','
storageUnitName)* (ignoreSingleTables | ignoreBroadcastTables |
ignoreSingleAndBroadcastTables)?
-
-ignoreSingleTables ::=
- 'IGNORE' 'SINGLE' 'TABLES'
-
-ignoreBroadcastTables ::=
- 'IGNORE' 'BROADCAST' 'TABLES'
-
-ignoreSingleAndBroadcastTables ::=
- 'IGNORE' ('SINGLE' ',' 'BROADCAST' | 'BROADCAST' ',' 'SINGLE') 'TABLES'
+ 'UNREGISTER' 'STORAGE' 'UNIT' ifExists? storageUnitName (','
storageUnitName)* ignoreTables?
ifExists ::=
'IF' 'EXISTS'
storageUnitName ::=
identifier
+
+ignoreTables ::=
+ 'IGNORE' ('SINGLE')? (',')? ('BROADCAST')? 'TABLES'
```
{{% /tab %}}
{{% tab name="Railroad diagram" %}}
@@ -48,33 +42,37 @@ storageUnitName ::=
### Example
-- Drop a storage unit
+- Unregister a storage unit
```sql
UNREGISTER STORAGE UNIT ds_0;
```
-- Drop multiple storage units
+- Unregister multiple storage units
```sql
UNREGISTER STORAGE UNIT ds_0, ds_1;
```
-- Ignore single rule remove storage unit
+- Unregister storage unit and ignore single tables
```sql
UNREGISTER STORAGE UNIT ds_0 IGNORE SINGLE TABLES;
```
+- Unregister storage unit and ignore broadcast tables
+
```sql
UNREGISTER STORAGE UNIT ds_0 IGNORE BROADCAST TABLES;
```
+- Unregister storage unit, ignore single and broadcast tables
+
```sql
UNREGISTER STORAGE UNIT ds_0 IGNORE SINGLE, BROADCAST TABLES;
```
-- Drop the storage unit with `ifExists` clause
+- Unregister storage unit with `ifExists` clause
```sql
UNREGISTER STORAGE UNIT IF EXISTS ds_0;
@@ -82,7 +80,7 @@ UNREGISTER STORAGE UNIT IF EXISTS ds_0;
### Reserved word
-`DROP`, `STORAGE`, `UNIT`, `IF`, `EXISTS`, `IGNORE`, `SINGLE`, `BROADCAST`,
`TABLES`
+`UNREGISTER`, `STORAGE`, `UNIT`, `IF`, `EXISTS`, `IGNORE`, `SINGLE`,
`BROADCAST`, `TABLES`
### Related links
