本文翻译自https://github.com/go-sql-driver/mysql/
Go-MySQL-Driver 用于Go语言database/sql
特性 
要求 
安装 
用法 
       DSN(Data Source Name,数据源名称) 
              密码 
              协议 
              地址 
              参数 
              实例 
       连接池和超时 
       支持context.Context 
       支持ColumnType 
       支持LOAD DATA LOCAL INFILE 
       支持time.Time 
       支持Unicode 
测试/开发 
License 
特性 
轻量又快速  纯Go语言实现,并非是对C语言的封装 通过TCP/IPv4、TCP/IPv6、Unix域套接字或自定义协议 进行连接 自动处理断开的连接 自动连接池(通过database/sql包) 支持大于16MB的查询字符串 完整的sql.RawBytes 智能地处理预处理语句中的LONG DATA 通过文件白名单安全地支持LOAD DATA LOCAL INFILE,也支持io.Reader 可选的time.Time解析 可选的占位符插值 要求 
Go 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驱动是Go的database/sql/driver包的接口的实现。你只需要导入这个驱动,然后就可以使用完整的database/sql
使用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)
}
// 参见“重要设置”小节。
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()函数来设置。
DSN(Data Source Name,数据源名称) 
数据源名称具有一个通用格式,例如PEAR DB 所使用的,但没有类型前缀(用方括号标记可选部分):
[username[:password]@][protocol[(address)]]/dbname[?param1=value1&...¶mN=valueN]完整形式的DSN:
username:password@protocol(address)/dbname?param=value除了数据库名称之外,所有值都是可选的。因此,最小DSN为:
/dbname如果不想预先选择一个数据库实例,请将dbname保留为空:
/这与空DSN字符串的效果相同。
或者,我们也可以使用Config.FormatDSN 通过填充一个结构体来创建DSN字符串。
密码 
密码可以由任何字符组成,无需转义。
协议 
有关可用网络的更多信息,请参阅net.Dial 。一般来说,如果可以,你应该使用Unix域套接字,否则应该使用TCP,以获得最佳性能。
地址 
对于TCP和UDP网络,地址的格式为host[:port]。如果省略port,将使用默认端口号。如果主机使用IPv6地址,则必须将其括在方括号中。函数net.JoinHostPort 和net.SplitHostPort 以这种形式处理地址。
对于Unix域套接字,地址是MySQL服务的套接字的绝对路径,例如:
/var/run/mysqld/mysqld.sock或
/tmp/mysql.sock参数 
参数区分大小写! 
请注意,true、TRUE、True或1中的任何一个表示布尔值“真”。毫不奇怪,布尔值“假”可以指定为以下任意值:false、FALSE、False或0。
allowAllFiles
Type:           bool
Valid Values:   true, false
Default:        falseallowAllFiles=true禁用LOAD DATA LOCAL INFILE的文件白名单,并允许所有文件。可能不安全 !
allowCleartextPasswords
Type:           bool
Valid Values:   true, false
Default:        falseallowCleartextPasswords=true在帐户需要时允许使用明文(cleartext)客户端插件 ,例如使用PAM身份验证插件 定义的插件。以明文形式发送密码在某些配置中可能是一个安全问题。如果密码有可能被拦截,为避免出现问题,客户端应使用保护密码的方法连接到MySQL服务器,包括使用TLS/SSL 、IPsec或专用网络。
allowFallbackToPlaintext
Type:           bool
Valid Values:   true, false
Default:        falseallowFallbackToPlaintext=true的作用类似于使用--ssl-mode=PREFERRED选项的MySQL客户端,如用于连接到服务器的命令选项 中所述
allowNativePasswords
Type:           bool
Valid Values:   true, false
Default:        trueallowNativePasswords=false禁止使用MySQL本机密码(native password)方式。
allowOldPasswords
Type:           bool
Valid Values:   true, false
Default:        falseallowOldPasswords=true允许使用不安全的旧密码(old password)方式。应该避免使用这种方式,但在某些情况下是必要的。另请参阅old_passwords维基页面 。
charset
Type:           string
Valid Values:   <name>
Default:        none设置用于客户端-服务器交互的字符集(“SET NAMES <value>“)。如果设置了多个字符集(用逗号分隔),则在设置当前字符集失败时继续尝试设置后续的字符集。例如, (charset=utf8mb4,utf8)设置utf8mb4(在MySQL 5.5.3中引入),如果是旧服务器就回退到utf8。
不鼓励使用charset参数,因为它会向服务器发出额外的查询。除非你需要回退行为,否则请改用collation参数。
checkConnLiveness
Type:           bool
Valid Values:   true, false
Default:        true在支持的平台上,Go从连接池中检索连接,在使用该连接之前会检查其是否活动。如果不活动,则将相应的连接标记为坏连接,并尝试使用另一个连接。checkConnLiveness=false不检查连接是否活动。
collation
Type:           string
Valid Values:   <name>
Default:        utf8mb4_general_ci设置连接时用于客户端-服务器交互的字符排序规则。与charset不同,collation不会发出额外的查询。如果指定的排序规则在目标服务器上不可用,则连接将失败。
可以使用SHOW COLLATION检索服务器的有效字符集列表。
MySQL 5.5支持默认排序规则(utf8mb4_general_ci)。对于较旧的MySQL,应该使用较旧的排序规则(例如utf8_general_ci)。 不能使用字符集”ucs2″、”utf16″、”utf16le”和”utf32″的排序规则(参考 )。
clientFoundRows
Type:           bool
Valid Values:   true, false
Default:        falseclientFoundRows=true会导致UPDATE语句返回匹配的行数,而不是更改的行数。
columnsWithAlias
Type:           bool
Valid Values:   true, false
Default:        false当columnsWithAlias=true时,调用sql.Rows.Columns()将返回表别名和用点分隔的列名。例如:
SELECT u.id FROM users as u如果columnsWithAlias=true,将返回u.id而不仅仅是id。
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时)。如果时区设置为Local,那么设置为系统的时区。有关详细信息,请参阅time.LoadLocation
注意,这将设置time.time值的时区,但不会更改MySQL的time_zone设置 。为此,请参见time_zone系统变量 ,该变量也可以设置为DSN的参数。
请记住,参数值必须是url.QueryEscape/替换为%2F。例如,US/Pacific(美国/太平洋时区)应该被设置为loc=US%2FPacific。
maxAllowedPacket
Type:          decimal number
Default:       4194304允许的最大数据包的大小(以字节为单位)。默认值为4MiB,应进行调整以匹配服务器设置。maxAllowedPacket=0可用于在每次连接时 从服务器自动获取max_allowed_packet变量。
multiStatements
Type:           bool
Valid Values:   true, false
Default:        false是否允许在一个查询中使用多条语句。虽然这允许批量查询,但也大大增加了被SQL注入的风险。只返回第一个查询语句的结果,所有其他结果都被默默丢弃。当使用multiStatements时,?参数只能在第一条语句中使用。
parseTime
Type:           bool
Valid Values:   true, false
Default:        falseparseTime=true将DATE和DATETIME值的输出类型更改为time.Time,而不是[]byte/string类型的日期或日期时间,例如0000-00-00 00:00:00将转换为time.Time的零值。
readTimeout
Type:           duration
Default:        0I/O读取的超时时间。该值必须是带有单位后缀的十进制数字(”ms”、”s”、”m”、”h”),例如”30s”、”0.5m”或”1m30s”。
rejectReadOnly
Type:           bool
Valid Values:   true, false
Default:        falserejectReadOnly=true会导致数据库驱动程序拒绝只读连接。这是针对自动故障切换期间可能出现的争用(race condition)情况,即故障切换后mysql客户端将连接到某个只读副本。
请注意,这应该是一种相当罕见的情况,因为自动故障转移通常发生在主服务器关闭时,并且竞态条件(race condition)不会发生,除非它在故障转移开始后立即恢复在线。另一方面,发生这种情况时,MySQL应用程序可能会卡在只读连接上,直到重新启动。然而,这种故障相当容易复现,例如在AWS Aurora的MySQL兼容集群上手动造成故障转移。
如果你不依赖只读事务来拒绝不应该发生的写入操作,那么在某些MySQL服务提供商(例如AWS Aurora)上设置此选项,对于故障切换来说更安全。
请注意,read-only服务器可能会返回1290号错误,此选项将导致重试该错误。但是,存在其他一些情况,也使用相同的1290错误号。因此启用此选项时,应确保应用程序在read-only模式之外,都不会导致1290号错误。
serverPubKey
Type:           string
Valid Values:   <name>
Default:        none可以使用mysql.RegisterServerPubKey
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:        falsetls=true启用与服务器的TLS/SSL加密连接。如果要使用自签名或无效证书(服务器端),那么使用skip-verify参数;或通过preferred参数使用TLS(仅当得到服务器端建议时),这类似于skip-verify,但还允许回退到未加密的连接。skip-verify和preferred都不添加任何可靠的安全性。你可以在向mysql.RegisterTLSConfig
writeTimeout
Type:           duration
Default:        0I/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>'规则:
例如:
autocommit=1: SET autocommit=1time_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应用引擎上的谷歌云SQL:
user:password@unix(/cloudsql/project-id:region-name:instance-name)/dbname使用本地主机上默认端口(3306)的TCP:
user:password@tcp/dbname?charset=utf8mb4,utf8&sys_var=esc%40ped使用默认协议(tcp)和主机(localhost:3306):
user:password@/dbname未预先选择数据库:
user:password@/连接池和超时 
连接池由Go的database/sql包管理。有关如何配置池的大小以及连接在池中停留的时间的详细信息,请参阅database/sql文档*DB.SetMaxOpenConns、*DB.Set MaxIdleConns和*DB.Set-ConnMaxLifetime。每个单独连接的读取、写入和拨号超时分别使用DSN参数readTimeout 、writeTimeout 和timeout 进行配置。
支持context.Context 
此驱动程序支持Go 1.8中引入的ColumnType接口ColumnType.Length()Unsigned的INT、TINYINT、SMALLINT或BIGINT名称。
支持ColumnType 
此驱动程序支持Go 1.8中引入的ColumnType接口ColumnType.Length()Unsigned的INT、TINYINT、SMALLINT或BIGINT名称。
支持context.Context 
在Go 1.8,database/sql包添加了对context.Context的支持。此驱动程序支持查询超时和通过context取消语句的执行。有关详细信息,请参阅database/sql包中的context支持
支持LOAD DATA LOCAL INFILE 
对于此功能,你需要直接访问软件包。因此,你必须更改导入路径(无_):
import "github.com/go-sql-driver/mysql"文件必须通过mysql.RegisterLocalFile(filepath)注册来明确允许加载里面的数据(推荐使用这种做法),或者必须通过使用DSN参数allowAllFiles=true来禁用allowlist检查(这种做法可能不安全 !)。
要使用io.Reader,必须使用mysql.RegisterReaderHandler(name, handler)注册处理函数,该函数返回io.Reador或io.ReadCloser。然后,Reader可以使用文件路径Reader::<name>。可以为不同的处理程序 handler注册不同的名字name,,当你不再需要它时,使用DeregisterReaderHandler反注册。
有关详细信息,请参阅Go MySQL驱动程序的godoc 。
支持time.Time 
MySQL DATE和DATETIME值的默认内部输出类型为[]byte,这允许你将值扫描到程序中的[]byte、string或sql.RawBytes变量中。
然而,许多人希望将MySQL的DATE和DATETIME值扫描到Go语言的time.Time变量中,这在逻辑上等同于MySQL中的DATE和DATETIME值。你可以通过使用DSN参数parseTime=true将内部输出类型从[]byte更改为time.Time。你可以使用DSN参数loc设置默认time.Time的时区位置
注意 :截至Go 1.1,这使得time.Time成为唯一可以扫描DATE和DATETIME值的变量类型。这会破坏例如对sql.RawBytes的支持 。
支持Unicode 
由于1.5版本的Go MySQL驱动程序默认情况下自动使用排序规则utf8mb4_general_ci。
可以使用DSN参数collation
1.0版的驱动程序建议将&charset=utf8(即MySQL命令SET NAMES utf8的别名)添加到DSN中,以启用正确的UTF-8支持。但现在已经没有必要这么做了,如果要设置其他排序规则/字符集的话,应该首选collation
有关MySQL的Unicode支持的更多详细信息参见http://dev.mysql.com/doc/refman/8.0/en/charset-unicode.html。
测试/开发 
要运行驱动程序测试,你可能需要调整配置。有关详细信息,请参阅测试的Wiki 页面 。
Go语言的MySQL驱动程序的功能还不完善。如果你想做出贡献,我们将非常感谢你的帮助,你可以处理未解决的问题 或查看拉取请求 。
有关详细信息,请参阅贡献指南 。
License 
Go语言的MySQL驱动程序在Mozilla公共许可证2.0版(Mozilla Public License Version 2.0) 下获得许可。
Mozilla将许可范围总结如下:
MPL :许可证适用于任何包含 MPL 代码的文件 。
这意味着:
你可以在私人和商业用途中使用未更改的 源代码。 分发时,你必须 根据a) MPL 2.0本身或b)兼容的许可证(例如GPL 3.0或Apache License 2.0)发布MPL 2.0许可的任何更改了源代码的文件 。 只要根据MPL 2.0许可的文件未更改 ,你就无需发布 你的库的源代码。 如果你对许可证有更多疑问,请阅读MPL 2.0的常见问题解答 。
你可以在此处阅读完整条款:LICENSE 。