选择驱动或 ORM 框架

选择驱动或 ORM 框架

注意

TiDB 支持等级说明：

Full：表明 TiDB 已经兼容该工具的绝大多数功能，并且在该工具的新版本中对其保持兼容。PingCAP 将定期地对 TiDB 支持的第三方工具中的新版本进行兼容性测试。
Compatible：表明由于该工具已适配 MySQL，而 TiDB 高度兼容 MySQL 协议，因此 TiDB 可以兼容该工具的大部分功能。但 PingCAP 并未对该工具作出完整的兼容性验证，有可能出现一些意外的行为。

关于更多 TiDB 支持的第三方工具，你可以查看 TiDB 支持的第三方工具。

TiDB 兼容 MySQL 的协议，但存在部分与 MySQL 不兼容或有差异的特性，具体信息可查看与 MySQL 兼容性对比。

Java

本节介绍 Java 语言的 Driver 及 ORM 的使用方式。

Java Drivers

MySQL-JDBC
TiDB-JDBC

支持等级：Full

按照 MySQL 文档中的说明下载并配置 Java JDBC 驱动程序即可使用。对于 TiDB v6.3.0 及以上版本，建议使用 MySQL Connector/J 8.0.33 及以上版本。

注意

在 8.0.32 之前的 MySQL Connector/J 8.0 版本中存在一个 bug，当与 TiDB v6.3.0 之前的版本一起使用时，可能会导致线程卡死。为了避免此问题，建议使用 MySQL Connector/J 8.0.32 或更高版本，或者使用 TiDB JDBC（见 TiDB-JDBC 标签）。
MySQL Connector/J 8.0 与 TiDB v7.5.x 一起使用时，建议将 TiDB 配置项 server-version 设置为 "5.7.25-TiDB-v7.5.x"。这是因为，当 TiDB 服务器报告版本为 MySQL 8.0.11 或更高版本时，MySQL Connector/J 会尝试访问 TiDB v7.5.x 中不存在的 information_schema.KEYWORDS 表。

有关一个完整的实例应用程序，可参阅 TiDB 和 JDBC 的简单 CRUD 应用程序。

支持等级：Full

TiDB-JDBC 是基于 MySQL 8.0.29 的定制版本。TiDB-JDBC 基于 MySQL 官方 8.0.29 版本编译，修复了原 JDBC 在 prepare 模式下多参数、多字段 EOF 的错误，并新增 TiCDC snapshot 自动维护和 SM3 认证插件等功能。

基于 SM3 的认证仅在 TiDB 的 TiDB-JDBC 中支持。

如果你使用的是 Maven，请将以下内容添加到你的 <dependencies></dependencies>：

<dependency>
  <groupId>io.github.lastincisor</groupId>
  <artifactId>mysql-connector-java</artifactId>
  <version>8.0.29-tidb-1.0.0</version>
</dependency>

如果你需要使用 SM3 认证，请将以下内容添加到你的 <dependencies></dependencies>：

<dependency>
  <groupId>io.github.lastincisor</groupId>
  <artifactId>mysql-connector-java</artifactId>
  <version>8.0.29-tidb-1.0.0</version>
</dependency>
<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcprov-jdk15on</artifactId>
    <version>1.67</version>
</dependency>
<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcpkix-jdk15on</artifactId>
    <version>1.67</version>
</dependency>

如果你使用的是 Gradle，请将以下内容添加到你的 dependencies：

implementation group: 'io.github.lastincisor', name: 'mysql-connector-java', version: '8.0.29-tidb-1.0.0'
implementation group: 'org.bouncycastle', name: 'bcprov-jdk15on', version: '1.67'
implementation group: 'org.bouncycastle', name: 'bcpkix-jdk15on', version: '1.67'

Java ORM 框架

注意

Hibernate 当前不支持嵌套事务。
TiDB 从 v6.2.0 版本开始支持 Savepoint。如需在 @Transactional 中使用 Propagation.NESTED 事务传播选项，即 @Transactional(propagation = Propagation.NESTED)，请确认你的 TiDB 版本为 v6.2.0 或以上。
Hibernate
MyBatis

支持等级：Full

你可以使用 Gradle 或 Maven 获取你的应用程序的所有依赖项，且会帮你下载依赖项的间接依赖，而无需你手动管理复杂的依赖关系。注意，只有 Hibernate 6.0.0.Beta2 及以上版本才支持 TiDB 方言。

如果你使用的是 Maven，请将以下内容添加到你的 <dependencies></dependencies>：

<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>6.0.0.CR2</version>
</dependency>
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>5.1.49</version>
</dependency>

如果你使用的是 Gradle，请将以下内容添加到你的 dependencies：

implementation 'org.hibernate:hibernate-core:6.0.0.CR2'
implementation 'mysql:mysql-connector-java:5.1.49'

有关原生 Java 使用 Hibernate 进行 TiDB 应用程序构建的例子，可参阅 TiDB 和 Hibernate 的简单 CRUD 应用程序。
有关 Spring 使用 Spring Data JPA、Hibernate 进行 TiDB 应用程序构建的例子，可参阅使用 Spring Boot 构建 TiDB 应用程序。

额外的，你需要在 Hibernate 配置文件中指定 TiDB 方言 org.hibernate.dialect.TiDBDialect，此方言在 Hibernate 6.0.0.Beta2 以上才可支持。若你无法升级 Hibernate 版本，那么请你直接使用 MySQL 5.7 的方言 org.hibernate.dialect.MySQL57Dialect。但这可能造成不可预料的使用结果，及部分 TiDB 特有特性的缺失，如：序列等。

支持等级：Full

你可以使用 Gradle 或 Maven 获取应用程序的所有依赖项包括间接依赖，无需手动管理复杂的依赖关系。

如果你使用的是 Maven，请将以下内容添加到你的 <dependencies></dependencies>：

<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>3.5.9</version>
</dependency>
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>5.1.49</version>
</dependency>

如果你使用的是 Gradle，请将以下内容添加到你的 dependencies：

implementation 'org.mybatis:mybatis:3.5.9'
implementation 'mysql:mysql-connector-java:5.1.49'

使用 MyBatis 进行 TiDB 应用程序构建的例子，可参阅 TiDB 和 MyBatis 的简单 CRUD 应用程序。

Java 客户端负载均衡

tidb-loadbalance

支持等级：Full

tidb-loadbalance 是应用端的负载均衡组件。通过 tidb-loadbalance，你可以实现自动维护 TiDB server 的节点信息，根据节点信息使用 tidb-loadbalance 策略在客户端分发 JDBC 连接。客户端应用与 TiDB server 之间使用 JDBC 直连，性能高于使用负载均衡组件。

目前 tidb-loadbalance 已实现轮询、随机、权重等负载均衡策略。

注意

tidb-loadbalance 需配合 mysql-connector-j 一起使用。

如果你使用的是 Maven，请将以下内容添加到你的 <dependencies></dependencies>：

<dependency>
  <groupId>io.github.lastincisor</groupId>
  <artifactId>mysql-connector-java</artifactId>
  <version>8.0.29-tidb-1.0.0</version>
</dependency>
<dependency>
  <groupId>io.github.lastincisor</groupId>
  <artifactId>tidb-loadbalance</artifactId>
  <version>0.0.5</version>
</dependency>

如果你使用的是 Gradle，请将以下内容添加到你的 dependencies：

implementation group: 'io.github.lastincisor', name: 'mysql-connector-java', version: '8.0.29-tidb-1.0.0'
implementation group: 'io.github.lastincisor', name: 'tidb-loadbalance', version: '0.0.5'

Golang

本节介绍 Golang 语言的 Driver 及 ORM 的使用方式。

Golang Drivers

go-sql-driver/mysql

支持等级：Full

按照 go-sql-driver/mysql 文档中的说明获取并配置 Golang 驱动程序即可使用。

有关一个完整的实例应用程序，可参阅使用 Go-MySQL-Driver 连接到 TiDB。

Golang ORM 框架

GORM

支持等级：Full

GORM 是一个流行的 Golang 的 ORM 框架，你可以使用 go get 获取你的应用程序的所有依赖项。

go get -u gorm.io/gorm
go get -u gorm.io/driver/mysql

使用 GORM 进行 TiDB 应用程序构建的例子，可参阅使用 GORM 连接到 TiDB。

Python

本节介绍 Python 语言的 Driver 及 ORM 的使用方式。

Python Drivers

PyMySQL
mysqlclient
MySQL Connector/Python

支持等级：Compatible

按照 PyMySQL 文档中的说明下载并配置驱动程序即可使用。建议使用 1.0.2 及以上版本。

使用 PyMySQL 构建 TiDB 应用程序的例子，可参阅使用 PyMySQL 连接到 TiDB。

支持等级：Compatible

按照 mysqlclient 文档中的说明下载并配置驱动程序即可使用。建议使用 2.1.1 及以上版本。

使用 mysqlclient 构建 TiDB 应用程序的例子，可参阅使用 mysqlclient 连接到 TiDB。

支持等级：Compatible

按照 MySQL Connector/Python 文档中的说明下载并配置驱动程序即可使用。建议使用 8.0.31 及以上版本。

使用 MySQL Connector/Python 构建 TiDB 应用程序的例子，可参阅使用 MySQL Connector/Python 连接到 TiDB。

Python ORM 框架

Django
SQLAlchemy
peewee

支持等级：Full

Django 是一个流行的 Python Web 开发框架。为解决 TiDB 与 Django 的兼容性问题，PingCAP 开发了一个专门的适配器 django-tidb。你可以参考 django-tidb 文档进行安装。

使用 Django 构建 TiDB 应用程序的例子，可参阅使用 Django 连接到 TiDB。

支持等级：Full

SQLAlchemy 是一个流行的 Python 的 ORM 框架，你可以使用 pip install SQLAlchemy==1.4.44 获取你的应用程序的所有依赖项。建议使用 1.4.44 及以上版本。

使用 SQLAlchemy 构建 TiDB 应用程序的例子，可参阅使用 SQLAlchemy 连接到 TiDB。

支持等级：Compatible

peewee 是一个流行的 Python 的 ORM 框架，你可以使用 pip install peewee==3.15.4 获取你的应用程序的所有依赖项。建议使用 3.15.4 及以上版本。

使用 peewee 构建 TiDB 应用程序的例子，可参阅使用 peewee 连接到 TiDB。