MySQL :: MySQL 8.4 参考手册 :: 6.2.5 使用 URI 类字符串或键值对连接到服务器

版本 8.4

9.0
8.0

8.0 日语

MySQL 8.4 参考手册 / ... / 使用 URI 类字符串或键值对连接到服务器

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

本节描述了如何使用 URI 类连接字符串或键值对来指定如何建立到 MySQL 服务器的连接，例如对于 MySQL Shell 这样的客户端。有关使用命令行选项（例如，对于 mysql 或 mysqldump 这样的客户端）建立连接的信息，请参见第 6.2.4 节，“使用命令选项连接到 MySQL 服务器”。如果您无法连接，请参见第 8.2.22 节，“排查连接到 MySQL 的问题”，获取更多信息。

注意

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

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

MySQL Shell
实现 X DevAPI 的 MySQL 连接器

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

使用 URI 类字符串指定的参数使用类似于 [email protected]: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，这意味着 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 协议（最高可达 TLSv1.2）的连接的加密密码。
ssl-crl: 包含 PEM 格式证书吊销列表的文件路径。
ssl-crlpath: 包含 PEM 格式证书吊销列表文件的目录路径。
ssl-key: PEM 格式的 X.509 密钥文件路径。
tls-version: 允许用于经典 MySQL 协议加密连接的 TLS 协议。此选项仅受 MySQL Shell 支持。tls-version（单数）的值是一个逗号分隔的列表，例如 TLSv1.2,TLSv1.3。有关详细信息，请参阅第 8.3.2 节，“加密连接 TLS 协议和密码”。此选项取决于 ssl-mode 选项是否设置为 DISABLED。
tls-versions: 允许用于加密 X 协议连接的 TLS 协议。tls-versions（复数）的值是一个数组，例如 [TLSv1.2,TLSv1.3]。有关详细信息，请参阅第 8.3.2 节，“加密连接 TLS 协议和密码”。此选项取决于 ssl-mode 选项是否设置为 DISABLED。
tls-ciphersuites: 允许的 TLS 密码套件。tls-ciphersuites 的值是 IANA 密码套件名称的列表，如 TLS 密码套件中列出。有关详细信息，请参阅第 8.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 密钥对基于密码交换的公钥。当通过经典 MySQL 协议使用 SSL 模式 DISABLED 连接到 MySQL 8+ 服务器时使用。在这种情况下，您必须指定协议。例如
```
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 插件的信息，请参阅第 8.4.1.2 节，“缓存 SHA-2 可插拔身份验证”。
server-public-key-path: 用于包含服务器为 RSA 密钥对基于密码交换所需的公钥的 PEM 格式文件的路径名。当通过经典 MySQL 协议使用 SSL 模式 DISABLED 连接到 MySQL 8+ 服务器时使用。
此选项适用于使用 sha256_password（已弃用）或 caching_sha2_password 身份验证插件进行身份验证的客户端。此选项对不使用这些插件之一进行身份验证的帐户将被忽略。如果未使用基于 RSA 的密码交换，此选项也会被忽略，例如，当客户端使用安全连接连接到服务器时。
如果给出 server-public-key-path=file_name 并指定了一个有效的公钥文件，它将优先于 get-server-public-key。
有关 sha256_password（已弃用）和 caching_sha2_password 插件的信息，请参阅第 8.4.1.3 节，“SHA-256 可插拔身份验证” 和第 8.4.1.2 节，“缓存 SHA-2 可插拔身份验证”。
ssh: 用于连接到 SSH 服务器以使用 SSH 隧道访问 MySQL 服务器实例的 URI。URI 格式为 [user@]host[:port]。使用 uri 选项指定目标 MySQL 服务器实例的 URI。有关来自 MySQL Shell 的 SSH 隧道连接的信息，请参阅使用 SSH 隧道。
uri: 用于通过 SSH 隧道（从 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: 此选项请求或禁用连接的压缩。
此选项可用的值为：required，它请求压缩，如果服务器不支持压缩则失败；preferred，它请求压缩，并回退到未压缩的连接；以及 disabled，它请求未压缩的连接，如果服务器不允许未压缩的连接则失败。preferred 是 X 协议连接的默认值，而 disabled 是经典 MySQL 协议连接的默认值。有关 X 插件连接压缩控制的信息，请参阅第 22.5.5 节，“使用 X 插件的连接压缩”。

注意

不同的 MySQL 客户端对连接压缩的支持方式不同。有关详细信息，请查阅您的客户端文档。
compression-algorithms 和 compression-level: 这些选项在 MySQL Shell 中可用，用于更细致地控制连接压缩。您可以指定它们来选择用于连接的压缩算法，以及与该算法一起使用的数字压缩级别。您也可以使用 compression-algorithms 代替 compression 请求连接的压缩。有关 MySQL Shell 的连接压缩控制的信息，请参阅使用压缩连接。
connection-attributes: 控制应用程序在连接时传递给服务器的键值对。有关连接属性的常规信息，请参阅第 29.12.9 节，“性能架构连接属性表”。客户端通常定义一组默认属性，这些属性可以禁用或启用。例如
```
mysqlx://user@host?connection-attributes
mysqlx://user@host?connection-attributes=true
mysqlx://user@host?connection-attributes=false
```
默认行为是发送默认属性集。应用程序可以指定要传递的属性，以补充默认属性。您可以在连接字符串中指定要传递的其他连接属性作为 connection-attributes 参数。connection-attributes 参数值必须为空（与指定 true 相同），布尔值（true 或 false 以启用或禁用默认属性集），或者是一个列表，包含 0 个或多个由逗号分隔的 key=value 说明符（要发送到默认属性集之外）。在列表中，缺失的键值将被评估为空字符串。其他示例
```
mysqlx://user@host?connection-attributes=[attr1=val1,attr2,attr3=]
mysqlx://user@host?connection-attributes=[]
```
应用程序定义的属性名称不能以 _ 开头，因为这些名称保留用于内部属性。

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

您可以使用 URI 类似的字符串指定与 MySQL Server 的连接。这些字符串可以与 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
```

与远程服务器实例的 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

可以指定可选的查询，它由作为 key=value 对或作为单个 key 给出的值组成。要指定多个值，请用 , 字符分隔它们。混合使用 key=value 和 key 值是允许的。值可以是列表类型，列表值按出现顺序排序。字符串必须是百分比编码的，或者用圆括号括起来。以下内容是等效的。
```
[email protected]?ssl-ca=%2Froot%2Fclientcert%2Fca-cert.pem\
&ssl-cert=%2Froot%2Fclientcert%2Fclient-cert.pem\
&ssl-key=%2Froot%2Fclientcert%2Fclient-key

[email protected]?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}
```

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

{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'}