使用 Spring Boot 连接 TiDB

TiDB 是一个兼容 MySQL 的数据库，Spring 是 Java 领域流行的开源容器框架。本文档以 Spring Boot 作为使用 Spring 的方式。

在本教程中，你可以学习如何结合 TiDB、Spring Data JPA 以及作为 JPA 提供者的 Hibernate，完成以下任务：

搭建你的开发环境。
使用 Hibernate 和 Spring Data JPA 连接到你的 TiDB 集群。
构建并运行你的应用程序。你还可以在示例代码片段中找到基本的 CRUD 操作示例。

注意

本教程适用于 TiDB Cloud Serverless, TiDB Cloud Essential, TiDB Cloud Dedicated 以及 TiDB 自建集群。

前置条件

完成本教程，你需要：

Java Development Kit (JDK) 17 或更高版本。你可以根据业务和个人需求选择 OpenJDK 或 Oracle JDK。
Maven 3.8 或更高版本。
Git。
一个 TiDB 集群。

如果你还没有 TiDB 集群，可以按如下方式创建：

（推荐）参考创建 TiDB Cloud Serverless 集群创建你自己的 TiDB Cloud 集群。
参考部署本地测试 TiDB 集群或部署生产环境 TiDB 集群创建本地集群。

运行示例应用连接 TiDB

本节演示如何运行示例应用代码并连接到 TiDB。

第 1 步：克隆示例应用仓库

在终端窗口中运行以下命令，克隆示例代码仓库：

git clone https://github.com/tidb-samples/tidb-java-springboot-jpa-quickstart.git
cd tidb-java-springboot-jpa-quickstart

第 2 步：配置连接信息

根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。

进入 Clusters 页面，点击目标集群名称进入集群概览页。
点击右上角的 Connect，弹出连接对话框。
确保连接对话框中的配置与你的操作环境一致。
- Connection Type 设置为 Public
- Branch 设置为 main
- Connect With 设置为 General
- Operating System 与你的环境一致
小贴士
如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。
点击 Generate Password 生成一个随机密码。
小贴士
如果你之前已经创建过密码，可以继续使用原密码，或点击 Reset Password 生成新密码。
运行以下命令，复制 env.sh.example 并重命名为 env.sh：
```
cp env.sh.example env.sh
```

将对应的连接字符串复制粘贴到 env.sh 文件中。示例结果如下：

export TIDB_HOST='{host}'  # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com
export TIDB_PORT='4000'
export TIDB_USER='{user}'  # e.g. xxxxxx.root
export TIDB_PASSWORD='{password}'
export TIDB_DB_NAME='test'
export USE_SSL='true'

请务必将 {} 占位符替换为连接对话框中获取的连接参数。

TiDB Cloud Serverless 需要安全连接，因此你需要将 USE_SSL 的值设置为 true。

保存 env.sh 文件。

进入 Clusters 页面，点击目标集群名称进入集群概览页。
点击右上角的 Connect，弹出连接对话框。
在连接对话框中，从 Connection Type 下拉列表选择 Public，然后点击 CA cert 下载 CA 证书。
如果你还未配置 IP 访问列表，请点击 Configure IP Access List，或参考 Configure an IP Access List 进行配置，以便首次连接。
除了 Public 连接类型，TiDB Cloud Dedicated 还支持 Private Endpoint 和 VPC Peering 连接类型。更多信息请参见 Connect to Your TiDB Cloud Dedicated Cluster。
运行以下命令，复制 env.sh.example 并重命名为 env.sh：
```
cp env.sh.example env.sh
```

将对应的连接字符串复制粘贴到 env.sh 文件中。示例结果如下：

export TIDB_HOST='{host}'  # e.g. tidb.xxxx.clusters.tidb-cloud.com
export TIDB_PORT='4000'
export TIDB_USER='{user}'  # e.g. root
export TIDB_PASSWORD='{password}'
export TIDB_DB_NAME='test'
export USE_SSL='false'

请务必将 {} 占位符替换为连接对话框中获取的连接参数。

保存 env.sh 文件。

运行以下命令，复制 env.sh.example 并重命名为 env.sh：
```
cp env.sh.example env.sh
```
将对应的连接字符串复制粘贴到 env.sh 文件中。示例结果如下：
```
export TIDB_HOST='{host}'
export TIDB_PORT='4000'
export TIDB_USER='root'
export TIDB_PASSWORD='{password}'
export TIDB_DB_NAME='test'
export USE_SSL='false'
```
请务必将 {} 占位符替换为连接参数，并将 USE_SSL 设置为 false。如果你在本地运行 TiDB，默认主机地址为 127.0.0.1，密码为空。
保存 env.sh 文件。

第 3 步：运行代码并检查结果

执行以下命令运行示例代码：
```
make
```
在另一个终端会话中运行请求脚本：
```
make request
```
检查 Expected-Output.txt 文件，确认输出是否一致。

示例代码片段

你可以参考以下示例代码片段，完成你自己的应用开发。

完整示例代码及运行方式请参考 tidb-samples/tidb-java-springboot-jpa-quickstart 仓库。

连接 TiDB

编辑配置文件 application.yml：

spring:
  datasource:
    url: ${TIDB_JDBC_URL:jdbc:mysql://localhost:4000/test}
    username: ${TIDB_USER:root}
    password: ${TIDB_PASSWORD:}
    driver-class-name: com.mysql.cj.jdbc.Driver
  jpa:
    show-sql: true
    database-platform: org.hibernate.dialect.TiDBDialect
    hibernate:
      ddl-auto: create-drop

配置完成后，将环境变量 TIDB_JDBC_URL、TIDB_USER 和 TIDB_PASSWORD 设置为你 TiDB 集群的实际值。配置文件为这些环境变量提供了默认值。如果你未配置环境变量，默认值如下：

TIDB_JDBC_URL："jdbc:mysql://localhost:4000/test"
TIDB_USER："root"
TIDB_PASSWORD：""

数据管理：`@Repository`

Spring Data JPA 通过 @Repository 接口管理数据。要使用 JpaRepository 提供的 CRUD 操作，需要继承 JpaRepository 接口：

@Repository
public interface PlayerRepository extends JpaRepository<PlayerBean, Long> {
}

然后，你可以在需要 PlayerRepository 的任何类中使用 @Autowired 进行自动依赖注入，从而直接使用 CRUD 功能。示例如下：

@Autowired
private PlayerRepository playerRepository;

插入或更新数据

playerRepository.save(player);

更多信息请参考插入数据和更新数据。

查询数据

PlayerBean player = playerRepository.findById(id).orElse(null);

更多信息请参考查询数据。

删除数据

playerRepository.deleteById(id);

更多信息请参考删除数据。

后续步骤

了解本文档中使用的第三方库和框架的更多用法，请参考其官方文档：
通过开发者指南各章节学习 TiDB 应用开发最佳实践，例如插入数据、更新数据、删除数据、单表读取、事务以及 SQL 性能优化。
通过专业的 TiDB 开发者课程学习，并在通过考试后获得 TiDB 认证。
通过 Java 开发者课程学习：Working with TiDB from Java。

需要帮助？

欢迎在 Discord 或 Slack 社区提问，或提交支持工单。