Go-MySQL-Driver 中间件驱动程序连接器
特征
- 轻量级和 快速
- 本机 Go 实现。没有 C 绑定,只是纯粹的 Go
- 通过 TCP/IPv4、TCP/IPv6、Unix 域套接字或 自定义协议的连接
- 自动处理断开的连接
- 自动连接池(通过 database/sql 包)
- 支持大于 16MB 的查询
- 全力
sql.RawBytes
支持。 LONG DATA
准备好的语句中的智能处理LOAD DATA LOCAL INFILE
通过文件许可名单和io.Reader
支持获得安全支持- 可选
time.Time
解析 - 可选占位符插值
要求
- 转到 1.13 或更高版本。我们的目标是支持 Go 的 3 个最新版本。
- MySQL (4.1+)、MariaDB、Percona Server、Google CloudSQL 或 Sphinx (2.2.3+)
安装
使用 shell 中的 go 工具 将软件包简单地安装到您的 $GOPATH 中:
$ go get -u github.com/go-sql-driver/mysql
确保 Git 安装 在您的机器上和系统的 PATH
。
用法
Go MySQL Driver 是 Go database/sql/driver
接口的一个实现。您只需要导入驱动程序,然后就可以使用完整的 database/sql
API。
使用 mysql
as 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 "Important settings" section. db.SetConnMaxLifetime(time.Minute * 3) db.SetMaxOpenConns(10) db.SetMaxIdleConns(10)
重要设置
db.SetConnMaxLifetime()
在 MySQL 服务器、操作系统或其他中间件关闭连接之前,需要确保驱动程序安全地关闭连接。由于一些中间件会在 5 分钟后关闭空闲连接,我们建议超时时间短于 5 分钟。此设置也有助于负载平衡和更改系统变量。
db.SetMaxOpenConns()
强烈建议限制应用程序使用的连接数。没有推荐的限制数量,因为它取决于应用程序和 MySQL 服务器。
db.SetMaxIdleConns()
建议设置为相同db.SetMaxOpenConns()
。当它小于 时SetMaxOpenConns()
,连接可以比您预期的更频繁地打开和关闭。空闲连接可以由 关闭db.SetConnMaxLifetime()
。如果你想更快地关闭空闲连接,你可以db.SetConnMaxIdleTime()
从 Go 1.15 开始使用。
DSN(数据源名称)
数据源名称具有通用格式,例如PEAR DB使用它,但没有类型前缀(用方括号标记的可选部分):
[username[:password]@][protocol[(address)]]/dbname[?param1=value1&...¶mN=valueN]
最完整形式的 DSN:
username:password@protocol(address)/dbname?param=value
除 databasename 外,所有值都是可选的。所以最小的 DSN 是:
/dbname
如果您不想预先选择数据库,请将其dbname
留空:
/
这与空的 DSN 字符串具有相同的效果:
或者,Config.FormatDSN可用于通过填充结构来创建 DSN 字符串。
密码
密码可以由任何字符组成。逃避是没有必要的。
协议
有关可用网络的详细信息,请参阅net.Dial。一般来说,您应该使用 Unix 域套接字(如果可用)和 TCP 否则以获得最佳性能。
地址
对于 TCP 和 UDP 网络,地址的形式为host[:port]
. 如果port
省略,将使用默认端口。如果host
是文字 IPv6 地址,则必须将其括在方括号中。函数net.JoinHostPort和net.SplitHostPort以这种形式操作地址。
对于 Unix 域套接字,地址是 MySQL-Server-socket 的绝对路径,例如/var/run/mysqld/mysqld.sock
或/tmp/mysql.sock
。
参数
参数区分大小写!
请注意,任何true
, TRUE
,True
或1
都被接受来代表真正的布尔值。不足为奇的是,假可以被指定为任何的:false
,FALSE
,False
或0
。
allowAllFiles
Type: bool
Valid Values: true, false
Default: false
allowAllFiles=true
禁用文件许可名单LOAD DATA LOCAL INFILE
并允许所有文件。 可能没有安全感!
allowCleartextPasswords
Type: bool
Valid Values: true, false
Default: false
allowCleartextPasswords=true
如果帐户需要,允许使用明文客户端插件,例如使用PAM 身份验证插件定义的插件。在某些配置中,以明文形式发送密码可能是一个安全问题。为避免密码可能被截获时出现问题,客户端应使用保护密码的方法连接到 MySQL 服务器。可能性包括TLS/SSL、IPsec 或专用网络。
allowNativePasswords
Type: bool
Valid Values: true, false
Default: true
allowNativePasswords=false
不允许使用 MySQL 本机密码方法。
allowOldPasswords
Type: bool
Valid Values: true, false
Default: false
allowOldPasswords=true
允许使用不安全的旧密码方法。这应该避免,但在某些情况下是必要的。另请参阅old_passwords 维基页面。
charset
Type: string
Valid Values: <name>
Default: none
设置用于客户端-服务器交互的字符集 ( "SET NAMES <value>"
)。如果设置了多个字符集(用逗号分隔),如果设置字符集失败,则使用以下字符集。例如,这可以支持utf8mb4
(在 MySQL 5.5.3 中引入)并回退到utf8
旧服务器 ( charset=utf8mb4,utf8
)。
charset
不鼓励使用该参数,因为它会向服务器发出额外的查询。除非您需要回退行为,否则请collation
改用。
checkConnLiveness
Type: bool
Valid Values: true, false
Default: true
在支持的平台上,从连接池中检索的连接在使用前会被检查活跃度。如果检查失败,则相应的连接被标记为错误,并使用另一个连接重试查询。 checkConnLiveness=false
禁用此连接的活性检查。
collation
Type: string
Valid Values: <name>
Default: utf8mb4_general_ci
设置用于连接时客户端-服务器交互的排序规则。与 相比charset
,collation
不会发出额外的查询。如果指定的排序规则在目标服务器上不可用,则连接将失败。
可使用 检索服务器的有效字符集列表SHOW COLLATION
。
utf8mb4_general_ci
MySQL 5.5 支持默认排序规则 ( )。utf8_general_ci
对于较旧的 MySQL,您应该使用较旧的排序规则(例如)。
不能使用字符集“ucs2”、“utf16”、“utf16le”和“utf32”的排序规则(ref)。
clientFoundRows
Type: bool
Valid Values: true, false
Default: false
clientFoundRows=true
导致 UPDATE 返回匹配行数而不是更改的行数。
columnsWithAlias
Type: bool
Valid Values: true, false
Default: false
当columnsWithAlias
为真时,调用sql.Rows.Columns()
将返回表别名和用点分隔的列名。例如:
SELECT u.id FROM users as u
将返回u.id
而不仅仅是id
if columnsWithAlias=true
。
interpolateParams
Type: bool
Valid Values: true, false
Default: false
如果interpolateParams
为 true,则?
调用db.Query()
和db.Exec()
中的占位符 ( )将插入到具有给定参数的单个查询字符串中。这减少了往返次数,因为驱动程序必须准备一个语句,使用给定的参数执行它并再次使用interpolateParams=false
.
这不能与多字节编码 BIG5、CP932、GB2312、GBK 或 SJIS 一起使用。这些被拒绝,因为它们可能会引入 SQL 注入漏洞!
loc
Type: string
Valid Values: <escaped name>
Default: UTC
设置 time.Time 值的位置(使用 时parseTime=true
)。“本地”设置系统的位置。有关详细信息,请参阅time.LoadLocation。
请注意,这会设置 time.Time 值的位置,但不会更改 MySQL 的time_zone 设置。为此,请参阅time_zone 系统变量,它也可以设置为 DSN 参数。
请记住,参数值必须是url.QueryEscape 'ed。另外,您可以手动替换/
用%2F
。例如US/Pacific
将是loc=US%2FPacific
.
maxAllowedPacket
Type: decimal number
Default: 4194304
允许的最大数据包大小(以字节为单位)。默认值为 4 MiB,应进行调整以匹配服务器设置。maxAllowedPacket=0
可用于在每个连接上自动max_allowed_packet
从服务器获取变量。
multiStatements
Type: bool
Valid Values: true, false
Default: false
允许在一个查询中使用多个语句。虽然这允许批量查询,但也大大增加了 SQL 注入的风险。只返回第一个查询的结果,所有其他结果都被静默丢弃。
当multiStatements
使用时,?
参数必须仅在第一个语句中使用。
parseTime
Type: bool
Valid Values: true, false
Default: false
parseTime=true
改变的输出类型DATE
和DATETIME
值,以time.Time
代替[]byte
/string
日期或日期时间等0000-00-00 00:00:00
被转换成零值time.Time
。
readTimeout
Type: duration
Default: 0
I/O 读取超时。该值必须是带有单位后缀("ms"、"s"、"m"、"h")的十进制数,例如"30s"、"0.5m"或"1m30s"。
rejectReadOnly
Type: bool
Valid Values: true, false
Default: false
rejectReadOnly=true
导致驱动程序拒绝只读连接。这是针对自动故障转移期间可能出现的竞争条件,其中 mysql 客户端在故障转移后连接到只读副本。
请注意,这应该是一种相当罕见的情况,因为自动故障转移通常在主服务器关闭时发生,并且竞争条件不应该发生,除非它在故障转移开始后立即恢复联机。另一方面,当发生这种情况时,MySQL 应用程序可能会卡在只读连接上,直到重新启动。然而,重现相当容易,例如,在 AWS Aurora 的 MySQL 兼容集群上使用手动故障转移。
如果您不依赖只读事务来拒绝不应该发生的写入,则在某些 MySQL 提供程序(例如 AWS Aurora)上设置此选项对于故障转移更安全。
请注意,可以为read-only
服务器返回 ERROR 1290 ,此选项将导致对该错误进行重试。然而,相同的错误编号用于其他一些情况。read-only
在启用此选项时,您应该确保您的应用程序永远不会导致 ERROR 1290,除了mode。
serverPubKey
Type: string
Valid Values: <name>
Default: none
服务器公钥可以用 注册mysql.RegisterServerPubKey
,然后可以由 DSN 中指定的名称使用。公钥用于传输加密数据,例如用于身份验证。如果服务器的公钥是已知的,则应手动设置它以避免每次需要时将公钥从服务器传输到客户端的昂贵且可能不安全的传输。
timeout
Type: duration
Default: OS default
建立连接超时,又名拨号超时。该值必须是带有单位后缀("ms"、"s"、"m"、"h")的十进制数,例如"30s"、"0.5m"或"1m30s"。
tls
Type: bool / string
Valid Values: true, false, skip-verify, preferred, <name>
Default: false
tls=true
启用与服务器的 TLS / SSL 加密连接。使用skip-verify
,如果你想使用自签名或无效证书(服务器端)或使用preferred
只有当服务器发布到使用TLS。这类似于skip-verify
,但另外允许回退到未加密的连接。既不skip-verify
也不preferred
添加任何可靠的安全性。使用 .tls 注册后,您可以使用自定义 TLS 配置mysql.RegisterTLSConfig
。
writeTimeout
Type: duration
Default: 0
I/O 写入超时。该值必须是带有单位后缀("ms"、"s"、"m"、"h")的十进制数,例如"30s"、"0.5m"或"1m30s"。
系统变量
任何其他参数都被解释为系统变量:
<boolean_var>=<value>
:SET <boolean_var>=<value>
<enum_var>=<value>
:SET <enum_var>=<value>
<string_var>=%27<value>%27
:SET <string_var>='<value>'
规则:
- 字符串变量的值必须用 引用
'
。 - 这些值也必须是 url.QueryEscape 'ed!(这意味着字符串变量的值必须用 包裹
%27
)。
例子:
autocommit=1
:SET autocommit=1
time_zone=%27Europe%2FParis%27
:SET time_zone='Europe/Paris'
transaction_isolation=%27REPEATABLE-READ%27
:SET transaction_isolation='REPEATABLE-READ'
例子
user@unix(/path/to/socket)/dbname
root:pw@unix(/tmp/mysql.sock)/myDatabase?loc=Local
user:password@tcp(localhost:5555)/dbname?tls=skip-verify&autocommit=true
通过设置系统变量将警告视为错误sql_mode
:
user:password@/dbname?sql_mode=TRADITIONAL
通过 IPv6 的 TCP:
user:password@tcp([de:ad:be:ef::ca:fe]:80)/dbname?timeout=90s&collation=utf8mb4_unicode_ci
远程主机上的 TCP,例如 Amazon RDS:
id:password@tcp(your-amazonaws-uri.com:3306)/dbname
App Engine 上的 Google Cloud SQL:
user:password@unix(/cloudsql/project-id:region-name:instance-name)/dbname
TCP 使用本地主机上的默认端口 (3306):
user:password@tcp/dbname?charset=utf8mb4,utf8&sys_var=esc%40ped
使用默认协议 (tcp) 和主机 (localhost:3306):
user:password@/dbname
未预选数据库:
user:password@/
连接池和超时
连接池由 Go 的 database/sql 包管理。有关如何配置池的大小和连接多久细节留在游泳池看到*DB.SetMaxOpenConns
,*DB.SetMaxIdleConns
和*DB.SetConnMaxLifetime
将在 数据库/ SQL文档。读,写,和拨号为每个单独的连接超时被配置成与DSN参数readTimeout
,writeTimeout
以及timeout
分别。
ColumnType
支持
此驱动程序支持Go 1.8 中引入的ColumnType
接口ColumnType.Length()
,但目前不支持的 。所有未签名的数据库类型名称将返回UNSIGNED
带有INT
, TINYINT
, SMALLINT
, BIGINT
。
context.Context
支持
Go 1.8 添加了database/sql
对context.Context
. 此驱动程序通过上下文支持查询超时和取消。有关更多详细信息,请参阅database/sql 包中的上下文支持。
LOAD DATA LOCAL INFILE
支持
对于此功能,您需要直接访问包。因此,您必须更改导入路径(否_
):
import "github.com/go-sql-driver/mysql"
文件必须通过注册mysql.RegisterLocalFile(filepath)
(推荐)明确允许,或者必须使用 DSN 参数停用许可名单检查allowAllFiles=true
(可能不安全!)。
要使用io.Reader
处理程序函数,必须注册mysql.RegisterReaderHandler(name, handler)
其返回 aio.Reader
或io.ReadCloser
。然后,Reader 可与文件路径一起使用Reader::<name>
。为不同的处理程序以及DeregisterReaderHandler
当您不再需要它时选择不同的名称。
有关详细信息,请参阅 Go-MySQL-Driver 的 godoc。
time.Time
支持
MySQLDATE
和DATETIME
值的默认内部输出类型是[]byte
允许您将值扫描到程序中的[]byte
,string
或sql.RawBytes
变量中。
但是,许多人希望将 MySQLDATE
和DATETIME
值扫描到time.Time
变量中,这在 Go toDATE
和DATETIME
MySQL 中是逻辑等价的。您可以通过使用 DSN 参数将内部输出类型从 更改为[]byte
来实现。您可以使用DSN 参数设置默认位置。time.Time
parseTime=true
time.Time
loc
注意:从 Go 1.1 开始,这成为time.Time
唯一可以扫描DATE
和DATETIME
取值的变量类型。例如,这会中断sql.RawBytes
支持。
Unicode 支持
从 1.5 版开始,Go-MySQL-Driver utf8mb4_general_ci
默认自动使用排序规则。
可以使用collation
DSN 参数设置其他排序规则/字符集。
驱动程序的 1.0 版建议将 &charset=utf8
(别名为 SET NAMES utf8
)添加到 DSN 以启用正确的 UTF-8 支持。这不再是必要的了。该collation
参数应该优先于设置另一个排序规则/字符集而不是默认值。
有关 MySQL 的 Unicode 支持的更多详细信息,请参阅 http://dev.mysql.com/doc/refman/8.0/en/charset-unicode.html。
如果你对这篇内容有疑问,欢迎到本站社区发帖提问 参与讨论,获取更多帮助,或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱,如果其他用户或者作者回复了您的评论,将不能在第一时间通知您!
- 特征
- 要求
- 安装
- 用法
- 重要设置
- DSN(数据源名称)
- 密码
- 协议
- 地址
- 参数
- allowAllFiles
- allowCleartextPasswords
- allowNativePasswords
- allowOldPasswords
- charset
- checkConnLiveness
- collation
- clientFoundRows
- columnsWithAlias
- interpolateParams
- loc
- maxAllowedPacket
- multiStatements
- parseTime
- readTimeout
- rejectReadOnly
- serverPubKey
- timeout
- tls
- writeTimeout
- 系统变量
- 例子
- 连接池和超时
- ColumnType 支持
- context.Context 支持
- LOAD DATA LOCAL INFILE 支持
- time.Time 支持
- Unicode 支持
发布评论