使用 Hibernate 连接到 TiDB

TiDB 是一个兼容 MySQL 的数据库。Hibernate 是当前比较流行的开源 Java 应用持久层框架。由于 TiDB 与 MySQL 高度兼容，建议使用 org.hibernate.dialect.MySQLDialect 作为 Hibernate 的方言 (Dialect)，以获得更好的长期兼容性。或者，也可以使用 TiDB 特定的方言 (org.hibernate.community.dialect.TiDBDialect)，该方言位于 Hibernate community dialects 项目中，但该项目并非由 PingCAP 维护。如果你在使用 MySQLDialect 时遇到兼容性问题，可以在 GitHub 上提交 issue。

本文档将展示如何使用 TiDB 和 Hibernate 来完成以下任务：

• 配置你的环境。
• 使用 Hibernate 连接到 TiDB 集群。
• 构建并运行你的应用程序。你也可以参考示例代码片段，完成基本的 CRUD 操作。

前置需求

• 推荐 Java Development Kit (JDK) 17 及以上版本。你可以根据公司及个人需求，自行选择 OpenJDK 或 Oracle JDK。
• Maven 3.8 及以上版本。
• Git。
• TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建：
  • （推荐方式）参考创建 TiDB Cloud Starter 集群，创建你自己的 TiDB Cloud 集群。
  • 参考部署本地测试 TiDB 集群或部署正式 TiDB 集群，创建本地集群。

运行代码并连接到 TiDB

本小节演示如何运行示例应用程序的代码，并连接到 TiDB。

第 1 步：克隆示例代码仓库到本地

运行以下命令，将示例代码仓库克隆到本地：

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

第 2 步：配置连接信息

根据不同的 TiDB 部署方式，使用不同的方法连接到 TiDB 集群。

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

1. 运行下述命令，执行示例代码：

   make
   

2. 查看 Expected-Output.txt，并与你的程序输出进行比较。结果近似即为连接成功。

示例代码片段

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

完整代码及其运行方式，见代码仓库 tidb-java-hibernate-quickstart。

连接到 TiDB

编写配置文件 hibernate.cfg.xml：

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
        "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
        "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
    <session-factory>

        <!-- Database connection settings -->
        <property name="hibernate.connection.driver_class">com.mysql.cj.jdbc.Driver</property>
        <property name="hibernate.dialect">org.hibernate.dialect.MySQLDialect</property>
        <property name="hibernate.connection.url">${tidb_jdbc_url}</property>
        <property name="hibernate.connection.username">${tidb_user}</property>
        <property name="hibernate.connection.password">${tidb_password}</property>
        <property name="hibernate.connection.autocommit">false</property>

        <!-- Required so a table can be created from the 'PlayerDAO' class -->
        <property name="hibernate.hbm2ddl.auto">create-drop</property>

        <!-- Optional: Show SQL output for debugging -->
        <property name="hibernate.show_sql">true</property>
        <property name="hibernate.format_sql">true</property>
    </session-factory>
</hibernate-configuration>

请将 ${tidb_jdbc_url}、${tidb_user}、${tidb_password} 等替换为你的 TiDB 集群的实际值。随后编写以下函数：

public SessionFactory getSessionFactory() {
    return new Configuration()
            .configure("hibernate.cfg.xml")
            .addAnnotatedClass(${your_entity_class})
            .buildSessionFactory();
}

在使用该函数时，你需要替换 ${your_entity_class} 为自己的数据实体类。如果你有多个实体类，需要添加多个 .addAnnotatedClass(${your_entity_class}) 语句。此外，这仅是 Hibernate 的其中一种配置方式。在配置中遇到任何问题，或想了解更多关于 Hibernate 的信息，你可参考 Hibernate 官方文档。

插入或更新数据

try (Session session = sessionFactory.openSession()) {
    session.persist(new PlayerBean("id", 1, 1));
}

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

查询数据

try (Session session = sessionFactory.openSession()) {
    PlayerBean player = session.get(PlayerBean.class, "id");
    System.out.println(player);
}

更多信息参考查询数据。

删除数据

try (Session session = sessionFactory.openSession()) {
    session.remove(new PlayerBean("id", 1, 1));
}

更多信息参考删除数据。

与 MySQLDialect 的兼容性

在 TiDB 中使用 MySQLDialect 时，请注意以下行为：

SERIALIZABLE 隔离级别

如果应用尝试将事务隔离级别设置为 SERIALIZABLE，TiDB 会返回如下错误：

The isolation level 'SERIALIZABLE' is not supported. Set tidb_skip_isolation_level_check=1 to skip this error

要避免该错误，请在服务端设置以下 TiDB 系统变量：

SET GLOBAL tidb_skip_isolation_level_check=1;

启用该变量后，TiDB 会接受请求中指定 SERIALIZABLE 而不返回错误。TiDB 内部仍然使用 REPEATABLE-READ，这是 TiDB 所支持的最强事务隔离级别。更多信息，请参见 tidb_skip_isolation_level_check。

CHECK 约束

Hibernate 的 @Check 注解会生成 DDL CHECK 约束。MySQL 8.0.16 及之后版本 默认会强制执行这些约束。但在 TiDB 中，如果没有显式启用，则不会强制执行。

要在 TiDB 中启用 CHECK 约束的强制执行，请设置以下系统变量：

SET GLOBAL tidb_enable_check_constraint=ON;

如果未启用该设置，TiDB 会接受 CHECK 约束的语法但不会强制执行，这可能导致数据完整性问题。更多信息，请参见 CHECK 约束。

下一步

• 关于 Hibernate 的更多使用方法，可以参考 Hibernate 官方文档。
• 你可以继续阅读开发者文档，以获取更多关于 TiDB 应用开发的最佳实践。例如：插入数据、更新数据、删除数据、单表读取、事务、SQL 性能优化等。
• 如果你更倾向于参与课程进行学习，我们也提供专业的 TiDB 开发者课程支持，并在考试后提供相应的资格认证。
• 我们还额外提供针对 Java 开发者的课程：使用 Connector/J - TiDB v6 及在 TiDB 上开发应用的最佳实践 - TiDB v6。

需要帮助?

如果在开发的过程中遇到问题，可以在 AskTUG 上进行提问，寻求帮助。