使用 mysql2 连接 TiDB
TiDB 是一个兼容 MySQL 的数据库。mysql2 是 Ruby 中最受欢迎的 MySQL 驱动之一。
本文档将展示如何使用 TiDB 和 mysql2 来完成以下任务:
- 设置你的环境。
- 使用 mysql2 连接你的 TiDB 集群。
- 构建并运行你的应用程序。你也可以参考示例代码片段,完成基本的 CRUD 操作。
前置需求
为了能够顺利完成本文中的操作,你需要提前:
如果你还没有 TiDB 集群,可以按照以下方式创建:
- (推荐方式)参考创建 TiDB Serverless 集群,创建你自己的 TiDB Cloud 集群。
- 参考部署本地测试 TiDB 集群或部署正式 TiDB 集群,创建本地集群。
运行示例应用程序并连接到 TiDB
本小节演示如何运行示例应用程序的代码,并连接到 TiDB。
第 1 步:克隆示例代码仓库到本地
在你的终端窗口中运行以下命令,将示例代码仓库克隆到本地:
git clone https://github.com/tidb-samples/tidb-ruby-mysql2-quickstart.git
cd tidb-ruby-mysql2-quickstart
第 2 步:安装依赖
运行以下命令,安装示例代码所需要的依赖(包括 mysql2
和 dotenv
依赖包):
bundle install
为现有项目安装依赖
对于你的现有项目,运行以下命令安装这些包:
bundle add mysql2 dotenv
第 3 步:配置连接信息
根据不同的 TiDB 部署方式,使用不同的方法连接到 TiDB 集群。
- TiDB Serverless
- TiDB Dedicated
- 本地部署的 TiDB
在 TiDB Cloud 的 Clusters 页面中,点击你的目标集群的名称,进入集群的 Overview 页面。
点击右上角的 Connect 按钮,将会弹出连接对话框。
确保连接对话框中的配置与你的操作环境匹配。
- Connection Type 设置为
Public
。 - Branch 选择
main
。 - Connect With 设置为
General
。 - Operating System 与你运行应用程序的操作系统相匹配。
- Connection Type 设置为
如果你还没有设置密码,点击 Generate Password 生成一个随机密码。
运行以下命令复制
.env.example
并将其重命名为.env
:cp .env.example .env编辑
.env
文件,按照以下方式设置环境变量,并将占位符{}
替换为连接对话框中相应的连接参数:DATABASE_HOST={host} DATABASE_PORT=4000 DATABASE_USER={user} DATABASE_PASSWORD={password} DATABASE_NAME=test DATABASE_ENABLE_SSL=true保存
.env
文件。
在 TiDB Cloud 的 Clusters 页面中,点击你的目标集群的名称,进入集群的 Overview 页面。
点击右上角的 Connect 按钮,将会弹出连接对话框。
在连接对话框中,从 Connection Type 下拉列表中选择 Public,并点击 CA cert 下载 CA 文件。
如果你尚未配置 IP 访问列表,请在首次连接前点击 Configure IP Access List 或按照配置 IP 访问列表(英文)中的步骤进行配置。
除 Public 连接类型外,TiDB Dedicated 还支持 Private Endpoint 和 VPC Peering 连接类型。详情请参阅连接 TiDB Dedicated 集群(英文)。
运行以下命令复制
.env.example
并将其重命名为.env
:cp .env.example .env编辑
.env
文件,按照以下方式设置环境变量,并将占位符{}
替换为连接对话框中相应的连接参数:DATABASE_HOST={host} DATABASE_PORT=4000 DATABASE_USER={user} DATABASE_PASSWORD={password} DATABASE_NAME=test DATABASE_ENABLE_SSL=true DATABASE_SSL_CA={downloaded_ssl_ca_path}保存
.env
文件。
运行以下命令复制
.env.example
并将其重命名为.env
:cp .env.example .env编辑
.env
文件,按照以下方式设置环境变量,并将占位符{}
替换为你的 TiDB 集群的连接参数:DATABASE_HOST={host} DATABASE_PORT=4000 DATABASE_USER={user} DATABASE_PASSWORD={password} DATABASE_NAME=test如果你在本地运行 TiDB,那么默认的主机地址是
127.0.0.1
,密码为空。保存
.env
文件。
第 4 步:运行代码并查看结果
运行以下命令来执行示例代码:
ruby app.rb
如果连接成功,你的终端将会输出所连接集群的版本信息:
🔌 Connected to TiDB cluster! (TiDB version: 5.7.25-TiDB-v7.1.5)
⏳ Loading sample game data...
✅ Loaded sample game data.
🆕 Created a new player with ID 12.
ℹ️ Got Player 12: Player { id: 12, coins: 100, goods: 100 }
🔢 Added 50 coins and 50 goods to player 12, updated 1 row.
🚮 Deleted 1 player data.
示例代码片段
你可参考以下关键代码片段,完成自己的应用开发。
完整代码及其运行方式,见代码仓库 tidb-samples/tidb-ruby-mysql2-quickstart。
连接到 TiDB
下面的代码使用环境变量中定义的连接选项来建立与 TiDB 集群的连接。
require 'dotenv/load'
require 'mysql2'
Dotenv.load # 从 .env 文件中加载环境变量
options = {
host: ENV['DATABASE_HOST'] || '127.0.0.1',
port: ENV['DATABASE_PORT'] || 4000,
username: ENV['DATABASE_USER'] || 'root',
password: ENV['DATABASE_PASSWORD'] || '',
database: ENV['DATABASE_NAME'] || 'test'
}
options.merge(ssl_mode: :verify_identity) unless ENV['DATABASE_ENABLE_SSL'] == 'false'
options.merge(sslca: ENV['DATABASE_SSL_CA']) if ENV['DATABASE_SSL_CA']
client = Mysql2::Client.new(options)
插入数据
以下查询创建一个具有两个字段的 player,并返回 last_insert_id
:
def create_player(client, coins, goods)
result = client.query(
"INSERT INTO players (coins, goods) VALUES (#{coins}, #{goods});"
)
client.last_id
end
更多信息,请参考插入数据。
查询数据
以下查询通过 ID 返回特定 player 的记录:
def get_player_by_id(client, id)
result = client.query(
"SELECT id, coins, goods FROM players WHERE id = #{id};"
)
result.first
end
更多信息,请参考查询数据。
更新数据
以下查询通过 ID 更新特定 player 的记录:
def update_player(client, player_id, inc_coins, inc_goods)
result = client.query(
"UPDATE players SET coins = coins + #{inc_coins}, goods = goods + #{inc_goods} WHERE id = #{player_id};"
)
client.affected_rows
end
更多信息,请参考更新数据。
删除数据
以下查询删除特定 player 的记录:
def delete_player_by_id(client, id)
result = client.query(
"DELETE FROM players WHERE id = #{id};"
)
client.affected_rows
end
更多信息,请参考删除数据。
最佳实践
默认情况下,mysql2 gem 可以按照特定的顺序搜索现有的 CA 证书,直到找到相应的文件。
- 对于 Debian、Ubuntu、Gentoo、Arch 或 Slackware,证书的默认存储路径为
/etc/ssl/certs/ca-certificates.crt
。 - 对于 RedHat、Fedora、CentOS、Mageia、Vercel 或 Netlify,证书的默认存储路径为
/etc/pki/tls/certs/ca-bundle.crt
。 - 对于 OpenSUSE,证书的默认存储路径为
/etc/ssl/ca-bundle.pem
。 - 对于 macOS 或 Alpine(docker 容器),证书的默认存储路径为
/etc/ssl/cert.pem
。
尽管可以手动指定 CA 证书路径,但在多环境部署场景中这可能会引起不必要的麻烦,因为不同的机器和环境可能存储 CA 证书的位置不同。因此,建议将 sslca
设置为 nil
,方便在不同环境中灵活且方便地部署。
下一步
- 从 mysql2 的文档中了解更多关于 mysql2 驱动的使用情况。
- 你可以继续阅读开发者文档的其它章节来获取更多 TiDB 应用开发的最佳实践。例如:插入数据,更新数据,删除数据,单表读取,事务,SQL 性能优化等。
- 如果你更倾向于参与课程进行学习,我们也提供专业的 TiDB 开发者课程支持,并在考试后提供相应的资格认证。
需要帮助?
在 AskTUG 论坛上提问。