Choose Driver or ORM
TiDB is highly compatible with the MySQL protocol but some features are incompatible with MySQL. For a full list of compatibility differences, see MySQL Compatibility.
Java
This section describes how to use drivers and ORM frameworks in Java.
Java drivers
- MySQL-JDBC
- TiDB-JDBC
Support level: Full
You can follow the MySQL documentation to download and configure a Java JDBC driver. It is recommended to use MySQL Connector/J 8.0.33 or later with TiDB v6.3.0 and newer.
For an example of how to build a complete application, see Build a simple CRUD app with TiDB and JDBC.
Support level: Full
TiDB-JDBC is a customized Java driver based on MySQL 8.0.29. Compiled based on MySQL official version 8.0.29, TiDB-JDBC fixes the bug of multi-parameter and multi-field EOF in the prepare mode in the original JDBC, and adds features such as automatic TiCDC snapshot maintenance and the SM3 authentication plugin.
The authentication based on SM3 is only supported in TiDB's TiDB-JDBC.
If you use Maven, add the following content to the <dependencies></dependencies> section in the pom.xml file:
<dependency>
<groupId>io.github.lastincisor</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>8.0.29-tidb-1.0.0</version>
</dependency>
If you need to enable SM3 authentication, add the following content to the <dependencies></dependencies> section in the pom.xml file:
<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>
If you use Gradle, add the following content to 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 frameworks
- Hibernate
- MyBatis
Support level: Full
To avoid manually managing complex relationships between different dependencies of an application, you can use Gradle or Maven to get all dependencies of your application, including those indirect ones. Note that only Hibernate 6.0.0.Beta2 or above supports the TiDB dialect.
If you are using Maven, add the following to your <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>
If you are using Gradle, add the following to your dependencies:
implementation 'org.hibernate:hibernate-core:6.0.0.CR2'
implementation 'mysql:mysql-connector-java:5.1.49'
- For an example of using Hibernate to build a TiDB application by native Java, see Build a simple CRUD app with TiDB and Hibernate.
- For an example of using Spring Data JPA or Hibernate to build a TiDB application by Spring, see Build a TiDB app using Spring Boot.
In addition, you need to specify the TiDB dialect in your Hibernate configuration file: org.hibernate.dialect.TiDBDialect, which is only supported by Hibernate 6.0.0.Beta2 or above. If your Hibernate version is earlier than 6.0.0.Beta2, upgrade it first.
Support level: Full
To avoid manually managing complex relationships between different dependencies of an application, you can use Gradle or Maven to get all dependencies of your application, including those indirect dependencies.
If you are using Maven, add the following to your <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>
If you are using Gradle, add the following to your dependencies:
implementation 'org.mybatis:mybatis:3.5.9'
implementation 'mysql:mysql-connector-java:5.1.49'
For an example of using MyBatis to build a TiDB application, see Build a simple CRUD app with TiDB and MyBatis.
Java client load balancing
tidb-loadbalance
Support level: Full
tidb-loadbalance is a load balancing component on the application side. With tidb-loadbalance, you can automatically maintain the node information of TiDB server and distribute JDBC connections on the client using the tidb-loadbalance policies. Using a direct JDBC connection between the client application and TiDB server has higher performance than using the load balancing component.
Currently, tidb-loadbalance supports the following policies: roundrobin, random, and weight.
If you use Maven, add the following content to the element body of <dependencies></dependencies> in the pom.xml file:
<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>
If you use Gradle, add the following content to 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
This section describes how to use drivers and ORM frameworks in Golang.
Golang drivers
go-sql-driver/mysql
Support level: Full
To download and configure a Golang driver, refer to the go-sql-driver/mysql documentation.
For an example of how to build a complete application, see Connect to TiDB with Go-MySQL-Driver.
Golang ORM frameworks
GORM
Support level: Full
GORM is a popular ORM framework for Golang. To get all dependencies in your application, you can use the go get command.
go get -u gorm.io/gorm
go get -u gorm.io/driver/mysql
For an example of using GORM to build a TiDB application, see Connect to TiDB with GORM.
Python
This section describes how to use drivers and ORM frameworks in Python.
Python drivers
- PyMySQL
- mysqlclient
- MySQL Connector/Python
Support level: Compatible
You can follow the PyMySQL documentation to download and configure the driver. It is recommended to use PyMySQL 1.0.2 or later versions.
For an example of using PyMySQL to build a TiDB application, see Connect to TiDB with PyMySQL.
Support level: Compatible
You can follow the mysqlclient documentation to download and configure the driver. It is recommended to use mysqlclient 2.1.1 or later versions.
For an example of using mysqlclient to build a TiDB application, see Connect to TiDB with mysqlclient.
Support level: Compatible
You can follow the MySQL Connector/Python documentation to download and configure the driver. It is recommended to use Connector/Python 8.0.31 or later versions.
For an example of using MySQL Connector/Python to build a TiDB application, see Connect to TiDB with MySQL Connector/Python.
Python ORM frameworks
- Django
- SQLAlchemy
- peewee
Support level: Full
Django is a popular Python web framework. To solve the compatibility issue between TiDB and Django, PingCAP provides a TiDB dialect django-tidb. To install it, you can see the django-tidb documentation.
For an example of using Django to build a TiDB application, see Connect to TiDB with Django.
Support level: Full
SQLAlchemy is a popular ORM framework for Python. To get all dependencies in your application, you can use the pip install SQLAlchemy==1.4.44 command. It is recommended to use SQLAlchemy 1.4.44 or later versions.
For an example of using SQLAlchemy to build a TiDB application, see Connect to TiDB with SQLAlchemy.
Support level: Compatible
peewee is a popular ORM framework for Python. To get all dependencies in your application, you can use the pip install peewee==3.15.4 command. It is recommended to use peewee 3.15.4 or later versions.
For an example of using peewee to build a TiDB application, see Connect to TiDB with peewee.