Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs for storage unit RDL #33203

Merged
merged 2 commits into from
Oct 10, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions RELEASE-NOTES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)?')'
Expand Down Expand Up @@ -47,6 +50,12 @@ key ::=

value ::=
literal

checkPrivileges ::=
'CHECK_PRIVILEGES' '=' privilegeType (',' privilegeType)*

privilegeType ::=
identifier
```
{{% /tab %}}
{{% tab name="铁路图" %}}
Expand All @@ -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` 时,跳过权限校验。

### 示例

Expand Down Expand Up @@ -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`

### 相关链接

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)?')'
Expand Down Expand Up @@ -47,6 +50,12 @@ key ::=

value ::=
literal

checkPrivileges ::=
'CHECK_PRIVILEGES' '=' privilegeType (',' privilegeType)*

privilegeType ::=
identifier
```
{{% /tab %}}
{{% tab name="Railroad diagram" %}}
Expand All @@ -56,56 +65,66 @@ 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

- Alter storage unit using HOST & PORT method

```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"
);
```

- Alter storage unit and set connection pool properties using HOST & PORT method

```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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)?')'
Expand Down Expand Up @@ -50,6 +53,12 @@ key ::=

value ::=
literal

checkPrivileges ::=
'CHECK_PRIVILEGES' '=' privilegeType (',' privilegeType)*

privilegeType ::=
identifier
```
{{% /tab %}}
{{% tab name="铁路图" %}}
Expand All @@ -64,7 +73,8 @@ value ::=
- `storageUnitName` 区分大小写;
- `storageUnitName` 在当前逻辑库中需要唯一;
- `storageUnitName` 命名只允许使用字母、数字以及 `_` ,且必须以字母开头;
- `PROPERTIES` 为可选参数,用于自定义连接池属性,`key` 必须和连接池参数名一致。
- `PROPERTIES` 为可选参数,用于自定义连接池属性,`key` 必须和连接池参数名一致;
- 可通过 `CHECK_PRIVILEGES` 指定注册时校验存储单元用户的权限,`privilegeType` 支持的类型有 `SELECT`、`XA`、`PIPELINE`、`NONE`,缺省值为 `SELECT`,当类型列表中包含 `NONE` 时,跳过权限校验。

### 示例

Expand Down Expand Up @@ -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`

### 相关链接

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)?')'
Expand Down Expand Up @@ -50,6 +53,12 @@ key ::=

value ::=
literal

checkPrivileges ::=
'CHECK_PRIVILEGES' '=' privilegeType (',' privilegeType)*

privilegeType ::=
identifier
```
{{% /tab %}}
{{% tab name="Railroad diagram" %}}
Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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="铁路图" %}}
Expand Down Expand Up @@ -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`

### 相关链接

Expand Down
Loading