Skip to content

Latest commit

 

History

History
316 lines (224 loc) · 11.3 KB

README-zh.md

File metadata and controls

316 lines (224 loc) · 11.3 KB

使用 mysql2 gem 连接 TiDB 集群

语言 驱动

以下指南将向你展示如何使用 Ruby 驱动器 mysql2 连接到 TiDB 集群，并执行基本的 SQL 操作，如创建、读取、更新和删除。

注意：

TiDB 是一个兼容 MySQL 的数据库，这意味着你可以在应用程序中使用来自 MySQL 生态系统的熟悉的驱动/ORM 框架连接到 TiDB 集群。

唯一的区别是，如果你使用公共端点连接到 TiDB Serverless 集群，你必须 在 mysql2 驱动上启用 TLS 连接。

前提条件

要完成本指南，你需要：

  • 机器上安装了 Ruby 版本 >= 3.0
  • 机器上安装了 Bundler
  • 机器上安装了 Git
  • 运行中的 TiDB 集群

如果你还没有 TiDB 集群，请使用以下其中一种方式创建一个：

  1. （推荐）立即在 TiDB Cloud 上启动一个 TiDB Serverless 集群。
  2. 在你的本地机器上使用 TiUP CLI 启动一个 TiDB Playground 集群。

入门

本节将演示如何运行示例应用程序代码并使用 mysql2 驱动连接到 TiDB。

1. 克隆仓库

运行以下命令将样本代码本地化：

git clone https://github.com/tidb-samples/tidb-ruby-mysql2-quickstart.git
cd tidb-ruby-mysql2-quickstart

2. 安装依赖项

运行以下命令安装样本代码所需的依赖项（包括 mysql2 包）：

bundle install
安装依赖项到现有项目

对于你的现有项目，运行以下命令安装以下包：

  • mysql2：Ruby 的 MySQL 驱动，用于数据库连接和 SQL 操作。
  • dotenv：加载 .env 文件中环境变量的实用程序包。
bundle add mysql2 dotenv

3. 获取连接参数

(选项 1) TiDB Serverless

您可以通过以下步骤在TiDB Cloud的Web控制台获取数据库连接参数：

  1. 导航至集群页面，然后点击目标集群的名称，进入其概述页面。

  2. 在右上角点击连接。

  3. 在连接对话框中，从连接方式下拉列表中选择通用，并保持终端类型的默认设置为公开。

  4. 如果您还没有设置密码，请点击创建密码生成一个随机密码。

  5. 复制代码块上显示的连接参数。

    The connection dialog of TiDB Serverless
    TiDB Serverless的连接对话框
(选项 2) TiDB独立版

您可以通过以下步骤在TiDB Cloud的Web控制台获取数据库连接参数：

  1. 导航至集群页面，然后点击目标集群的名称，进入其概述页面。

  2. 点击右上角的连接。将显示连接对话框。

  3. 为集群创建流量过滤器。

    1. 点击允许任何地方的访问，添加一个新的CIDR地址规则，允许来自任何IP地址的客户端访问。
    2. 点击创建过滤器确认变更。

  4. 在对话框的步骤2：下载TiDB集群CA下，点击下载TiDB集群CA，以便于TLS连接到TiDB集群。

  5. 在对话框的步骤3：用SQL客户端连接下，从连接方式下拉列表中选择通用，并从终端类型下拉列表中选择公开。

  6. 复制代码块上显示的连接参数。

(选项 3) TiDB 自托管

为你的集群准备以下连接参数：

  • 主机：运行TiDB集群的IP地址或域名（例如：127.0.0.1）。
  • 端口：数据库服务器运行的端口（默认：4000）。
  • 用户：数据库用户名（默认：root）。
  • 密码：数据库用户密码（TiDB Playground 默认无密码）。

4. 设置环境变量

(选项 1) TiDB Serverless
  1. 复制 .env.example 文件到 .env 文件。
  2. 编辑 .env 文件，并替换 <host>, <user>, 和 <password> 的占位符为复制的连接参数。
  3. 将 DATABASE_ENABLE_SSL 修改为 true 以启用 TLS 连接。（公共端点需要）
DATABASE_HOST=<host>
DATABASE_PORT=4000
DATABASE_USER=<user>
DATABASE_PASSWORD=<password>
DATABASE_NAME=test
DATABASE_ENABLE_SSL=true
(选项 2) TiDB Dedicated
  1. 复制 .env.example 文件到 .env 文件。
  2. 编辑 .env 文件，并替换 <host>, <user>, 和 <password> 的占位符为复制的连接参数。
  3. 将 DATABASE_ENABLE_SSL 修改为 true 以启用 TLS 连接。（公共端点需要）
  4. 将 DATABASE_SSL_CA 修改为 TiDB Cloud 提供的 CA 证书的文件路径。（公共端点需要）
DATABASE_HOST=<host>
DATABASE_PORT=4000
DATABASE_USER=<user>
DATABASE_PASSWORD=<password>
DATABASE_NAME=test
DATABASE_ENABLE_SSL=true
DATABASE_SSL_CA=/path/to/ca.pem
(选项 3) TiDB 自托管
  1. 复制 .env.example 文件到 .env 文件。
  2. 编辑 .env 文件，并替换 <host>, <user>, 和 <password> 的占位符为复制的连接参数。

默认情况下，TiDB 自托管集群使用非加密连接在 TiDB 服务器和客户端之间，如果你的集群没有启用 TLS 连接则跳过下面的步骤。

  1. （可选）将 DATABASE_ENABLE_SSL 修改为 true 以启用 TLS 连接。
  2. （可选）将 DATABASE_SSL_CA 修改为定义 ssl-ca 选项的受信任 CA 证书的文件路径。
DATABASE_HOST=<host>
DATABASE_PORT=4000
DATABASE_USER=<user>
DATABASE_PASSWORD=<password>
DATABASE_NAME=test
# DATABASE_ENABLE_SSL=true
# DATABASE_SSL_CA=/path/to/ca.pem

5. 运行示例代码

执行以下命令以运行示例代码：

ruby app.rb

如果连接成功，控制台将输出 TiDB 集群的版本。

期望的执行输出：

🔌 成功连接到 TiDB 集群！（TiDB 版本：5.7.25-TiDB-v7.1.0）
⏳ 正在加载示例游戏数据...
✅ 已加载示例游戏数据。

🆕 创建了一个新的玩家，ID 为 12。
ℹ️ 获取了玩家 12：Player { id: 12, coins: 100, goods: 100 }
🔢 给玩家 12 增加了 50 金币和 50 商品，更新了 1 行。
🚮 删除了 1 个玩家数据。

示例代码

连接至 TiDB 集群

以下代码采用环境变量（存储在 .env 文件中）作为连接选项，与 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)
对于 TiDB Serverless

要通过公共端点与 TiDB Serverless 连接，请将环境变量 DATABASE_ENABLE_SSL 设置为 true 以开启 TLS 连接。

默认情况下，mysql2 gem 将按一定的顺序搜索现有的 CA 证书，直到找到一个文件为止。

  1. /etc/ssl/certs/ca-certificates.crt # Debian / Ubuntu / Gentoo / Arch / Slackware
  2. /etc/pki/tls/certs/ca-bundle.crt # RedHat / Fedora / CentOS / Mageia / Vercel / Netlify
  3. /etc/ssl/ca-bundle.pem # OpenSUSE
  4. /etc/ssl/cert.pem # MacOS / Alpine (docker container)

虽然可以手动指定 CA 证书路径，但这种方式可能会导致在多环境部署场景中产生显著的不便，因为不同的机器和环境可能会将 CA 证书存储在不同的位置。因此，建议将 sslca 设置为 nil，以提高部署在不同环境中的灵活性和便利性。

对于 TiDB Dedicated

要通过公共端点与 TiDB Dedicated 连接，请将环境变量 DATABASE_ENABLE_SSL 设置为 true 以开启 TLS 连接，并使用 DATABASE_SSL_CA 指定从TiDB Cloud Web 控制台下载的 CA 证书的文件路径。

插入数据

以下查询创建一个带有两个字段的单个玩家，并返回 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

有关更多信息，请参阅删除数据。

下一步