查看“使用类似URI的字符串或键值对连接到服务器”的源代码

本节介绍了如何使用类似URI的连接字符串或键值对来指定如何建立与MySQL服务器的连接，适用于MySQL Shell等客户端。

 注意
 术语“类似URI”表示连接字符串语法与RFC 3986定义的URI（统一资源标识符）语法类似但不完全相同。

以下MySQL客户端支持使用类似URI的连接字符串或键值对连接到MySQL服务器：

*MySQL Shell
*实现X DevAPI的MySQL Connectors

本节记录了所有有效的类似URI字符串和键值对连接参数，其中许多参数与命令行选项中指定的参数类似：

*使用类似URI的字符串指定的参数使用myuser@example.com:3306/main-schema等语法，用于完整的语法，请参阅使用类似URI的连接字符串。
*使用键值对指定的参数使用{user:'myuser', host:'example.com', port:3306, schema:'main-schema'}等语法，用于完整的语法，请参阅使用键值对进行连接。

连接参数不区分大小写。每个参数（如果指定）只能给出一次。如果一个参数被指定多次，将会出错。


==基本连接参数==
以下讨论描述了在指定与MySQL的连接时可用的参数。这些参数可以使用符合基本类似URI语法的字符串（请参阅使用类似URI的连接字符串）或键值对（请参阅使用键值对进行连接）来提供。

*scheme：要使用的传输协议。对于X协议连接，请使用mysqlx，对于经典MySQL协议连接，请使用mysql。如果未指定协议，则服务器尝试猜测协议。支持DNS SRV的连接器可以使用mysqlx+srv方案（请参阅使用DNS SRV记录进行连接）。

*user：用于身份验证过程的MySQL用户帐户。

*password：用于身份验证过程的密码。

 警告
 在连接规范中指定明确的密码是不安全且不推荐的。稍后的讨论将显示如何导致出现交互式提示输入密码。

*host：服务器实例运行的主机。值可以是主机名、IPv4地址或IPv6地址。如果未指定主机，则默认为localhost。

*port：目标MySQL服务器侦听连接的TCP/IP网络端口。如果未指定端口，则X协议连接的默认值为33060，经典MySQL协议连接的默认值为3306。

*socket：Unix套接字文件的路径或Windows命名管道的名称。值是本地文件路径。在类似URI的字符串中，它们必须进行编码，使用百分比编码或使用括号将路径括起来。括号可以省略对字符进行百分比编码，例如/目录分隔符字符。例如，要使用Unix套接字/tmp/mysql.sock连接为root@localhost，请使用百分比编码指定路径为root@localhost?socket=%2Ftmp%2Fmysql.sock，或者使用括号指定路径为root@localhost?socket=(/tmp/mysql.sock)。

*schema：连接的默认数据库。如果未指定数据库，则连接没有默认数据库。

在Unix上处理localhost取决于传输协议的类型。使用经典MySQL协议进行连接的本地主机的处理方式与其他MySQL客户端相同，这意味着localhost被假定为基于套接字的连接。对于使用X协议的连接，localhost的行为不同，它被假定为表示回环地址，例如IPv4地址127.0.0.1。


==附加连接参数==
您可以通过在类似URI的字符串中附加?attribute=value的属性，或者使用键值对指定连接的选项。以下选项可用：

*ssl-mode：连接的所需安全状态。以下模式是可接受的：
**DISABLED
**PREFERRED
**REQUIRED
**VERIFY_CA
**VERIFY_IDENTITY

 重要
 VERIFY_CA和VERIFY_IDENTITY比默认的PREFERRED更好，因为它们有助于防止中间人攻击。
 
 有关这些模式的信息，请参阅加密连接的--ssl-mode选项描述。

*ssl-ca：PEM格式的X.509证书颁发机构文件的路径。

*ssl-capath：包含PEM格式的X.509证书颁发机构文件的目录的路径。

*ssl-cert：PEM格式的X.509证书文件的路径。

*ssl-cipher：用于使用TLS协议进行连接的加密密码。

*ssl-crl：包含PEM格式的证书吊销列表的文件的路径。

*ssl-crlpath：包含PEM格式的证书吊销列表文件的目录的路径。

*ssl-key：PEM格式的X.509密钥文件的路径。

*tls-version：经典MySQL协议加密连接允许的TLS协议。此选项仅受MySQL Shell支持。tls-version（单数）的值是逗号分隔的列表，例如TLSv1.2，TLSv1.3。

*tls-versions：用于加密X协议连接的允许的TLS协议。tls-versions（复数）的值是一个数组，例如[TLSv1.2，TLSv1.3]。此选项取决于ssl-mode选项未设置为DISABLED。

*tls-ciphersuites：允许的TLS密码套件。tls-ciphersuites的值是TLS密码套件的IANA密码套件名称列表，如TLS密码套件中所列。此选项取决于ssl-mode选项未设置为DISABLED。

*auth-method：用于连接的身份验证方法。默认值为AUTO，表示服务器尝试猜测。以下方法是可接受的：
**AUTO
**MYSQL41
**SHA256_MEMORY
**FROM_CAPABILITIES
**FALLBACK
**PLAIN

对于X协议连接，任何配置的auth-method都会被覆盖为以下身份验证方法序列：MYSQL41，SHA256_MEMORY，PLAIN。

*get-server-public-key：从服务器请求用于RSA基于密钥对的密码交换所需的公钥。在使用SSL模式DISABLED的经典MySQL协议连接MySQL 8.0服务器时使用。在这种情况下，您必须指定协议。例如：

 mysql://user@localhost:3306?get-server-public-key=true
此选项适用于使用caching_sha2_password身份验证插件进行身份验证的客户端。对于该插件，除非请求，否则服务器不会发送公钥。对于不使用该插件进行身份验证的帐户，该选项将被忽略。如果客户端使用安全连接连接到服务器，则也会忽略该选项。

如果给定server-public-key-path=file_name并指定有效的公钥文件，则它优先于get-server-public-key。


*server-public-key-path：以PEM格式包含服务器所需的基于RSA密钥对的密码交换的客户端端公钥的文件的路径名。在使用SSL模式DISABLED的经典MySQL协议连接MySQL 8.0服务器时使用。

此选项适用于使用sha256_password或caching_sha2_password身份验证插件进行身份验证的客户端。对于不使用这些插件进行身份验证的帐户，该选项将被忽略。如果客户端使用安全连接连接到服务器，则也会忽略该选项。

如果给定server-public-key-path=file_name并指定有效的公钥文件，则它优先于get-server-public-key。


*ssh: 通过SSH隧道连接到SSH服务器以访问MySQL服务器实例的连接URI。URI格式为[user@]host[:port]。使用uri选项指定目标MySQL服务器实例的URI。

*uri: 要通过ssh选项指定的服务器访问MySQL服务器实例的URI。URI格式为[scheme://][user@]host[:port]。不要使用基本连接参数（scheme，user，host，port）来指定用于SSH隧道的MySQL服务器连接，只需使用uri选项。

*ssh-password: SSH服务器连接的密码。

 警告
 在连接规范中指定显式密码是不安全且不推荐的。当需要密码时，MySQL Shell会交互式地提示输入密码。

*ssh-config-file: SSH服务器连接的SSH配置文件。您可以使用MySQL Shell配置选项ssh.configFile将自定义文件设置为默认文件（如果未指定此选项）。如果未设置ssh.configFile，则默认为标准SSH配置文件〜/.ssh/config。

*ssh-identity-file: 用于连接到SSH服务器的身份文件。如果未指定此选项，则默认为在SSH代理中配置的任何身份文件（如果使用），或在SSH配置文件中，或在SSH配置文件夹（〜/.ssh/id_rsa）中的标准私钥文件。

*ssh-identity-pass: ssh-identity-file选项指定的身份文件的密码。

 警告
 在连接规范中指定显式密码是不安全且不推荐的。当需要密码时，MySQL Shell会交互式地提示输入密码。

*connect-timeout: 用于配置客户端（例如MySQL Shell）等待多少秒后停止尝试连接到无响应的MySQL服务器的整数值。

*compression: 此选项请求或禁用连接的压缩。在MySQL 8.0.19之前，它仅对经典的MySQL协议连接起作用，而从MySQL 8.0.20开始，它也适用于X协议连接。

在MySQL 8.0.19之前，此选项的值为true（或1），表示启用压缩，而默认值false（或0）表示禁用压缩。

从MySQL 8.0.20开始，此选项的值为required，表示请求压缩并在服务器不支持时失败；preferred，表示请求压缩并在无法压缩连接时回退到无压缩连接；以及disabled，表示请求无压缩连接并在服务器不允许时失败。preferred是X协议连接的默认值，disabled是经典的MySQL协议连接的默认值。

请注意，不同的MySQL客户端对连接压缩的支持实现不同。有关详细信息，请参阅客户端的文档。

*compression-algorithms和compression-level: 这些选项在MySQL Shell 8.0.20及更高版本中可用，用于更好地控制连接压缩。您可以指定它们来选择用于连接的压缩算法以及与该算法一起使用的数字压缩级别。您还可以使用compression-algorithms替代compression来请求连接压缩。

*connection-attributes: 控制应用程序在连接时传递给服务器的键值对。客户端通常定义一组默认属性，可以禁用或启用。例如：

 mysqlx://user@host?connection-attributes
 mysqlx://user@host?connection-attributes=true
 mysqlx://user@host?connection-attributes=false
默认行为是发送默认属性集。应用程序可以指定要在默认属性之外传递的属性。您可以将额外的连接属性指定为连接字符串中的connection-attributes参数。connection-attributes参数值必须为空（与指定true相同），是一个布尔值（true或false，以启用或禁用默认属性集），或者是一个由逗号分隔的零个或多个键=值指定符组成的列表（以发送除默认属性集之外的属性）。在列表中，缺少的键值将计算为空字符串。更多示例：

 mysqlx://user@host?connection-attributes=[attr1=val1,attr2,attr3=]
 mysqlx://user@host?connection-attributes=[]
应用程序定义的属性名称不能以_开头，因为这些名称保留给内部属性。


==使用类似URI的连接字符串进行连接==
您可以使用类似URI的字符串指定与MySQL服务器的连接。这样的字符串可以与MySQL Shell一起使用，使用--uri命令选项，MySQL Shell \connect命令和实现X DevAPI的MySQL连接器。

 注意
 术语“类似URI”表示与RFC 3986定义的URI（统一资源标识符）语法类似但不完全相同的连接字符串语法。

类似URI的连接字符串具有以下语法：

 [scheme://][user[:[password]]@]host[:port][/schema][?attribute1=value1&attribute2=value2...

 重要
 在URI类似字符串的元素中，必须使用百分号编码来保留字符。例如，如果您指定包含@字符的字符串，则必须将该字符替换为%40。如果在IPv6地址中包含区域ID，则用作分隔符的%字符必须替换为%25。

您可以在类似URI的连接字符串中使用的参数在基本连接参数中进行了描述。

MySQL Shell的shell.parseUri（）和shell.unparseUri（）方法可用于解构和组装类似URI的连接字符串。给定一个类似URI的连接字符串，shell.parseUri（）返回一个包含字符串中找到的每个元素的字典。shell.unparseUri（）将URI组件和连接选项的字典转换为用于连接到MySQL的有效类似URI的连接字符串，可以在MySQL Shell中使用，也可以由实现X DevAPI的MySQL连接器使用。

如果在类似URI的字符串中未指定密码（建议的做法），交互式客户端会提示输入密码。以下示例演示了如何使用用户名user_name指定类似URI的字符串。在每种情况下，都会提示输入密码。

*连接到本地服务器实例，侦听端口33065的X协议连接。

 mysqlx://user_name@localhost:33065
*连接到本地服务器实例，侦听端口3333的经典MySQL协议连接。

 mysql://user_name@localhost:3333
*通过使用主机名、IPv4地址和IPv6地址连接到远程服务器实例的X协议连接。

 mysqlx://user_name@server.example.com/
 mysqlx://user_name@198.51.100.14:123
 mysqlx://user_name@[2001:db8:85a3:8d3:1319:8a2e:370:7348]
*使用套接字进行的X协议连接，使用百分号编码或括号提供路径。

 mysqlx://user_name@/path%2Fto%2Fsocket.sock
 mysqlx://user_name@(/path/to/socket.sock)
*可以指定可选路径，表示一个数据库。

 #将'world'用作默认数据库
 mysqlx://user_name@198.51.100.1/world
 
 #将'world_x'用作默认数据库，将_编码为%5F
 mysqlx://user_name@198.51.100.2:33060/world%5Fx
*可以指定可选查询，由每个键值对或单个键给出的值组成。要指定多个值，请使用逗号字符分隔它们。允许混合使用键=值和键值。值可以是列表类型，列表值按出现顺序排序。字符串必须使用百分号编码或括号括起来。以下是等效的。

 ssluser@127.0.0.1?ssl-ca=%2Froot%2Fclientcert%2Fca-cert.pem
 &ssl-cert=%2Froot%2Fclientcert%2Fclient-cert.pem
 &ssl-key=%2Froot%2Fclientcert%2Fclient-key
 
 ssluser@127.0.0.1?ssl-ca=(/root/clientcert/ca-cert.pem)
 &ssl-cert=(/root/clientcert/client-cert.pem)
 &ssl-key=(/root/clientcert/client-key)
*要指定用于加密连接的TLS版本和密码套件：

 mysql://user_name@198.51.100.2:3306/world%5Fx?
 tls-versions=[TLSv1.2,TLSv1.3]&tls-ciphersuites=[TLS_DHE_PSK_WITH_AES_128_
 GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256]

前面的示例假设连接需要密码。对于交互式客户端，在登录提示符处请求指定用户的密码。如果用户帐户没有密码（这是不安全且不推荐的），或者如果使用套接字对等凭证验证（例如，使用Unix套接字连接），则必须在连接字符串中明确指定不提供密码并且不需要密码提示。为此，在user_name之后的字符串中放置一个:，但不在其后指定密码。例如：

 mysqlx://user_name:@localhost


==使用键值对进行连接==
在MySQL Shell和一些实现X DevAPI的MySQL连接器中，您可以使用键值对指定与MySQL服务器的连接，以语言自然构造的形式提供。例如，您可以在JavaScript中将连接参数作为键值对的JSON对象或在Python中作为字典提供。无论以何种方式提供键值对，概念都是相同的：如本节所述的键可以被赋予用于指定连接的值。您可以在MySQL Shell的shell.connect（）方法或InnoDB Cluster的dba.createCluster（）方法中使用键值对指定连接，并且可以使用一些实现X DevAPI的MySQL连接器。

通常，键值对由{和}字符括起来，逗号字符用作键值对之间的分隔符。:字符用于键和值之间，字符串必须用''字符引起来（例如，使用'字符）。与类似URI的连接字符串不同，不需要对字符串进行百分号编码。

以键值对形式指定的连接具有以下格式：

 { key: value, key: value, ...}
您可以作为连接键使用的参数在基本连接参数中进行了描述。

如果在键值对中未指定密码（建议的做法），交互式客户端会提示输入密码。以下示例演示了如何使用用户名'user_name'指定使用键值对的连接。在每种情况下，都会提示输入密码。

*连接到本地服务器实例，侦听端口33065的X协议连接。

 {user:'user_name', host:'localhost', port:33065}
*连接到本地服务器实例，侦听端口3333的经典MySQL协议连接。

 {user:'user_name', host:'localhost', port:3333}
*通过使用主机名、IPv4地址和IPv6地址连接到远程服务器实例的X协议连接。

 {user:'user_name', host:'server.example.com'}
 {user:'user_name', host:198.51.100.14:123}
 {user:'user_name', host:[2001:db8:85a3:8d3:1319:8a2e:370:7348]}
*使用套接字进行的X协议连接。

 {user:'user_name', socket:'/path/to/socket/file'}
*可以指定可选模式，表示一个数据库。

 {user:'user_name', host:'localhost', schema:'world'}

前面的示例假设连接需要密码。对于交互式客户端，在登录提示符处请求指定用户的密码。如果用户帐户没有密码（这是不安全且不推荐的），或者如果使用套接字对等凭证验证（例如，使用Unix套接字连接），则必须明确指定不提供密码并且不需要密码提示。为此，在密码键后面使用''提供一个空字符串。例如：

 {user:'user_name', password:'', host:'localhost'}