Ruby 连接 Mysql – MySql2（完整指南）

Ruby 连接 Mysql – MySql2：从零开始建立数据库通信桥梁

在开发 Web 应用时，数据库是数据存储的核心。Ruby 语言虽然本身不自带数据库驱动，但通过第三方库可以轻松实现与 MySQL 的通信。其中，MySql2 是目前最主流、最稳定的 MySQL 连接驱动，广泛用于 Rails 框架和独立 Ruby 项目中。

想象一下，你的 Ruby 程序是一艘船，而 MySQL 数据库是一片深海中的岛屿。没有连接工具，船永远无法靠岸。而 MySql2 就是那条坚固的缆绳，把程序和数据库紧紧连接在一起。今天我们就来亲手搭建这条“数据缆绳”。

安装与配置 MySql2 驱动

在开始之前，请确保你的系统已经安装了 MySQL 服务。可以通过命令行验证：

mysql -u root -p

如果提示输入密码并成功进入 MySQL 命令行，说明服务已就绪。

接下来，我们需要在 Ruby 项目中引入 MySql2 驱动。推荐使用 Gem 包管理器（RubyGems）来安装。

gem install mysql2

注：如果你使用的是 Ruby 版本管理工具（如 rbenv 或 rvm），请确保当前环境已正确激活。

安装完成后，可以通过以下代码测试是否安装成功：

require 'mysql2'

client = Mysql2::Client.new(
  host: 'localhost',
  username: 'root',
  password: 'your_password'
)

puts "MySql2 驱动安装成功！"
client.close

这段代码的作用是：加载 mysql2 库，创建一个客户端连接对象，但并未连接具体数据库。如果输出“成功”，说明驱动已就绪。

创建数据库与测试表

为了后续操作，我们需要在 MySQL 中创建一个测试数据库和一张表。

打开 MySQL 命令行，执行以下 SQL 命令：

CREATE DATABASE IF NOT EXISTS test_ruby_db;

USE test_ruby_db;

CREATE TABLE users (
  id INT AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(100) NOT NULL,
  email VARCHAR(100) UNIQUE NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

这条命令做了三件事：

1. 创建名为 test_ruby_db 的数据库（如果不存在）
2. 切换到该数据库
3. 创建 users 表，包含用户 ID、姓名、邮箱和创建时间字段

建议：生产环境中的表结构应更加严谨，这里仅为演示目的。

建立 Ruby 与 MySQL 的连接

现在我们来写一个完整的连接示例，实现 Ruby 与 MySQL 的握手。

require 'mysql2'

config = {
  host: 'localhost',           # 数据库服务器地址
  username: 'root',            # 登录用户名
  password: 'your_password',   # 登录密码（请替换为你的实际密码）
  database: 'test_ruby_db',    # 要连接的数据库名
  port: 3306,                  # MySQL 默认端口
  encoding: 'utf8mb4'          # 推荐使用 utf8mb4 支持 emoji 等特殊字符
}

begin
  # 创建连接对象
  client = Mysql2::Client.new(config)

  # 测试连接是否成功
  puts "✅ 成功连接到 MySQL 数据库！"
  puts "当前数据库版本：#{client.query('SELECT VERSION()').first['VERSION()']}"

rescue Mysql2::Error => e
  # 捕获连接错误
  puts "❌ 连接失败：#{e.message}"
ensure
  # 无论是否成功，都尝试关闭连接
  client.close if client
end

代码说明：

• Mysql2::Client.new(config)：创建一个客户端实例，传入连接配置
• client.query()：执行 SQL 查询，返回结果集
• rescue 块用于捕获可能的连接异常，比如密码错误或服务未启动
• ensure 块确保连接最终被关闭，防止资源泄漏

运行这段代码，你应该看到类似输出：

✅ 成功连接到 MySQL 数据库！
当前数据库版本：8.0.32

执行增删改查操作：CRUD 实战

连接建立后，我们就可以进行真正的数据库操作了。下面是一个完整的 CRUD 示例。

require 'mysql2'

config = {
  host: 'localhost',
  username: 'root',
  password: 'your_password',
  database: 'test_ruby_db',
  port: 3306,
  encoding: 'utf8mb4'
}

client = Mysql2::Client.new(config)

puts "📝 插入新用户..."

insert_sql = <<-SQL
  INSERT INTO users (name, email) VALUES (?, ?)
SQL

client.prepare(insert_sql) do |stmt|
  stmt.execute("张三", "zhangsan@example.com")
  stmt.execute("李四", "lisi@example.com")
end

puts "✅ 插入成功：2 条记录"

puts "\n🔍 查询所有用户..."

result = client.query("SELECT id, name, email, created_at FROM users")

puts "ID | 姓名 | 邮箱 | 创建时间"
puts "---|------|------|------------"

result.each do |row|
  puts "#{row['id']} | #{row['name']} | #{row['email']} | #{row['created_at']}"
end

puts "\n✏️ 更新用户信息..."

update_sql = "UPDATE users SET name = ? WHERE email = ?"
client.prepare(update_sql) do |stmt|
  stmt.execute("张三（已修改）", "zhangsan@example.com")
end

puts "✅ 更新成功：张三的姓名已修改"

puts "\n🗑️ 删除用户..."

delete_sql = "DELETE FROM users WHERE email = ?"
client.prepare(delete_sql) do |stmt|
  stmt.execute("lisi@example.com")
end

puts "✅ 删除成功：李四的记录已被移除"

client.close

重要提示：

• 使用 prepare + execute 的方式执行 SQL，能有效防止 SQL 注入攻击
• ? 是占位符，由驱动自动处理转义，安全可靠
• result.each 遍历结果集，每个 row 是一个哈希对象，字段名作为键

配置文件分离：提升代码可维护性

当项目变大时，将数据库配置写死在代码中显然不合理。我们可以通过配置文件来管理。

创建一个 config/database.yml 文件：

development:
  adapter: mysql2
  host: localhost
  username: root
  password: your_password
  database: test_ruby_db
  port: 3306
  encoding: utf8mb4

然后在 Ruby 代码中读取配置：

require 'yaml'
require 'mysql2'

def load_database_config(env = 'development')
  config_path = File.join(__dir__, 'config', 'database.yml')
  configs = YAML.load_file(config_path)
  configs[env]
end

config = load_database_config

client = Mysql2::Client.new(config)

puts "✅ 已加载 #{config['database']} 环境配置"

result = client.query("SELECT COUNT(*) as total FROM users")
puts "当前用户总数：#{result.first['total']}"

client.close

这样做的好处是：不同环境（开发、测试、生产）可以使用不同配置，无需修改代码。

常见问题与解决方案

提示：在 macOS 上，可能需要使用 Homebrew 安装 MySQL 客户端：

brew install mysql-client
export PATH="/opt/homebrew/bin:$PATH"

总结：掌握 Ruby 连接 Mysql – MySql2 的核心要点

通过本文，我们一步步完成了从环境准备、驱动安装、连接配置到实际 CRUD 操作的全流程。关键点总结如下：

• MySql2 是 Ruby 与 MySQL 通信的标准桥梁，稳定、高效、功能完整。
• 使用 Mysql2::Client.new(config) 建立连接，配置项清晰明了。
• 优先使用 prepare + execute 模式执行 SQL，保障安全性。
• 将配置分离到独立文件，提升项目可维护性。
• 处理异常和资源释放（ensure 块）是专业开发的必备习惯。

无论你是正在学习 Ruby 的初学者，还是已有项目需要接入数据库的中级开发者，掌握 Ruby 连接 Mysql – MySql2 的核心技能，都是迈向真实应用开发的重要一步。记住：数据库不是冷冰冰的存储，它是你程序的“记忆中枢”——连接它，就是赋予程序生命。