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

[](<>)[](<>)

本节描述使用类似 URI 的连接字符串或键值对来指定如何建立与 MySQL 服务器的连接，用于 MySQL Shell 等客户端。有关使用命令行选项建立连接的信息，对于客户端，例如[**mysql**](mysql.html)要么[**mysql转储**](mysqldump.html)， 看[第 4.2.4 节，“使用命令选项连接到 MySQL 服务器”](connecting.html).有关无法连接的更多信息，请参阅[第 6.2.22 节，“解决连接到 MySQL 的问题”](problems-connecting.html).

[](<>)

笔记

术语“URI-like”表示连接字符串语法，它类似于但不等同于定义的 URI（统一资源标识符）语法[RFC 3986](https://tools.ietf.org/html/rfc3986).

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

-   MySQL 外壳

-   实现 X DevAPI 的 MySQL 连接器

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

-   用类似 URI 的字符串指定的参数使用如下语法`myuser@example.com:3306/main-schema`.有关完整语法，请参阅[使用类似 URI 的连接字符串进行连接](connecting-using-uri-or-key-value-pairs.html#connecting-using-uri).

-   使用键值对指定的参数使用如下语法`{用户：'myuser'，主机：'example.com'，端口：3306，架构：'main-schema'}`.有关完整语法，请参阅[使用键值对连接](connecting-using-uri-or-key-value-pairs.html#connecting-using-key-value-pairs).

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

    本节涵盖以下主题：

-   [基本连接参数](connecting-using-uri-or-key-value-pairs.html#connection-parameters-base)

-   [附加连接参数](connecting-using-uri-or-key-value-pairs.html#connection-parameters-additional)

-   [使用类似 URI 的连接字符串进行连接](connecting-using-uri-or-key-value-pairs.html#connecting-using-uri)

-   [使用键值对连接](connecting-using-uri-or-key-value-pairs.html#connecting-using-key-value-pairs)

#### 基本连接参数

[](<>)

以下讨论描述了指定与 MySQL 的连接时可用的参数。可以使用符合基本类似 URI 语法的字符串来提供这些参数（请参阅[使用类似 URI 的连接字符串进行连接](connecting-using-uri-or-key-value-pairs.html#connecting-using-uri)），或作为键值对（见[使用键值对连接](connecting-using-uri-or-key-value-pairs.html#connecting-using-key-value-pairs)）。

-   *`方案`*：要使用的传输协议。采用`mysqlx`对于 X 协议连接和`mysql`用于经典的 MySQL 协议连接。如果没有指定协议，服务器会尝试猜测协议。支持 DNS SRV 的连接器可以使用`mysqlx+srv`方案（见[使用 DNS SRV 记录的连接](https://dev.mysql.com/doc/x-devapi-userguide/en/connecting-dns-srv.html)）。

-   *`用户`*：为身份验证过程提供的 MySQL 用户帐户。

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

    警告

    在连接规范中指定显式密码是不安全的，不推荐使用。稍后的讨论显示了如何导致出现密码的交互式提示。

-   *`主持人`*：运行服务器实例的主机。该值可以是主机名、IPv4 地址或 IPv6 地址。如果未指定主机，则默认为`本地主机`.

-   *`港口`*：目标 MySQL 服务器正在侦听连接的 TCP/IP 网络端口。如果没有指定端口，X 协议连接默认为 33060，经典 MySQL 协议连接默认为 3306。

-   *`插座`*: Unix 套接字文件的路径或 Windows 命名管道的名称。值是本地文件路径。在类似 URI 的字符串中，它们必须被编码，使用百分比编码或用括号括起来路径。括号消除了对字符进行百分比编码的需要，例如`/`目录分隔符。例如，连接为`根@localhost`使用 Unix 套接字`/tmp/mysql.sock`，使用百分比编码指定路径为`root@localhost?socket=%2Ftmp%2Fmysql.sock`, 或使用括号作为`root@localhost?socket=(/tmp/mysql.sock)`.

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

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

#### 附加连接参数

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

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

    -   `已禁用`

    -   `首选`

    -   `必需的`

    -   `验证_CA`

    -   `VERIFY_IDENTITY`

        有关这些模式的信息，请参阅[`--ssl 模式`](connection-options.html#option_general_ssl-mode)选项描述在[加密连接的命令选项](connection-options.html#encrypted-connection-options).

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

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

-   `ssl 证书`: PEM 格式的 X.509 证书文件的路径。

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

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

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

-   `ssl 密钥`: PEM 格式的 X.509 密钥文件的路径。

-   `tls-版本`：经典 MySQL 协议加密连接允许的 TLS 协议。仅 MySQL Shell 支持此选项。的价值`tls-版本`（单数）是一个逗号分隔的列表，例如`TLSv1.2、TLSv1.3`.有关详细信息，请参阅[第 6.3.2 节，“加密连接 TLS 协议和密码”](encrypted-connection-protocols-ciphers.html).此选项取决于`ssl 模式`选项未设置为`已禁用`.

-   `tls 版本`：加密 X 协议连接的允许 TLS 协议。的价值`tls 版本`（复数）是一个数组，例如`[TLSv1.2,TLSv1.3]`.有关详细信息，请参阅[第 6.3.2 节，“加密连接 TLS 协议和密码”](encrypted-connection-protocols-ciphers.html).此选项取决于`ssl 模式`选项未设置为`已禁用`.

-   `tls-密码套件`：允许的 TLS 密码套件。的价值`tls-密码套件`是列出的 IANA 密码套件名称列表[TLS 密码套件](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4).有关详细信息，请参阅[第 6.3.2 节，“加密连接 TLS 协议和密码”](encrypted-connection-protocols-ciphers.html).此选项取决于`ssl 模式`选项未设置为`已禁用`.

-   `认证方法`：用于连接的身份验证方法。默认是`汽车`，表示服务器尝试猜测。以下方法是允许的：

    -   `汽车`

    -   `MYSQL41`

    -   `SHA256_MEMORY`

    -   `FROM_CAPABILITIES`

    -   `倒退`

    -   `清楚的`

        对于 X 协议连接，任何配置的`认证方法`被以下身份验证方法序列覆盖：`MYSQL41`,`SHA256_MEMORY`,`清楚的`.

-   `获取服务器公钥`：从服务器请求基于 RSA 密钥对的密码交换所需的公钥。在使用 SSL 模式通过经典 MySQL 协议连接到 MySQL 8.0 服务器时使用`已禁用`.在这种情况下，您必须指定协议。例如：

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

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

    如果`服务器公钥路径=*`文件名`*`给出并指定一个有效的公钥文件，它优先于`获取服务器公钥`.

    有关信息`cache_sha2_password`插件，见[第 6.4.1.2 节，“缓存 SHA-2 可插入身份验证”](caching-sha2-pluggable-authentication.html).

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

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

    如果`服务器公钥路径=*`文件名`*`给出并指定一个有效的公钥文件，它优先于`获取服务器公钥`.

    有关信息`sha256_password`和`cache_sha2_password`插件，见[第 6.4.1.3 节，“SHA-256 可插入身份验证”](sha256-pluggable-authentication.html)， 和[第 6.4.1.2 节，“缓存 SHA-2 可插入身份验证”](caching-sha2-pluggable-authentication.html).

-   `ssh`：用于连接到 SSH 服务器以使用 SSH 隧道访问 MySQL 服务器实例的 URI。URI 格式为`[用户@]主机[：端口]`.使用`乌里`用于指定目标 MySQL 服务器实例的 URI 的选项。有关来自 MySQL Shell 的 SSH 隧道连接的信息，请参阅[使用 SSH 隧道](https://dev.mysql.com/doc/mysql-shell/8.0/en/mysql-shell-connection-ssh.html).

-   `乌里`：要通过 SSH 隧道从由指定的服务器访问的 MySQL 服务器实例的 URI`ssh`选项。URI 格式为`[方案：//][用户@]主机[：端口]`.不要使用基本连接参数（`方案`,`用户`,`主持人`,`港口`) 为 SSH 隧道指定 MySQL 服务器连接，只需使用`乌里`选项。

-   `ssh 密码`：连接到 SSH 服务器的密码。

    警告

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

-   `ssh 配置文件`：用于连接 SSH 服务器的 SSH 配置文件。您可以使用 MySQL Shell 配置选项`ssh.config文件`如果未指定此选项，则将自定义文件设置为默认值。如果`ssh.config文件`没有设置，默认是标准的SSH配置文件`~/.ssh/config`.

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

-   `ssh 身份通行证`：由指定的身份文件的密码`ssh 身份文件`选项。

    警告

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

-   `连接超时`: 一个整数值，用于配置客户端（例如 MySQL Shell）在停止尝试连接到无响应的 MySQL 服务器之前等待的秒数。

-   `压缩`：此选项请求或禁用连接压缩。直到 MySQL 8.0.19，它仅适用于经典 MySQL 协议连接，从 MySQL 8.0.20 开始，它也适用于 X 协议连接。

    -   直到 MySQL 8.0.19，这个选项的值是`真的`（或 1）启用压缩，默认`错误的`（或 0）禁用压缩。

    -   从 MySQL 8.0.20 开始，此选项的值为`必需的`, 请求压缩，如果服务器不支持则失败；`首选`，它请求压缩并回退到未压缩的连接；和`禁用`，它请求未压缩的连接，如果服务器不允许，则失败。`首选`是 X 协议连接的默认值，并且`禁用`是经典 MySQL 协议连接的默认值。有关 X Plugin 连接压缩控制的信息，请参阅[第 20.5.5 节，“使用 X 插件进行连接压缩”](x-plugin-connection-compression.html).

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

-   `压缩算法`和`压缩级别`：这些选项在 MySQL Shell 8.0.20 及更高版本中可用，以更好地控制连接压缩。您可以指定它们以选择用于连接的压缩算法，以及与该算法一起使用的数字压缩级别。你也可以使用`压缩算法`代替`压缩`请求压缩连接。有关 MySQL Shell 的连接压缩控制的信息，请参阅[使用压缩连接](https://dev.mysql.com/doc/mysql-shell/8.0/en/mysql-shell-compressed-connections.html).

-   `连接属性`：控制应用程序在连接时传递给服务器的键值对。有关连接属性的一般信息，请参阅[第 27.12.9 节，“性能模式连接属性表”](performance-schema-connection-attribute-tables.html).客户端通常定义一组默认属性，可以禁用或启用。例如：

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

    默认行为是发送默认属性集。除了默认属性外，应用程序还可以指定要传递的属性。您将附加连接属性指定为`连接属性`连接字符串中的参数。这`连接属性`参数值必须为空（同指定`真的`）， 一种`布尔值`价值 （`真的`要么`错误的`启用或禁用默认属性集），或一个列表或零个或多个`键=值`用逗号分隔的说明符（除了默认属性集外发送）。在列表中，缺少的键值评估为空字符串。更多示例：

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

    应用程序定义的属性名称不能以`_`因为这些名称是为内部属性保留的。

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

[](<>)

您可以使用类似 URI 的字符串指定与 MySQL 服务器的连接。这样的字符串可以与 MySQL Shell 一起使用[`--uri`](https://dev.mysql.com/doc/mysql-shell/8.0/en/mysqlsh.html#option_mysqlsh_uri)命令选项，MySQL Shell`\连接`命令，以及实现 X DevAPI 的 MySQL 连接器。

笔记

术语“URI-like”表示连接字符串语法，它类似于但不等同于定义的 URI（统一资源标识符）语法[RFC 3986](https://tools.ietf.org/html/rfc3986).

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

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

重要的

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

您可以在类似 URI 的连接字符串中使用的参数在以下位置进行了描述[基本连接参数](connecting-using-uri-or-key-value-pairs.html#connection-parameters-base).

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

如果在类似 URI 的字符串中没有指定密码（推荐），交互式客户端会提示输入密码。以下示例显示如何使用用户名指定类似 URI 的字符串*`用户名`*.在每种情况下，都会提示输入密码。

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

    ```
    mysqlx://user_name@localhost:33065
    ```

-   一个经典的 MySQL 协议连接到在端口 3333 上侦听的本地服务器实例。

    ```
    mysql://user_name@localhost:3333
    ```

-   与远程服务器实例的 X 协议连接，使用主机名、IPv4 地址和 IPv6 地址。

    ```
    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
    ```

-   可以指定一个可选查询，由每个给出的值组成`*`钥匙`*=*`价值`*`双人还是单人*`钥匙`*.若要指定多个值，请按`,`角色。混合的`*`钥匙`*=*`价值`*`和*`钥匙`*数值是允许的。值可以是列表类型，列表值按外观排序。字符串必须采用百分比编码或用括号括起来。以下是等效的。

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


```
mysqlx://user_name:@localhost
```

#### 使用键值对进行连接

[](<>)

在MySQL Shell和一些实现X DevAPI的MySQL连接器中，可以使用键-值对指定到MySQL服务器的连接，键-值对以语言自然结构提供，用于实现。例如，可以使用键值对作为JavaScript中的JSON对象或Python中的字典来提供连接参数。无论提供键-值对的方式如何，概念都是一样的：本节中描述的键可以被分配用于指定连接的值。您可以在MySQL Shell的`壳连接（）`方法或InnoDB群集的`dba。createCluster（）`方法，并使用一些实现X DevAPI的MySQL连接器。

通常，键值对由`{`和`}`人物和`,`字符用作键值对之间的分隔符。这个`:`字符用于键和值之间，字符串必须分隔（例如，使用`'`性格）。与类似URI的连接字符串不同，不需要对字符串进行百分比编码。

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

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

可以用作连接键的参数如所述[基本连接参数](connecting-using-uri-or-key-value-pairs.html#connection-parameters-base).

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

-   与监听端口33065的本地服务器实例的X协议连接。

    ```
    {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套接字连接），则必须明确指定不提供密码，并且不需要密码提示。为此，请使用`''`之后`暗语`钥匙例如：


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