tidb-golang-gorm-quickstart

README

How to Connect to TiDB Using GORM

English | 中文

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

TiDB is a MySQL-compatible database. GORM is a popular open-source Golang ORM framework, and GORM supports TiDB's features like AUTO_RANDOM. TiDB is also the default supported database for GORM.

Prerequisites

• Recommended Golang version is 1.20 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-golang-gorm-quickstart.git
cd tidb-golang-gorm-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.example to .env:

   cp .env.example .env
   

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

   TIDB_HOST='{gateway-region}.aws.tidbcloud.com'
   TIDB_PORT='4000'
   TIDB_USER='{prefix}.root'
   TIDB_PASSWORD='{password}'
   TIDB_DB_NAME='test'
   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.example to .env:

   cp .env.example .env
   

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

   TIDB_HOST='{host}.clusters.tidb-cloud.com'
   TIDB_PORT='4000'
   TIDB_USER='{prefix}.root'
   TIDB_PASSWORD='{password}'
   TIDB_DB_NAME='test'
   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.example to .env:

   cp .env.example .env
   

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

   TIDB_HOST='{tidb_server_host}'
   TIDB_PORT='4000'
   TIDB_USER='root'
   TIDB_PASSWORD='{password}'
   TIDB_DB_NAME='test'
   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 details and information about GORM, you can refer to the official GORM 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 application developers: Learn SQL with TiDB.