使用 Rails 框架和 ActiveRecord ORM 连接 TiDB
TiDB 是一个兼容 MySQL 的数据库,Rails 是用 Ruby 编写的流行的 Web 框架,而 ActiveRecord ORM 是 Rails 中的对象关系映工具。
本文档将展示如何使用 TiDB 和 Rails 来完成以下任务:
- 设置你的环境。
- 使用 Rails 连接你的 TiDB 集群。
- 构建并运行你的应用程序。你也可以参考示例代码片段,完成基本的 CRUD 操作。
前置需求
为了能够顺利完成本文中的操作,你需要提前:
如果你还没有 TiDB 集群,可以按照以下方式创建:
- (推荐方式)参考创建 TiDB Serverless 集群,创建你自己的 TiDB Cloud 集群。
- 参考部署本地测试 TiDB 集群或部署正式 TiDB 集群,创建本地集群。
运行示例应用程序并连接到 TiDB
本小节演示如何运行示例应用程序的代码,并连接到 TiDB。
第 1 步:克隆示例代码仓库到本地
在你的终端窗口中运行以下命令,将示例代码仓库克隆到本地:
git clone https://github.com/tidb-samples/tidb-ruby-rails-quickstart.git
cd tidb-ruby-rails-quickstart
第 2 步:安装依赖
运行以下命令,安装示例代码所需要的依赖(包括 mysql2
和 dotenv
依赖包):
bundle install
为现有项目安装依赖
对于你的现有项目,运行以下命令以安装这些包:
bundle add mysql2 dotenv
第 3 步:配置连接信息
根据不同的 TiDB 部署方式,使用不同的方法连接到 TiDB 集群。
- TiDB Serverless
- TiDB Dedicated
- 本地部署的 TiDB
在 TiDB Cloud 的 Clusters 页面中,点击你的目标集群的名称,进入集群的 Overview 页面。
点击右上角的 Connect 按钮,将会弹出连接对话框。
在连接对话框中,从 Connect With 下拉列表中选择
Rails
,并保持 Connection Type 的默认设置为Public
。如果你还没有设置密码,点击 Generate Password 生成一个随机密码。
运行以下命令复制
.env.example
并将其重命名为.env
:cp .env.example .env编辑
.env
文件,按照以下方式设置DATABASE_URL
环境变量,并将占位符{}
替换为连接对话框中相应的连接参数:DATABASE_URL=mysql2://{user}:{password}@{host}:{port}/{database_name}?ssl_mode=verify_identity保存
.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_URL
环境变量,将占位符{}
替换为连接对话框中相应的连接参数,并将sslca
查询参数设置为从连接对话框下载的 CA 证书的文件路径:DATABASE_URL=mysql2://{user}:{password}@{host}:{port}/{database}?ssl_mode=verify_identity&sslca=/path/to/ca.pem保存
.env
文件。
运行以下命令复制
.env.example
并将其重命名为.env
:cp .env.example .env编辑
.env
文件,按照以下方式设置DATABASE_URL
环境变量,并将{user}
、{password}
、{host}
、{port}
和{database}
替换为你自己的 TiDB 连接信息:DATABASE_URL=mysql2://{user}:{password}@{host}:{port}/{database}如果你在本地运行 TiDB,那么默认的主机地址是
127.0.0.1
,密码为空。保存
.env
文件。
第 4 步:运行代码并查看结果
创建数据库和表:
bundle exec rails db:create bundle exec rails db:migrate填充示例数据:
bundle exec rails db:seed运行以下命令执行示例代码:
bundle exec rails runner ./quickstart.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-rails-quickstart。
连接到 TiDB
config/database.yml
中的以下代码使用 DATABASE_URL
系统变量的配置连接到 TiDB:
default: &default
adapter: mysql2
encoding: utf8mb4
pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
url: <%= ENV["DATABASE_URL"] %>
development:
<<: *default
test:
<<: *default
database: quickstart_test
production:
<<: *default
插入数据
以下查询创建了一个具有两个字段的 Player,并返回创建的 Player
对象:
new_player = Player.create!(coins: 100, goods: 100)
更多信息,请参考插入数据。
查询数据
以下通过 ID 查询返回特定 Player
的记录:
player = Player.find_by(id: new_player.id)
更多信息,请参考查询数据。
更新数据
以下查询更新特定 Player
对象:
player.update(coins: 50, goods: 50)
更多信息,请参考更新数据。
删除数据
以下查询删除特定 Player
对象:
player.destroy
更多信息,请参考删除数据。
最佳实践
默认情况下,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
,方便在不同环境中灵活且方便地部署。
下一步
- 从 ActiveRecord 文档中了解更多关于 ActiveRecord ORM 的用法。
- 你可以继续阅读开发者文档的其它章节来获取更多 TiDB 应用开发的最佳实践。例如:插入数据,更新数据,删除数据,单表读取,事务,SQL 性能优化等。
- 如果你更倾向于参与课程进行学习,我们也提供专业的 TiDB 开发者课程支持,并在考试后提供相应的资格认证。
需要帮助?
在 AskTUG 论坛上提问。