Go-MySQL-Driver 技术文档

1. 安装指南

要安装 Go-MySQL-Driver，请使用以下命令将包安装到您的 $GOPATH 中：

go get -u github.com/go-sql-driver/mysql

确保您的计算机上已安装并配置了 Git。

2. 项目的使用说明

Go MySQL Driver 是 Go 语言 database/sql 包的一个 MySQL 驱动实现。您只需导入驱动，即可使用完整的 database/sql API。

使用 mysql 作为 driverName 和一个有效的 DSN 作为 dataSourceName：

import (
	"database/sql"
	"time"

	_ "github.com/go-sql-driver/mysql"
)

// ...

db, err := sql.Open("mysql", "user:password@/dbname")
if err != nil {
	panic(err)
}
// See "重要设置" section.
db.SetConnMaxLifetime(time.Minute * 3)
db.SetMaxOpenConns(10)
db.SetMaxIdleConns(10)

更多示例可以在我们的 Wiki 中找到。

重要设置

db.SetConnMaxLifetime() 用于确保在 MySQL 服务器、操作系统或其他中间件关闭连接之前，驱动程序能够安全地关闭连接。由于某些中间件可能会在 5 分钟内关闭空闲连接，我们建议设置小于 5 分钟的超时时间。此设置有助于负载均衡和更改系统变量。

db.SetMaxOpenConns() 建议用于限制应用程序使用的连接数。没有推荐的限制数，因为这取决于应用程序和 MySQL 服务器。

db.SetMaxIdleConns() 建议设置为与 db.SetMaxOpenConns() 相同。当它小于 SetMaxOpenConns() 时，连接的打开和关闭可能会比您预期的更频繁。空闲连接可以由 db.SetConnMaxLifetime() 关闭。如果您希望更快地关闭空闲连接，自 Go 1.15 起可以使用 db.SetConnMaxIdleTime()。

3. 项目API使用文档

本项目遵循 Go 的 database/sql 接口规范。具体 API 使用请参考 Go 官方文档以及 database/sql 包的说明。

4. 项目安装方式

如安装指南所述，使用 go get 命令即可安装本项目。

go get -u github.com/go-sql-driver/mysql

数据源名称 (DSN)

数据源名称 (DSN) 的常见格式如下（可选部分由方括号标记）：

[username[:password]@][protocol[(address)]]/dbname[?param1=value1&...&paramN=valueN]

一个完整的 DSN 示例：

username:password@protocol(address)/dbname?param=value

除了数据库名称外，所有值都是可选的。因此，最简化的 DSN 是：

/dbname

如果您不希望预先选择数据库，请留空 dbname：

/

这与空 DSN 字符串的效果相同：

`

自 v1.8.0 起，dbname 通过 PathEscape() 进行转义。如果您的数据库名称为 dbname/withslash，它将变为：

/dbname%2Fwithslash

另外，Config.FormatDSN 可以用来通过填充一个结构体来创建 DSN 字符串。

参数

参数区分大小写！

请注意，true、TRUE、True 或 1 均可表示布尔值 true。不出所料，false 可以表示为 false、FALSE、False 或 0。

allowAllFiles

类型：bool
有效值：true, false
默认值：false

allowAllFiles=true 禁用 LOAD DATA LOCAL INFILE 的文件允许列表，允许所有文件。可能不安全！

allowCleartextPasswords

类型：bool
有效值：true, false
默认值：false

allowCleartextPasswords=true 允许在需要时使用 明文客户端侧插件，例如定义了 PAM 认证插件 的账户。在某些配置中，发送明文密码可能存在安全问题。为了避免密码被截获的问题，客户端应使用保护密码的方法连接到 MySQL 服务器，例如 TLS / SSL、IPsec 或专用网络。

allowFallbackToPlaintext

类型：bool
有效值：true, false
默认值：false

allowFallbackToPlaintext=true 的行为类似于 MySQL 客户端的 --ssl-mode=PREFERRED 选项，如 连接到服务器的命令选项 中所述。

allowNativePasswords

类型：bool
有效值：true, false
默认值：true

allowNativePasswords=false 禁用 MySQL 本地密码方法的 usage。

allowOldPasswords

类型：bool
有效值：true, false
默认值：false

allowOldPasswords=true 允许使用不安全的旧密码方法。在大多数情况下应避免使用，但在某些情况下是必要的。也请参阅 old_passwords wiki 页面。

charset

类型：string
有效值：<名称>
默认值：无

设置用于客户端-服务器交互的字符集 ("SET NAMES <value>")。如果设置了多个字符集（用逗号分隔），则在设置字符集失败时使用下一个字符集。这启用了对 utf8mb4 （在 MySQL 5.5.3 中引入）的支持，并为较旧的服务器提供 utf8 的后备（charset=utf8mb4,utf8）。

也请参阅 Unicode 支持。

checkConnLiveness

类型：bool
有效值：true, false
默认值：true

在支持的平台中，从连接池中检索的连接在使用前会检查其活动状态。如果检查失败，相应的连接将被标记为坏连接，并使用另一个连接重试查询。 checkConnLiveness=false 禁用此连接活动状态的检查。

collation

类型：string
有效值：<名称>
默认值：utf8mb4_general_ci

设置用于客户端-服务器交互的校对规则。与 charset 不同，collation 不会发出额外的查询。如果目标服务器上不可用指定的校对规则，连接将失败。

服务器上可用的有效字符集列表可以通过 SHOW COLLATION 获取。

默认校对规则（utf8mb4_general_ci）从 MySQL 5.5 开始支持。对于较旧版本的 MySQL，您应该使用较旧的校对规则（例如 utf8_general_ci）。