MySQL程序之：使用类似URI的字符串或键值对连接到服务器

本节介绍使用类似URI的连接字符串或键值对来指定如何为MySQLShell等客户端建立到MySQL服务器的连接。

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

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

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

• 使用类似URI的字符串指定的参数使用[e-mail]:3306/main-schema等语法。
• 使用键值对指定的参数使用以下语法{user:'myuser', host:'example.com', port:3306, schema:'main-schema'}。

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

基础连接参数

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

• scheme：要使用的传输协议。X协议连接使用mysqlx，经典MySQL协议连接使用mysql。如果未指定协议，服务器会尝试猜测协议。支持域名系统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套接字连接为root@localhost/tmp/mysql.sock，使用百分比编码指定路径为root@localhost?socket=%2Ftmp%2Fmysql.sock，或使用括号作为root@localhost?socket=(/tmp/mysql.sock)。

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

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

附加连接参数

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

• ssl-mode：连接所需的安全状态。以下模式是允许的：DISABLED、PREFERRED、REQUIRED、VERIFY_CA、VERIFY_IDENTITY，重要：VERIFY_CA并且VERIFY_IDENTITY是比默认的PREFERRED更好的选择，因为它们有助于防止中间人攻击。

• 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协议。此选项仅受MySQLShell支持。tls-version（单数）的值是逗号分隔的列表，例如TLSv1.2、TLSv1.3。有关详细信息，请参阅“加密连接TLS协议和密码”。此选项取决于未设置为DISABLED的ssl-mode选项。
• TLS-版本：加密X协议连接允许的TLS协议。TLS-版本的值（复数）是一个数组，例如[TLSv1.2， TLSv1.3]。有关详细信息，请参阅，“加密连接TLS协议和密码”。此选项取决于未设置为DISABLED的ssl模式选项。
• tls-ciphersuites：允许的TLS密码套件。tls-ciphersuites的值是TLS密码套件中列出的IANA密码套件名称列表。有关详细信息，请参阅“加密连接TLS协议和密码”。此选项取决于未设置为DISABLED的ssl-mode选项。

• 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协议连接到MySQL8+台服务器时使用DISABLED。在这种情况下，您必须指定协议。例如：

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

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

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

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

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

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

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

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

• ssh-password：连接到SSH服务器的密码。警告：在连接规范中指定显式密码不安全且不推荐。MySQLShell会在需要密码时以交互方式提示输入密码。

• ssh-config-file：连接SSH服务器的SSH配置文件。如果未指定MySQLShell配置选项ssh.configFile，可以使用该选项将自定义文件设置为默认值。如果未设置ssh.configFile，则默认为标准SSH配置文件~/.ssh/config。

• ssh-identity-file：用于连接到SSH服务器的标识文件。如果未指定此选项，则默认为在SSH代理（如果使用）、SSH配置文件或SSH配置文件夹（~/. ssh/id_rsa~/.ssh/id_rsa

• ssh-identity-pass：标识文件的密码由ssh-identity-file选项指定。警告：在连接规范中指定显式密码不安全且不推荐。MySQLShell会在需要密码时以交互方式提示输入密码。

• connect-timeout：一个整数值，用于配置客户端（如MySQLShell）在停止尝试连接到无响应MySQL服务器之前等待的秒数。

• compression：此选项请求或禁用连接的压缩。

  此选项可用的值是：required，请求压缩，如果服务器不支持，则失败；preferred，请求压缩并回退到未压缩的连接；disabled，请求未压缩的连接，如果服务器不允许，则失败。preferred是X协议连接的默认值，disabled是经典MySQL协议连接的默认值。有关X插件连接压缩控制的信息，请参阅“使用X插件进行连接压缩”。注：不同的MySQL客户端实现其对连接压缩的支持不同。有关详细信息，请参阅客户端的留档。

• compression-algorithms和compression-level：这些选项在MySQLShell中提供，可以更好地控制连接压缩。您可以指定它们来选择用于连接的压缩算法以及用于该算法的数字压缩级别。您还可以使用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相同）、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、MySQL Shell\connect命令和实现X DevAPI的MySQL Connectors一起使用。

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

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

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

MySQLShell的shell.parseUri()和shell.unparseUri()方法可用于解构和组装类似URI的连接字符串。给定一个类似URI的连接字符串，shell.parseUri()返回一个字典，其中包含字符串中找到的每个元素。shell.unparseUri()将URI组件和连接选项的字典转换为有效的类似URI的连接字符串，用于连接到MySQL，可以在MySQLShell或实现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://[e-mail]/
  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

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

  ssluser@127.0.0.1?ssl-ca=%2Froot%2Fclientcert%2Fca-cert.pem\
  &ssl-cert=%2Froot%2Fclientcert%2Fclient-cert.pem\
  &ssl-key=%2Froot%2Fclientcert%2Fclient-keyssluser@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

使用键值对进行连接

在MySQLShell和一些实现X DevAPI的MySQL连接器中，您可以使用键值对来指定到MySQLServer的连接，这些键值对是为实现提供的语言自然结构。例如，您可以使用键值对作为JavaScript中的JSON对象或Python中的字典来提供连接参数。无论键值对的提供方式如何，概念都保持不变：可以为本节中描述的键分配用于指定连接的值。您可以使用MySQLShell的shell. connect（）方法或InnoDB簇的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'}

• 可以指定一个可选的schema，它代表一个数据库。

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

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

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