Adapt Serverless Tier in Developer Guide (#11862) (#11947)

pingcap · Nov 8, 2022 · 60fc57d · 60fc57d
1 parent cc65985
commit 60fc57d
Show file tree

Hide file tree

Showing 5 changed files with 84 additions and 98 deletions.
diff --git a/TOC.md b/TOC.md
@@ -20,11 +20,10 @@
   - 快速开始
     - [使用 TiDB Cloud (Serverless Tier) 构建 TiDB 集群](/develop/dev-guide-build-cluster-in-cloud.md)
     - [使用 TiDB 的增删改查 SQL](/develop/dev-guide-tidb-crud-sql.md)
-    - 构建简单的 CRUD 应用程序
-      - [Java](/develop/dev-guide-sample-application-java.md)
-      - [Golang](/develop/dev-guide-sample-application-golang.md)
   - 示例程序
-    - [使用 Spring Boot 构建 TiDB 应用程序](/develop/dev-guide-sample-application-spring-boot.md)
+    - [Java](/develop/dev-guide-sample-application-java.md)
+    - [Java (Spring Boot)](/develop/dev-guide-sample-application-spring-boot.md)
+    - [Golang](/develop/dev-guide-sample-application-golang.md)
   - 连接到 TiDB
     - [选择驱动或 ORM 框架](/develop/dev-guide-choose-driver-or-orm.md)
     - [连接到 TiDB](/develop/dev-guide-connect-to-tidb.md)

diff --git a/develop/dev-guide-build-cluster-in-cloud.md b/develop/dev-guide-build-cluster-in-cloud.md
@@ -15,18 +15,18 @@ summary: 使用 TiDB Cloud (Serverless Tier) 构建 TiDB 集群，并连接 TiDB
 
 1. 如果你还未拥有 TiDB Cloud 帐号，请先在此[注册](https://tidbcloud.com/free-trial)。
 2. 使用你的 TiDB Cloud 帐号[登录](https://tidbcloud.com/)。
-3. 在[方案](https://tidbcloud.com/console/plans)内选择免费的 **Serverless Tier** 方案，或在 [Clusters](https://tidbcloud.com/console/clusters) 页面中点击 **Create Cluster** 按钮。
-4. 在 **Create Cluster** 页面设置集群名称、云服务商（Serverless Tier 默认为 AWS）、可用区（建议就近选择）后，点击 **Create** 按钮创建 Serverless Tier 免费集群。
-5. 在 **Security Settings** 对话框中，设置密码，并添加允许连接你的集群的 IP 地址，完成后点击 **Apply**。
+3. 在 [Clusters](https://tidbcloud.com/console/clusters) 页面中点击 **Create Cluster** 按钮。
+4. **Create Cluster** 页面默认选择 **Serverless Tier**。你可以根据需要修改集群名称并选择可用区。
+5. 点击 **Create** 创建免费的 Serverless Tier 集群。
 
     你的 TiDB Cloud 集群将于 30 秒后创建完毕。
 
-6. 创建完毕后，点击右上角的 **Connect** 按钮。或点击集群名称，打开集群的详情页，再点击右上角的 **Connect** 按钮。这将显示一个连接对话框。
-7. 复制连接对话框 **Step 2: Connect with a SQL client** 中的连接字符串，供后续步骤使用。
+6. 集群创建完毕后，点击 **Security Settings** 按钮，在对话框中设置连接集群的 root 密码，完成后点击 **Submit**。如果没有设置 root 密码，你将无法连接集群。
+7. 点击 **Connect** 按钮。在连接对话框 **Connect with a SQL Client** 下选择你需要的连接方式并保存对应的连接字符串。下面连接到集群以 MySQL 客户端为例。
 
-    > **Note:**
+    > **注意：**
     >
-    > 需要特别说明的是，在你使用 [Serverless Tier clusters](https://docs.pingcap.com/tidbcloud/select-cluster-tier#serverless-tier) 集群时，你需要给你设置的用户名加上前缀（如上图中的 `9ATyn6DhCXoo6U1`），若使用命令行连接，还需使用单引号包裹用户名。你可以在 [TiDB Cloud - 用户名前缀](https://docs.pingcap.com/tidbcloud/select-cluster-tier#user-name-prefix) 中获得更多信息。
+    > 需要特别说明的是，在你使用 [Serverless Tier](https://docs.pingcap.com/tidbcloud/select-cluster-tier#serverless-tier) 集群时，你需要给你设置的用户名加上前缀（如 `2aEp24QWEDLqRFs.root` 中的 `2aEp24QWEDLqRFs`），若使用命令行连接，还需使用单引号包裹用户名。你可以在 [TiDB Cloud 用户名前缀](https://docs.pingcap.com/tidbcloud/select-cluster-tier#user-name-prefix) 中获得更多信息。
 
 ## 第 2 步：连接到集群
 
@@ -116,55 +116,32 @@ summary: 使用 TiDB Cloud (Serverless Tier) 构建 TiDB 集群，并连接 TiDB
     {{< copyable "shell-regular" >}}
 
     ```shell
-    mysql --connect-timeout 15 -u '<prefix>.root' -h <host> -P 4000 -p
+    mysql --connect-timeout 15 -u '<prefix>.root' -h <host> -P 4000 -D test --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/cert.pem -p
     ```
 
-3. 填写密码，完成登录。
-
-## 第 3 步：运行示例应用程序
-
-1. 克隆 tidb-example-java 项目。
-
-    {{< copyable "shell-regular" >}}
-
-    ```shell
-    git clone https://github.com/pingcap-inc/tidb-example-java.git
-    ```
-
-2. 更改连接参数。
-
-    对于非本地默认集群、TiDB Cloud 或其他远程集群，需要更改 `plain-java-jdbc/src/main/java/com/pingcap/JDBCExample.java` 内关于 Host、Port、User、Password 的参数：
+> **注意：**
+>
+> - 在连接 Serverless Tier 集群时，[必须使用 TLS 连接](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-tier-clusters)。
+> - 如果你在连接时遇到问题，可阅读 [TiDB Cloud Serverless Tier 集群安全连接](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-tier-clusters) 来获得更多信息。
 
-    {{< copyable "" >}}
-
-    ```java
-    mysqlDataSource.setServerName("localhost");
-    mysqlDataSource.setPortNumber(4000);
-    mysqlDataSource.setDatabaseName("test");
-    mysqlDataSource.setUser("<prefix>.root");
-    mysqlDataSource.setPassword("");
-    ```
-
-    若你设定的密码为 `123456`，而且从 TiDB Cloud 得到的连接字符串为：
-
-    {{< copyable "shell-regular" >}}
+3. 填写密码，完成登录。
 
-    ```shell
-    mysql --connect-timeout 15 -u '9ATyn6DhCXoo6U1.root' -h xxx.tidbcloud.com -P 4000 -D test -p
-    ```
+## 第 3 步：运行 SQL
 
-    那么此处应将参数更改为：
+尝试运行一下你在 TiDB Cloud 上的的第一个 SQL 吧：
 
-    {{< copyable "" >}}
+```sql
+SELECT 'Hello TiDB Cloud!';
+```
 
-    ```java
-    mysqlDataSource.setServerName("xxx.tidbcloud.com");
-    mysqlDataSource.setPortNumber(4000);
-    mysqlDataSource.setDatabaseName("test");
-    mysqlDataSource.setUser("9ATyn6DhCXoo6U1.root");
-    mysqlDataSource.setPassword("123456");
-    ```
+你将看到这样的输出：
 
-3. 运行 `make plain-java-jdbc`。
+```sql
++-------------------+
+| Hello TiDB Cloud! |
++-------------------+
+| Hello TiDB Cloud! |
++-------------------+
+```
 
-    输出应如[预期](https://github.com/pingcap-inc/tidb-example-java/blob/main/Expected-Output.md#plain-java-jdbc)所示
+如果你的实际输出与预期输出一致，表示你已经在 TiDB Cloud 上成功地运行了 SQL 语句。
diff --git a/develop/dev-guide-sample-application-golang.md b/develop/dev-guide-sample-application-golang.md
@@ -31,7 +31,7 @@ summary: 给出一个 TiDB 和 Golang 的简单 CRUD 应用程序示例。
 
 ### 使用云原生开发环境
 
-基于 Git 的预配置的开发环境: [现在就试试](/develop/dev-guide-playground-gitpod.md)
+基于 Git 的预配置的开发环境：[现在就试试](/develop/dev-guide-playground-gitpod.md)
 
 该环境会自动克隆代码，并通过 TiUP 部署测试集群。
 
@@ -766,52 +766,60 @@ mysql --host 127.0.0.1 --port 4000 -u root<sql/dbinit.sql
 
 <div label="使用 GORM（推荐）" value="gorm">
 
-若你使用非本地默认集群、TiDB Cloud 或其他远程集群，更改 `gorm.go` 内 `dsn` 参数值：
+若你使用 TiDB Cloud Serverless Tier 集群，更改 `gorm.go` 内 `dsn` 参数值：
 
 {{< copyable "" >}}
 
 ```go
 dsn := "root:@tcp(127.0.0.1:4000)/test?charset=utf8mb4"
 ```
 
-若你设定的密码为 `123456`，而且从 TiDB Cloud 得到的连接字符串为：
+若你设定的密码为 `123456`，而且从 TiDB Cloud Serverless Tier 集群面板中得到的连接信息为：
 
-```
-mysql --connect-timeout 15 -u root -h xxx.tidbcloud.com -P 4000 -p
-```
+- Endpoint: `xxx.tidbcloud.com`
+- Port: `4000`
+- User: `2aEp24QWEDLqRFs.root`
 
-那么此处应将参数更改为：
-
-{{< copyable "" >}}
+那么此处应将 `mysql.RegisterTLSConfig` 和 `dsn` 更改为：
 
 ```go
-dsn := "root:123456@tcp(xxx.tidbcloud.com:4000)/test?charset=utf8mb4"
+mysql.RegisterTLSConfig("register-tidb-tls", &tls.Config {
+    MinVersion: tls.VersionTLS12,
+    ServerName: "xxx.tidbcloud.com",
+})
+
+dsn := "2aEp24QWEDLqRFs.root:123456@tcp(xxx.tidbcloud.com:4000)/test?charset=utf8mb4&tls=register-tidb-tls"
 ```
 
 </div>
 
 <div label="使用 go-sql-driver/mysql" value="sqldriver">
 
-若你使用非本地默认集群、TiDB Cloud 或其他远程集群，更改 `sqldriver.go` 内 `dsn` 参数的值：
+若你使用 TiDB Cloud Serverless Tier 集群，更改 `sqldriver.go` 内 `dsn` 参数的值：
 
 {{< copyable "" >}}
 
 ```go
 dsn := "root:@tcp(127.0.0.1:4000)/test?charset=utf8mb4"
 ```
 
-若你设定的密码为 `123456`，而且从 TiDB Cloud 得到的连接字符串为：
+若你设定的密码为 `123456`，而且从 TiDB Cloud Serverless Tier 集群面板中得到的连接信息为：
 
-```
-mysql --connect-timeout 15 -u root -h xxx.tidbcloud.com -P 4000 -p
-```
+- Endpoint: `xxx.tidbcloud.com`
+- Port: `4000`
+- User: `2aEp24QWEDLqRFs.root`
 
-那么此处应将参数更改为：
+那么此处应将 `mysql.RegisterTLSConfig` 和 `dsn` 更改为：
 
 {{< copyable "" >}}
 
 ```go
-dsn := "root:123456@tcp(xxx.tidbcloud.com:4000)/test?charset=utf8mb4"
+mysql.RegisterTLSConfig("register-tidb-tls", &tls.Config {
+    MinVersion: tls.VersionTLS12,
+    ServerName: "xxx.tidbcloud.com",
+})
+
+dsn := "2aEp24QWEDLqRFs.root:123456@tcp(xxx.tidbcloud.com:4000)/test?charset=utf8mb4&tls=register-tidb-tls"
 ```
 
 </div>

diff --git a/develop/dev-guide-sample-application-java.md b/develop/dev-guide-sample-application-java.md
@@ -1553,7 +1553,7 @@ mysql --host 127.0.0.1 --port 4000 -u root<src/main/resources/dbinit.sql
 
 <div label="使用 Mybatis（推荐）" value="mybatis">
 
-若你使用非本地默认集群、TiDB Cloud 或其他远程集群，更改 `mybatis-config.xml` 内关于 `dataSource.url`、`dataSource.username`、`dataSource.password` 的参数：
+若你使用 TiDB Cloud Serverless Tier 集群，更改 `mybatis-config.xml` 内关于 `dataSource.url`、`dataSource.username`、`dataSource.password` 的参数：
 
 {{< copyable "" >}}
 
@@ -1598,11 +1598,11 @@ mysql --host 127.0.0.1 --port 4000 -u root<src/main/resources/dbinit.sql
 </configuration>
 ```
 
-若你设定的密码为 `123456`，而且从 TiDB Cloud 得到的连接字符串为：
+若你设定的密码为 `123456`，而且从 TiDB Cloud Serverless Tier 集群面板中得到的连接信息为：
 
-```
-mysql --connect-timeout 15 -u root -h xxx.tidbcloud.com -P 4000 -p
-```
+- Endpoint: `xxx.tidbcloud.com`
+- Port: `4000`
+- User: `2aEp24QWEDLqRFs.root`
 
 那么此处应将配置文件中 `dataSource` 节点内更改为：
 
@@ -1619,8 +1619,8 @@ mysql --connect-timeout 15 -u root -h xxx.tidbcloud.com -P 4000 -p
             <!-- Database pool -->
             <dataSource type="POOLED">
                 <property name="driver" value="com.mysql.jdbc.Driver"/>
-                <property name="url" value="jdbc:mysql://xxx.tidbcloud.com:4000/test"/>
-                <property name="username" value="root"/>
+                <property name="url" value="jdbc:mysql://xxx.tidbcloud.com:4000/test?sslMode=VERIFY_IDENTITY&amp;enabledTLSProtocols=TLSv1.2,TLSv1.3"/>
+                <property name="username" value="2aEp24QWEDLqRFs.root"/>
                 <property name="password" value="123456"/>
             </dataSource>
         ...
@@ -1632,7 +1632,7 @@ mysql --connect-timeout 15 -u root -h xxx.tidbcloud.com -P 4000 -p
 
 <div label="使用 Hibernate（推荐）" value="hibernate">
 
-若你使用非本地默认集群、TiDB Cloud 或其他远程集群，更改 `hibernate.cfg.xml` 内关于 hibernate.connection.url、hibernate.connection.username、hibernate.connection.password 的参数：
+若你使用 TiDB Cloud Serverless Tier 集群，更改 `hibernate.cfg.xml` 内关于 `hibernate.connection.url`、`hibernate.connection.username`、`hibernate.connection.password` 的参数：
 
 {{< copyable "" >}}
 
@@ -1662,11 +1662,11 @@ mysql --connect-timeout 15 -u root -h xxx.tidbcloud.com -P 4000 -p
 </hibernate-configuration>
 ```
 
-若你设定的密码为 `123456`，而且从 TiDB Cloud 得到的连接字符串为：
+若你设定的密码为 `123456`，而且从 TiDB Cloud Serverless Tier 集群面板中得到的连接信息为：
 
-```
-mysql --connect-timeout 15 -u root -h xxx.tidbcloud.com -P 4000 -p
-```
+- Endpoint: `xxx.tidbcloud.com`
+- Port: `4000`
+- User: `2aEp24QWEDLqRFs.root`
 
 那么此处应将配置文件更改为：
 
@@ -1683,8 +1683,8 @@ mysql --connect-timeout 15 -u root -h xxx.tidbcloud.com -P 4000 -p
         <!-- Database connection settings -->
         <property name="hibernate.connection.driver_class">com.mysql.cj.jdbc.Driver</property>
         <property name="hibernate.dialect">org.hibernate.dialect.TiDBDialect</property>
-        <property name="hibernate.connection.url">jdbc:mysql://xxx.tidbcloud.com:4000/test</property>
-        <property name="hibernate.connection.username">root</property>
+        <property name="hibernate.connection.url">jdbc:mysql://xxx.tidbcloud.com:4000/test?sslMode=VERIFY_IDENTITY&amp;enabledTLSProtocols=TLSv1.2,TLSv1.3</property>
+        <property name="hibernate.connection.username">2aEp24QWEDLqRFs.root</property>
         <property name="hibernate.connection.password">123456</property>
         <property name="hibernate.connection.autocommit">false</property>
 
@@ -1702,7 +1702,7 @@ mysql --connect-timeout 15 -u root -h xxx.tidbcloud.com -P 4000 -p
 
 <div label="使用 JDBC" value="jdbc">
 
-若你使用非本地默认集群、TiDB Cloud 或其他远程集群，更改 `JDBCExample.java` 内关于 Host、Port、User、Password 的参数：
+若你使用 TiDB Cloud Serverless Tier 集群，更改 `JDBCExample.java` 内关于 Host、Port、User、Password 的参数：
 
 {{< copyable "" >}}
 
@@ -1714,11 +1714,11 @@ mysqlDataSource.setUser("root");
 mysqlDataSource.setPassword("");
 ```
 
-若你设定的密码为 `123456`，而且从 TiDB Cloud 得到的连接字符串为：
+若你设定的密码为 `123456`，而且从 TiDB Cloud Serverless Tier 集群面板中得到的连接信息为：
 
-```
-mysql --connect-timeout 15 -u root -h xxx.tidbcloud.com -P 4000 -p
-```
+- Endpoint: `xxx.tidbcloud.com`
+- Port: `4000`
+- User: `2aEp24QWEDLqRFs.root`
 
 那么此处应将参数更改为：
 
@@ -1728,8 +1728,10 @@ mysql --connect-timeout 15 -u root -h xxx.tidbcloud.com -P 4000 -p
 mysqlDataSource.setServerName("xxx.tidbcloud.com");
 mysqlDataSource.setPortNumber(4000);
 mysqlDataSource.setDatabaseName("test");
-mysqlDataSource.setUser("root");
+mysqlDataSource.setUser("2aEp24QWEDLqRFs.root");
 mysqlDataSource.setPassword("123456");
+mysqlDataSource.setSslMode(PropertyDefinitions.SslMode.VERIFY_IDENTITY.name());
+mysqlDataSource.setEnabledTLSProtocols("TLSv1.2,TLSv1.3");
 ```
 
 </div>

diff --git a/develop/dev-guide-sample-application-spring-boot.md b/develop/dev-guide-sample-application-spring-boot.md
@@ -243,7 +243,7 @@ summary: 给出一个 Spring Boot 构建 TiDB 应用程序示例。
 
 ### 第 5 步第 1 部分：TiDB Cloud 更改参数
 
-若你使用非本地默认集群、TiDB Cloud 或其他远程集群，更改 `application.yml` (位于 `src/main/resources` 内) 关于 spring.datasource.url、spring.datasource.username、spring.datasource.password 的参数：
+若你使用 TiDB Cloud Serverless Tier 集群，更改 `application.yml`（位于 `src/main/resources` 内）关于 `spring.datasource.url`、`spring.datasource.username`、`spring.datasource.password` 的参数：
 
 ```yaml
 spring:
@@ -259,19 +259,19 @@ spring:
       ddl-auto: create-drop
 ```
 
-若你设定的密码为 `123456`，而且从 TiDB Cloud 得到的连接字符串为：
+若你设定的密码为 `123456`，而且从 TiDB Cloud Serverless Tier 集群面板中得到的连接信息为：
 
-```
-mysql --connect-timeout 15 -u root -h xxx.tidbcloud.com -P 4000 -p
-```
+- Endpoint: `xxx.tidbcloud.com`
+- Port: `4000`
+- User: `2aEp24QWEDLqRFs.root`
 
 那么此处应将参数更改为：
 
 ```yaml
 spring:
   datasource:
-    url: jdbc:mysql://xxx.tidbcloud.com:4000/test
-    username: root
+    url: jdbc:mysql://xxx.tidbcloud.com:4000/test?sslMode=VERIFY_IDENTITY&enabledTLSProtocols=TLSv1.2,TLSv1.3
+    username: 2aEp24QWEDLqRFs.root
     password: 123456
     driver-class-name: com.mysql.cj.jdbc.Driver
   jpa: