From da496acca5cba9edfb70ffa007765b02ee06d93e Mon Sep 17 00:00:00 2001 From: Raigor Date: Thu, 10 Oct 2024 16:59:11 +0800 Subject: [PATCH] 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 0d570ccdebf6c..0d801677fe267 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 efd493917c4e6..68a1ddcc01dad 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 6c7aee224e4a6..e05cc4aefebf4 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 85723ee7ef747..9b66100eac69d 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 369ac97556655..44992f1e4cd2c 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 cdef6a5b472f7..d6b556ac095b3 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 88805066ca874..bf2d12112e9d8 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