使用 JDBC 连接 TiDB

TiDB 是一个兼容 MySQL 的数据库，JDBC（Java Database Connectivity）是 Java 的数据访问 API。MySQL Connector/J 是 MySQL 的 JDBC 实现。

在本教程中，你可以学习如何使用 TiDB 和 JDBC 完成以下任务：

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

Note

本教程适用于平凯数据库云服务 Starter、Essential 以及 TiDB 自建集群。

从 TiDB v7.4 开始，如果在 JDBC URL 中未配置 connectionCollation，且 characterEncoding 未配置或设置为 UTF-8，则 JDBC 连接中使用的排序规则取决于 JDBC 驱动版本。更多信息请参见 JDBC 连接中使用的排序规则。

前置条件

完成本教程，你需要：

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

Note

出于安全考虑，建议你在通过互联网连接 TiDB 集群时，使用 VERIFY_IDENTITY 建立 TLS 连接。平凯数据库云服务 Starter 和 Essential 使用 Subject Alternative Name (SAN) 证书，这要求 MySQL Connector/J 版本大于等于 8.0.22。

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

（推荐）参考创建平凯数据库云服务 Starter 集群创建属于你自己的平凯数据库云服务集群。
参考部署本地测试 TiDB 集群或部署生产环境 TiDB 集群创建本地集群。

运行示例应用连接 TiDB

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

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

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

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

第 2 步：配置连接信息

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

进入 Clusters 页面，然后点击目标集群名称进入集群概览页。
点击右上角的 Connect，弹出连接对话框。
确保连接对话框中的配置与你的操作环境一致。
- Connection Type 设置为 Public
- Branch 设置为 main
- Connect With 设置为 General
- Operating System 与你的环境一致
Tip

如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。
点击 Generate Password 生成随机密码。

Tip

如果你之前已经创建过密码，可以继续使用原密码，或点击 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'
```
请务必将 {} 占位符替换为连接对话框中获取的连接参数。

平凯数据库云服务 Starter 需要安全连接，因此你需要将 USE_SSL 的值设置为 true。
保存 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
```
检查 Expected-Output.txt 文件，确认输出是否一致。

示例代码片段

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

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

连接 TiDB

public MysqlDataSource getMysqlDataSource() throws SQLException {
    MysqlDataSource mysqlDataSource = new MysqlDataSource();

    mysqlDataSource.setServerName(${tidb_host});
    mysqlDataSource.setPortNumber(${tidb_port});
    mysqlDataSource.setUser(${tidb_user});
    mysqlDataSource.setPassword(${tidb_password});
    mysqlDataSource.setDatabaseName(${tidb_db_name});
    if (${tidb_use_ssl}) {
        mysqlDataSource.setSslMode(PropertyDefinitions.SslMode.VERIFY_IDENTITY.name());
        mysqlDataSource.setEnabledTLSProtocols("TLSv1.2,TLSv1.3");
    }

    return mysqlDataSource;
}

使用该函数时，你需要将 ${tidb_host}、${tidb_port}、${tidb_user}、${tidb_password} 和 ${tidb_db_name} 替换为你 TiDB 集群的实际值。

插入数据

public void createPlayer(PlayerBean player) throws SQLException {
    MysqlDataSource mysqlDataSource = getMysqlDataSource();
    try (Connection connection = mysqlDataSource.getConnection()) {
        PreparedStatement preparedStatement = connection.prepareStatement("INSERT INTO player (id, coins, goods) VALUES (?, ?, ?)");
        preparedStatement.setString(1, player.getId());
        preparedStatement.setInt(2, player.getCoins());
        preparedStatement.setInt(3, player.getGoods());

        preparedStatement.execute();
    }
}

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

查询数据

public void getPlayer(String id) throws SQLException {
    MysqlDataSource mysqlDataSource = getMysqlDataSourceByEnv();
    try (Connection connection = mysqlDataSource.getConnection()) {
        PreparedStatement preparedStatement = connection.prepareStatement("SELECT * FROM player WHERE id = ?");
        preparedStatement.setString(1, id);
        preparedStatement.execute();

        ResultSet res = preparedStatement.executeQuery();
        if(res.next()) {
            PlayerBean player = new PlayerBean(res.getString("id"), res.getInt("coins"), res.getInt("goods"));
            System.out.println(player);
        }
    }
}

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

更新数据

public void updatePlayer(String id, int amount, int price) throws SQLException {
    MysqlDataSource mysqlDataSource = getMysqlDataSourceByEnv();
    try (Connection connection = mysqlDataSource.getConnection()) {
        PreparedStatement transfer = connection.prepareStatement("UPDATE player SET goods = goods + ?, coins = coins + ? WHERE id=?");
        transfer.setInt(1, -amount);
        transfer.setInt(2, price);
        transfer.setString(3, id);
        transfer.execute();
    }
}

更多信息请参考更新数据。

删除数据

public void deletePlayer(String id) throws SQLException {
    MysqlDataSource mysqlDataSource = getMysqlDataSourceByEnv();
    try (Connection connection = mysqlDataSource.getConnection()) {
        PreparedStatement deleteStatement = connection.prepareStatement("DELETE FROM player WHERE id=?");
        deleteStatement.setString(1, id);
        deleteStatement.execute();
    }
}

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

实用说明

使用驱动还是 ORM 框架？

Java 驱动提供了对数据库的底层访问，但这要求开发者：

手动建立和释放数据库连接。
手动管理数据库事务。
手动将数据行映射为数据对象。

除非你需要编写复杂的 SQL 语句，否则推荐使用 ORM 框架进行开发，例如 Hibernate、MyBatis 或 Spring Data JPA。它可以帮助你：

减少用于管理连接和事务的样板代码。
通过数据对象操作数据，而不是大量 SQL 语句。

MySQL 兼容性

在 MySQL 中，当你向 DECIMAL 列插入数据时，如果小数位数超过了该列定义的精度，MySQL 会自动截断多余的小数位并成功插入，无论多余的小数位有多少。

在 TiDB v8.5.3 及更早版本中：

如果小数位数超过定义的精度但不超过 72，TiDB 也会自动截断多余的小数位并成功插入。
但如果小数位数超过 72，插入会失败并返回错误。

从 TiDB v8.5.4 开始，TiDB 行为与 MySQL 保持一致：无论多余的小数位有多少，都会自动截断并成功插入。

后续步骤

通过 MySQL Connector/J 文档学习更多 MySQL Connector/J 的用法。
通过开发者指南各章节学习 TiDB 应用开发最佳实践，例如插入数据、更新数据、删除数据、单表读取、事务以及 SQL 性能优化。
通过专业的 TiDB 开发者课程学习，并在通过考试后获得 TiDB 认证。
通过 Java 开发者课程学习：Working with TiDB from Java。

需要帮助？

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