Go中mysql驱动的DSN解析

DSN

数据源名称具有通用格式，例如PEAR DB使用它，但没有类型前缀（可选部分用方括号标记）：

1

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

DSN最完整的形式：

1

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

除databasename外，所有值都是可选的。所以最小的DSN是：

1

/dbname

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

1

/

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

或者，Config.FormatDSN可用于通过填充结构来创建DSN字符串。

Password

Password可以包含任何字符。逃避是没有必要的。

Protocol

有关哪些网络可用的详细信息，请参见net.Dial。通常，如果可用，则应使用Unix域套接字，否则应使用TCP以获得最佳性能。

net.Dial

1

func Dial(network, address string) (Conn, error)

Dial连接到指定网络上的地址。

已知网络是“tcp”，“tcp4”（仅限IPv4），“tcp6”（仅限IPv6），“udp”，“udp4”（仅限IPv4），“udp6”（仅限IPv6），“ip” ，“ip4”（仅限IPv4），“ip6”（仅限IPv6），“unix”，“unixgram”和“unixpacket”。

对于TCP和UDP网络，地址的格式为“host：port”。主机必须是文字IP地址或可以解析为IP地址的主机名。端口必须是文字端口号或服务名称。如果主机是文字IPv6地址，则必须用方括号括起来，如“[2001：db8 :: 1]：80”或“[fe80 :: 1％zone]：80”。该区域指定RFC 4007中定义的文字IPv6地址的范围。函数JoinHostPort和SplitHostPort以此形式操作一对主机和端口。当使用TCP，并且主机解析为多个IP地址时，Dial将按顺序尝试每个IP地址，直到成功为止。

例子：

1
2
3
4
5
6


Dial("tcp", "golang.org:http")
Dial("tcp", "192.0.2.1:http")
Dial("tcp", "198.51.100.1:80")
Dial("udp", "[2001:db8::1]:domain")
Dial("udp", "[fe80::1%lo0]:53")
Dial("tcp", ":80")

对于IP网络，网络必须是“ip”，“ip4”或“ip6”，后跟冒号和文字协议号或协议名称，地址的格式为“host”。主机必须是文字IP地址或带区域的文字IPv6地址。它取决于每个操作系统操作系统如何使用非众所周知的协议号（例如“0”或“255”）进行操作。

例子：

1
2
3


Dial("ip4:1", "192.0.2.1")
Dial("ip6:ipv6-icmp", "2001:db8::1")
Dial("ip6:58", "fe80::1%lo0")

对于TCP，UDP和IP网络，如果主机为空或文本未指定的IP地址，如“：80”，“0.0.0.0:80”或“[::]：80”表示TCP和UDP，“” ，“0.0.0.0”或“::”对于IP，假设本地系统。

对于Unix网络，地址必须是文件系统路径。

Address

对于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

1
2
3


Type:           bool
Valid Values:   true, false
Default:        false

allowAllFiles=true 禁用文件白名单LOAD DATA LOCAL INFILE并允许所有文件。可能不安全！

allowCleartextPasswords

1
2
3


Type:           bool
Valid Values:   true, false
Default:        false

allowCleartextPasswords=true允许在帐户需要时使用明文客户端插件，例如使用PAM身份验证插件定义的插件。在某些配置中，以明文形式发送密码可能是安全问题。如果有可能截获密码以避免出现问题，客户端应使用保护密码的方法连接到MySQL Server。可能性包括TLS / SSL，IPsec或专用网络。

allowNativePasswords

1
2
3


Type:           bool
Valid Values:   true, false
Default:        true

allowNativePasswords=false 不允许使用MySQL本机密码方法。

allowOldPasswords

1
2
3


Type:           bool
Valid Values:   true, false
Default:        false

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

charset

1
2
3


Type:           string
Valid Values:   <name>
Default:        none

设置用于客户端 - 服务器交互的charset（“SET NAMES "）。如果设置了多个字符集（用逗号分隔），则在设置charset failes时使用以下字符集。这使得例如支持utf8mb4（在MySQL 5.5.3中引入）utf8支持旧服务器（charset=utf8mb4,utf8）的回退。

charset不鼓励使用该参数，因为它会向服务器发出其他查询。除非您需要回退行为，否则请collation改用。

collation

1
2
3


Type:           string
Valid Values:   <name>
Default:        utf8mb4_general_ci

设置用于连接上的客户端 - 服务器交互的排序规则。与charset相反，collation不会发出其他查询。如果目标服务器上的指定排序规则不可用，则连接将失败。

可以检索服务器的有效字符集列表SHOW COLLATION。

utf8mb4_general_ciMySQL 5.5支持默认的collation（）。utf8_general_ci对于较旧的MySQL，您应该使用较旧的排序规则（例如）。

不能使用字符集“ucs2”，“utf16”，“utf16le”和“utf32”的排序规则（参考号）。

clientFoundRows

1
2
3


Type:           bool
Valid Values:   true, false
Default:        false

clientFoundRows=true 导致UPDATE返回匹配的行数而不是更改的行数。

columnsWithAlias

1
2
3


Type:           bool
Valid Values:   true, false
Default:        false

如果columnsWithAlias为true，则调用sql.Rows.Columns()将返回表别名和以点分隔的列名。例如：

1

SELECT u.id FROM users as u

如果columnsWithAlias=true,将返回u.id，而不是只是id。

interpolateParams

1
2
3


Type:           bool
Valid Values:   true, false
Default:        false

如果interpolateParams为true，则占位符（?）调用db.Query()并db.Exec()插入到具有给定参数的单个查询字符串中。这减少了往返次数，因为如果使用interpolateParams=false,驱动程序必须准备一个语句，用给定的参数执行它并再次关闭语句。

这不能与多字节编码BIG5，CP932，GB2312，GBK或SJIS一起使用。这些被列入黑名单，因为它们可能会引入SQL注入漏洞！

loc

1
2
3


Type:           string
Valid Values:   <escaped name>
Default:        UTC

设置time.Time值的位置（使用时parseTime=true）。“Local”设置系统的位置。有关详细信息，请参阅time.LoadLocation。

请注意，这会设置time.Time值的位置，但不会更改MySQL的time_zone设置。为此，请参阅time_zone系统变量，该变量也可以设置为DSN参数。

请记住，param值必须是url.QueryEscape’ed。或者，您可以手动替换/使用%2F。例如US/Pacific会loc=US%2FPacific。

func QueryEscape

1

func QueryEscape(s string) string

QueryEscape转义字符串，以便可以安全地放在URL查询中。

func LoadLocation

1

func LoadLocation(name string) (*Location, error)

LoadLocation返回具有给定名称的Location。

如果名称为“”或“UTC”，则LoadLocation返回UTC。如果名称为“Local”，则LoadLocation返回Local。

否则，该名称将被视为与IANA时区数据库中的文件相对应的位置名称，例如“America / New_York”。

LoadLocation所需的时区数据库可能不存在于所有系统上，尤其是非Unix系统。LoadLocation查找由ZONEINFO环境变量命名的目录或未压缩的zip文件（如果有），然后查看Unix系统上的已知安装位置，最后查找$ GOROOT / lib / time / zoneinfo.zip。

maxAllowedPacket

1
2


Type:          decimal number
Default:       4194304

允许的最大包大小以字节为单位默认值为4 MiB，应调整以匹配服务器设置。maxAllowedPacket=0可用于在每个连接上自动max_allowed_packet从服务器获取变量。

multiStatements

1
2
3


Type:           bool
Valid Values:   true, false
Default:        false

在一个查询中允许多个语句。虽然这允许批量查询，但它也大大增加了SQL注入的风险。仅返回第一个查询的结果，所有其他结果将被静默丢弃。

当multiStatements使用时，?参数必须仅在第一个语句中使用。

parseTime

1
2
3


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

1
2


Type:           duration
Default:        0

I / O读取超时。该值必须是带有单位后缀（“ms”，“s”，“m”，“h”）的十进制数，例如“30s”，“0.5m”或“1m30s”。

rejectReadOnly

1
2
3


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 。

serverPubKey

1
2
3


Type:           string
Valid Values:   <name>
Default:        none

可以注册服务器公钥mysql.RegisterServerPubKey，然后可以由DSN中指定的名称使用。公钥用于传输加密数据，例如用于认证。如果服务器的公钥是已知的，则应手动设置它，以避免每次需要时将公钥从服务器传输到客户端的昂贵且可能不安全。

timeout

1
2


Type:           duration
Default:        OS default

建立连接超时，即拨号超时。该值必须是带有单位后缀（“ms”，“s”，“m”，“h”）的十进制数，例如“30s”，“0.5m”或“1m30s”。

tls

1
2
3


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配置mysql.RegisterTLSConfig。

writeTimeout

1
2


Type:           duration
Default:        0

I / O写超时。该值必须是带有单位后缀（“ms”，“s”，“m”，“h”）的十进制数，例如“30s”，“0.5m”或“1m30s”。

系统变量

任何其他参数都被解释为系统变量：

1
2
3


<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）。

例子：

1
2
3


autocommit=1： SET autocommit=1
time_zone=%27Europe%2FParis%27： SET time_zone='Europe/Paris'
tx_isolation=%27REPEATABLE-READ%27： SET tx_isolation='REPEATABLE-READ'

例子

1
2
3


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：

1

user:password@/dbname?sql_mode=TRADITIONAL

TCP通过IPv6：

1

user:password@tcp([de:ad:be:ef::ca:fe]:80)/dbname?timeout=90s&collation=utf8mb4_unicode_ci

远程主机上的TCP，例如Amazon RDS：

1

id:password@tcp(your-amazonaws-uri.com:3306)/dbname

App Engine上的Google Cloud SQL（第一代MySQL服务器）：

1

user@cloudsql(project-id:instance-name)/dbname

App Engine上的Google Cloud SQL（第二代MySQL服务器）：

1

user@cloudsql(project-id:regionname:instance-name)/dbname

TCP使用localhost上的默认端口（3306）：

1

user:password@tcp/dbname?charset=utf8mb4,utf8&sys_var=esc%40ped

使用默认协议（tcp）和主机（localhost：3306）：

1

user:password@/dbname

没有预选数据库：

1

user:password@/

文章目录

DSN