4.2.5使用类似URI的字符串或键值对连接到服务器

本节介绍了如何使用类似URI的连接字符串或键值对来指定如何为MySQL Shell等客户端建立与MySQL服务器的连接。有关使用命令行选项建立连接的信息，对于mysql或mysqldump之类的客户端，请参见第4.2.4节“使用命令选项连接到MySQL服务器”。有关无法连接的其他信息，请参见 第6.2.21节“对连接MySQL的问题进行故障排除”。

注意

术语“类URI ”表示连接字符串语法，该语法类似于但不等同于RFC 3986定义的URI（统一资源标识符）语法 。

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

• MySQL Shell
• 实现X DevAPI的MySQL连接器

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

• 用类似URI的字符串指定的参数使用诸如的语法myuser@example.com:3306/main-schema。有关完整语法，请参见使用类似URI的连接字符串进行连接。
• 由键值对指定的参数使用语法，例如 {user:'myuser', host:'example.com', port:3306, schema:'main-schema'}。有关完整语法，请参见 使用键值对连接。

连接参数不区分大小写。如果指定了每个参数，则只能给出一次。如果多次指定参数，则会发生错误。

本节涵盖以下主题：

• 基本连接参数
• 其他连接参数
• 使用类似URI的连接字符串进行连接
• 使用键值对进行连接

基本连接参数

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

• scheme：要使用的传输协议。使用mysqlx的X协议连接和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的字符串中，必须使用百分比编码或使用括号将路径括起来对它们进行编码。括号消除了对字符（例如/目录分隔符）进行百分比编码的需要。例如，要root@localhost使用Unix套接字 进行连接 /tmp/mysql.sock，请使用百分比编码将路径指定为root@localhost?socket=%2Ftmp%2Fmysql.sock，或将括号 使用来指定 root@localhost?socket=(/tmp/mysql.sock)。

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

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

其他连接参数

您可以为连接指定选项，可以通过添加，将其指定为类似URI的字符串中的属性，也可以指定 为键值对。提供以下选项： ?*attribute=value*

• ssl-mode：连接所需的安全状态。允许以下模式：

  • DISABLED
  • PREFERRED
  • REQUIRED
  • VERIFY_CA
  • VERIFY_IDENTITY

  有关这些模式的信息，请参见“加密连接的命令选项”中的 --ssl-mode选项描述 。

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

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

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

• ssl-cipher：用于通过TLSv1.2使用TLS协议的连接的加密密码。

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

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

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

• tls-version：经典MySQL协议加密连接允许使用TLS协议。仅MySQL Shell支持此选项。tls-version（单数）的值 是一个逗号分隔的列表，例如 TLSv1.1,TLSv1.2。有关详细信息，请参见 第6.3.2节“加密的连接TLS协议和密码”。此选项取决于ssl-mode 未设置为的选项DISABLED。

• tls-versions：用于加密的X协议连接的允许TLS协议。tls-versions（复数）的值是一个数组，例如[TLSv1.2,TLSv1.3]。有关详细信息，请参见 第6.3.2节“加密的连接TLS协议和密码”。此选项取决于ssl-mode 未设置为的选项DISABLED。

• tls-ciphersuites：允许的TLS密码套件。的值 tls-ciphersuites是TLS密码套件中列出的IANA密码套件名称的列表 。有关详细信息，请参见 第6.3.2节“加密的连接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模式通过经典MySQL协议连接到MySQL 8.0服务器时使用 DISABLED。在这种情况下，您必须指定协议。例如：

  mysql://user@localhost:3306?get-server-public-key=true
  

  此选项适用于使用caching_sha2_password身份验证插件进行身份验证的客户端 。对于该插件，除非请求，否则服务器不会发送公钥。对于未使用该插件进行身份验证的帐户，将忽略此选项。如果未使用基于RSA的密码交换，也将被忽略，例如客户端使用安全连接连接到服务器时。

  如果 给出并指定了有效的公共密钥文件，则优先于。 server-public-key-path=*file_name*``get-server-public-key

  有关caching_sha2_password插件的信息 ，请参见 第6.4.1.2节“缓存SHA-2可插拔身份验证”。

• server-public-key-path：PEM格式的文件的路径名，其中包含服务器用于基于RSA密钥对的密码交换所需的公共密钥的客户端副本。通过SSL模式通过经典MySQL协议连接到MySQL 8.0服务器时使用 DISABLED。

  此选项适用于使用sha256_password或 caching_sha2_password身份验证插件进行身份验证的客户端 。对于未通过这些插件之一进行身份验证的帐户，将忽略此选项。如果未使用基于RSA的密码交换，也将被忽略，例如客户端使用安全连接连接到服务器时。

  如果 给出并指定了有效的公共密钥文件，则优先于。 server-public-key-path=*file_name*``get-server-public-key

  有关sha256_password 和caching_sha2_password插件的信息，请参见 第6.4.1.3节“ SHA-256可插拔身份验证”和 第6.4.1.2节“缓存SHA-2可插拔身份验证”。

• 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协议连接的默认值。有关X插件连接压缩控制的信息，请参见 第20.5.5节“使用X插件进行连接压缩”。

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

• compression-algorithms和 compression-level：这些选项在MySQL Shell 8.0.20和更高版本中可用，以更好地控制连接压缩。您可以指定它们以选择用于连接的压缩算法，以及用于该算法的数字压缩级别。您也可以使用compression-algorithms代替compression请求压缩连接。有关MySQL Shell的连接压缩控件的信息，请参见 使用压缩的连接。

• connection-attributes：控制应用程序在连接时传递给服务器的键/值对。有关连接属性的一般信息，请参见 第26.12.9节“性能架构连接属性表”。客户端通常定义一组默认属性，可以将其禁用或启用。例如：

  mysqlx://user@host?connection-attributes
  mysqlx://user@host?connection-attributes=true
  mysqlx://user@host?connection-attributes=false
  

  默认行为是发送默认属性集。除默认属性外，应用程序还可以指定要传递的属性。您可以将其他连接属性指定为connection-attributes 连接字符串中的参数。的 connection-attributes参数值必须是空的（等同于指定 true），一个Boolean值（true或false启用或禁用的默认属性集），或者一个列表或零个或多个key=value限定符用逗号隔开（除了默认属性集要被发送） 。在列表中，缺少的键值将计算为空字符串。进一步的例子：

  mysqlx://user@host?connection-attributes=[attr1=val1,attr2,attr3=]
  mysqlx://user@host?connection-attributes=[]
  

  应用程序定义的属性名称不能开头， _因为此类名称是为内部属性保留的。

使用类似URI的连接字符串进行连接

您可以使用类似URI的字符串指定与MySQL Server的连接。这样的字符串可以与带有 --uri命令选项的MySQL Shell \connect，MySQL Shell命令以及实现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组件和连接选项的字典转换为类似于URI的有效连接字符串以连接到MySQL，该字符串可在MySQL Shell中或由实现X DevAPI的MySQL连接器使用。

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

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

  mysqlx://user_name@localhost:33065
  

• 与本地服务器实例的经典MySQL协议连接，侦听端口3333。

  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)
  

• 可以指定一个可选路径，该路径代表一个数据库。

  # use 'world' as the default database
  mysqlx://user_name@198.51.100.1/world
  
  # use 'world_x' as the default database, encoding _ as %5F
  mysqlx://user_name@198.51.100.2:33060/world%5Fx
  

• 可以指定一个可选查询，该查询由每个值以 成对或单个形式给出。要指定多个值，请用字符分隔它们 。允许混合使用 和值。值可以是list类型，列表值按外观排序。字符串必须使用百分比编码或用括号括起来。以下是等效的。 *key*=*value*key,``*key*=*value*key

  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套接字连接），则必须在连接字符串中明确指定不提供密码。并且不需要密码提示。为此，请将a 放在字符串:后， *user_name*但不要在其后指定密码。例如：

mysqlx://user_name:@localhost

使用键值对进行连接

在MySQL Shell和某些实现X DevAPI的MySQL连接器中，您可以使用键-值对指定到MySQL Server的连接，键-值对以语言自然的构造形式提供给实现。例如，您可以使用键-值对提供连接参数，将其用作JavaScript中的JSON对象或Python中的字典。无论提供键值对的方式如何，概念都保持不变：可以为本节中描述的键分配用于指定连接的值。您可以在MySQL Shell的shell.connect()方法或InnoDB Cluster的 dba.createCluster()方法中使用键-值对以及一些实现X DevAPI的MySQL连接器来指定连接 。

通常，键值对由{和}字符包围， 并且字符 ,用作键值对之间的分隔符。该:字符键和值之间的使用，并且字符串必须（使用例如，分隔'符）。与类似URI的连接字符串不同，不必对字符串进行百分比编码。

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

{ key: value, key: value, ...}

基本连接参数 中介绍了可用作连接键的参数。

如果建议在键值对中未指定密码，则交互式客户端会提示您输入密码。以下示例显示如何使用带有用户名的键值对指定连接 。在每种情况下，都会提示输入密码。 '*user_name*'

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

  {user:'user_name', host:'localhost', port:33065}
  

• 与本地服务器实例的经典MySQL协议连接，侦听端口3333。

  {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套接字连接），则必须明确指定不提供密码，并提示输入密码不需要。为此，请''在password键之后使用提供一个空字符串 。例如：

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