How to Connect to TiDB Using Hibernate

English | 中文

This is an example project by PingCAP for connecting to TiDB using the Hibernate library.

TiDB is a MySQL-compatible database. Hibernate is a currently popular open-source Java application persistence framework. Hibernate supports TiDB dialect from version 6.0.0.Beta2 and above, perfectly adapting to TiDB's features.

Prerequisites

• Recommended Java Development Kit (JDK) version 17 or above. You can choose OpenJDK or Oracle JDK based on your company and personal needs.
• Maven version 3.8 or above.
• Git.
• TiDB cluster. If you don't have a TiDB cluster yet, you can create one using the following methods:
  • (Recommended) Refer to Create TiDB Serverless Cluster to create your own TiDB Cloud cluster.
  • Refer to Deploy a Local Testing TiDB Cluster or Deploy a Production TiDB Cluster to create a local cluster.

Getting Started

1. Clone the Example Code Repository to Your Local Machine

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

2. Configure Connection Information

(Option 1) TiDB Serverless

1. In the TiDB Cloud console, open the Clusters page, select your TiDB Serverless cluster, go to the Overview page, and click the Connect button in the upper right corner.

2. Ensure that the configuration in the window matches your runtime environment.

   • Endpoint Type is Public
   • Connect With is General
   • Operating System matches your runtime environment

   If you are running in Windows Subsystem for Linux (WSL), switch to the corresponding Linux distribution.

3. Click Generate password to generate a password.

   If you have generated a password before, you can use the original password or click Reset Password to generate a new one.

4. Run the following command to copy and rename env.sh.example to env.sh:

   cp env.sh.example env.sh

5. Copy and paste the corresponding connection string into env.sh. Change the example results as follows.

   export TIDB_HOST='{gateway-region}.aws.tidbcloud.com'
   export TIDB_PORT='4000'
   export TIDB_USER='{prefix}.root'
   export TIDB_PASSWORD='{password}'
   export TIDB_DB_NAME='test'
   export USE_SSL='true'

   Replace placeholders {} with values obtained from the Connect window.

   TiDB Serverless requires the use of a secure connection, so the value of USE_SSL should be set to true.

6. Save the file.

(Option 2) TiDB Dedicated

1. In the TiDB Cloud Web Console, select your TiDB Dedicated cluster, go to the Overview page, click the Connect button in the upper right corner. Click Allow Access from Anywhere.

   For more configuration details, refer to TiDB Dedicated Standard Connection Guide.

2. Run the following command to copy and rename env.sh.example to env.sh:

   cp env.sh.example env.sh

3. Copy and paste the corresponding connection string into env.sh. Change the example results as follows.

   export TIDB_HOST='{host}.clusters.tidb-cloud.com'
   export TIDB_PORT='4000'
   export TIDB_USER='{prefix}.root'
   export TIDB_PASSWORD='{password}'
   export TIDB_DB_NAME='test'
   export USE_SSL='false'

   Replace placeholders {} with values obtained from the Connect window, and configure the certificate path downloaded in previous steps.

4. Save the file.

(Option 3) Self-Hosted TiDB

1. Run the following command to copy and rename env.sh.example to env.sh:

   cp env.sh.example env.sh

2. Copy and paste the corresponding connection string into env.sh. Change the example results as follows.

   export TIDB_HOST='{tidb_server_host}'
   export TIDB_PORT='4000'
   export TIDB_USER='root'
   export TIDB_PASSWORD='{password}'
   export TIDB_DB_NAME='test'
   export USE_SSL='false'

   Replace placeholders {} with values corresponding to your TiDB setup. If you are running TiDB on your local machine, the default Host address is 127.0.0.1, and the password is empty.

3. Save the file.

3. Run the Example Code

make

4. Expected Output

Expected Output

Notes

For more usage and details about Hibernate, refer to the Hibernate Official Documentation.

Next Steps

• You can continue reading the developer documentation to gain more knowledge about TiDB. For example: Insert Data, Update Data, Delete Data, Read from a Single Table, Transactions, SQL Performance Optimization.
• If you prefer a structured learning approach, we provide professional course for Java developers: Working with TiDB from Java.