使用 GORM 连接到 TiDB

TiDB 是一个兼容 MySQL 的数据库。GORM 是当前比较流行的开源 Golang ORM 框架并且适配了 TiDB 的 AUTO_RANDOM 等特性。同时，TiDB 为 GORM 的默认支持数据库。

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

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

注意

本文档适用于 TiDB Serverless、TiDB Dedicated 和本地部署的 TiDB。

前置需求

推荐 Go 1.20 及以上版本。
Git。
TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建：
- （推荐方式）参考创建 TiDB Serverless 集群，创建你自己的 TiDB Cloud 集群。
- 参考部署本地测试 TiDB 集群或部署正式 TiDB 集群，创建本地集群。

运行代码并连接到 TiDB

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

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

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

git clone https://github.com/tidb-samples/tidb-golang-gorm-quickstart.git
cd tidb-golang-gorm-quickstart

第 2 步：配置连接信息

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

TiDB Serverless
TiDB Dedicated
本地部署 TiDB

在 TiDB Cloud 的 Clusters 页面中，选择你的 TiDB Serverless 集群，进入集群的 Overview 页面。
点击右上角的 Connect 按钮，将会弹出连接对话框。
确认对话框中的配置和你的运行环境一致。
- Endpoint Type 为 Public。
- Branch 选择 main。
- Connect With 选择 General。
- Operating System 为你的运行环境。
小贴士
如果你在 Windows Subsystem for Linux (WSL) 中运行，请切换为对应的 Linux 发行版。
如果你还没有设置密码，点击 Generate Password 生成一个随机密码。
小贴士
如果你之前已经生成过密码，可以直接使用原密码，或点击 Reset Password 重新生成密码。
运行以下命令，将 .env.example 复制并重命名为 .env：
```
cp .env.example .env
```
复制并粘贴对应连接字符串至 .env 中。示例结果如下：
```
TIDB_HOST='{host}'  # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com
TIDB_PORT='4000'
TIDB_USER='{user}'  # e.g. xxxxxx.root
TIDB_PASSWORD='{password}'
TIDB_DB_NAME='test'
USE_SSL='true'
```
注意替换 {} 中的占位符为连接对话框中获得的值。
TiDB Serverless 要求使用 TLS (SSL) connection，因此 USE_SSL 的值应为 true。
保存 .env 文件。

在 TiDB Cloud 的 Clusters 页面中，选择你的 TiDB Dedicated 集群，进入集群的 Overview 页面。
点击右上角的 Connect 按钮，将会出现连接对话框。
在对话框中点击 Allow Access from Anywhere。
更多配置细节，可参考 TiDB Dedicated 标准连接教程（英文）。
运行以下命令，将 .env.example 复制并重命名为 .env：
```
cp .env.example .env
```

复制并粘贴对应的连接字符串至 .env 中。示例结果如下：

TIDB_HOST='{host}'  # e.g. tidb.xxxx.clusters.tidb-cloud.com
TIDB_PORT='4000'
TIDB_USER='{user}'  # e.g. root
TIDB_PASSWORD='{password}'
TIDB_DB_NAME='test'
USE_SSL='false'

注意替换 {} 中的占位符为连接对话框中获得的值。

保存 .env 文件。

运行以下命令，将 .env.example 复制并重命名为 .env：
```
cp .env.example .env
```
复制并粘贴对应 TiDB 的连接字符串至 .env 中。示例结果如下：
```
TIDB_HOST='{host}'
TIDB_PORT='4000'
TIDB_USER='root'
TIDB_PASSWORD='{password}'
TIDB_DB_NAME='test'
USE_SSL='false'
```
注意替换 {} 中的占位符为你的 TiDB 对应的值，并设置 USE_SSL 为 false。如果你在本机运行 TiDB，默认 Host 地址为 127.0.0.1，密码为空。
保存 .env 文件。

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

运行下述命令，执行示例代码：
```
make
```
查看 Expected-Output.txt，并与你的程序输出进行比较。结果近似即为连接成功。

示例代码片段

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

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

连接到 TiDB

func createDB() *gorm.DB {
    dsn := fmt.Sprintf("%s:%s@tcp(%s:%s)/%s?charset=utf8mb4&tls=%s",
        ${tidb_user}, ${tidb_password}, ${tidb_host}, ${tidb_port}, ${tidb_db_name}, ${use_ssl})

    db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{
        Logger: logger.Default.LogMode(logger.Info),
    })
    if err != nil {
        panic(err)
    }

    return db
}

在使用该函数时，你需要将 ${tidb_host}、${tidb_port}、${tidb_user}、${tidb_password}、${tidb_db_name} 等替换为你的 TiDB 集群的实际值。因为 TiDB Serverless 要求使用 TLS (SSL) connection，因此在连接到 TiDB Serverless 时 ${use_ssl} 的值应为 true。

插入数据

db.Create(&Player{ID: "id", Coins: 1, Goods: 1})

更多信息参考插入数据。

查询数据

var queryPlayer Player
db.Find(&queryPlayer, "id = ?", "id")

更多信息参考查询数据。

更新数据


db.Save(&Player{ID: "id", Coins: 100, Goods: 1})

更多信息参考更新数据。

删除数据

db.Delete(&Player{ID: "id"})

更多信息参考删除数据。

下一步

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

需要帮助?

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