MySQL Shell API8.0.31
MySQL产品的统一开发接口
连接数据

连接数据

在MySQL Shell上公开的API上,有几个函数需要提供一些连接数据。

连接数据可以用以下格式指定:

  • URI字符串
  • 一个带有连接选项的字典

一个基本URI字符串有以下格式:

[方案:/ /][用户(密码):@]<主机(港口):|套接字>[/模式][?选项=价值选择=值…]

连接选项

以下选项在URI或字典中使用都是有效的:

  • SSL -mode:连接中使用的SSL模式。
  • ssl-ca: PEM格式的X509证书颁发机构文件路径。
  • ssl-capath: X509证书颁发机构PEM格式文件所在目录的路径。
  • SSL -cert: PEM格式的SSL公钥证书文件路径。
  • SSL -key: PEM格式的SSL私钥文件路径。
  • ssl-crl:包含证书吊销列表的文件路径。
  • ssl-crlpath:证书吊销列表文件所在目录的路径。
  • ssl-cipher:使用TLSv1.2以下TLS协议的连接所允许的加密密码列表。
  • tls-version:允许安全连接的协议列表。
  • TLS -ciphers:要使用的TLS v1.3密码列表。
  • auth-method:鉴权方式。
  • get-server-public-key:向服务器请求基于RSA密钥对的密码交换所需的公钥。当使用禁用SSL模式的经典MySQL会话连接MySQL 8.0服务器时使用。
  • server-public-key-path:一个文件的路径名,该文件包含服务器用于基于RSA密钥对的密码交换所需的公钥的客户端副本。当使用禁用SSL模式的经典MySQL会话连接MySQL 8.0服务器时使用。
  • connect-timeout:连接超时时间,以毫秒为单位。如果没有提供,将使用默认的10秒超时。指定值为0将禁用连接超时。
  • compression:在客户/服务器协议中启用压缩。
  • compression-algorithms:在服务器/客户端协议中使用压缩算法。
  • compression-level:在客户端/服务器协议中使用此压缩级别。
  • connection-attributes:要在PERFORMANCE_SCHEMA连接属性表中注册的连接属性列表。
  • LOCAL - INFILE:启用/禁用LOAD DATA LOCAL INFILE。
  • net-buffer-length:用于TCP/IP和套接字通信的缓冲区大小。

当在URI中定义这些选项时,它们的值必须是URL编码的。

当使用字典时,以下选项也有效:

基础连接选项

  • uri: uri字符串。
  • 方案:连接时使用的协议。
  • user:连接时使用的MySQL用户名。
  • dbUser:用户别名。
  • Password:连接时使用的密码。
  • dbPassword:与password相同。
  • host:连接中要使用的主机名或IP地址。
  • port: TCP连接使用的端口号。
  • Socket:通过Unix套接字连接时使用的套接字文件名。
  • Schema:连接完成后要选择的模式。

SSH隧道连接选项

  • ssh:需要ssh隧道时使用的SSHURI字符串。
  • SSH -password: SSH连接时使用的密码。
  • SSH -identity-file: SSH连接时使用的密钥文件。
  • SSH -identity-file-password: SSH私钥文件密码。
  • SSH -config-file: SSH配置文件,默认值为shell.options[' SSH . configfile ']
注意
dbUser和dbPassword选项将在未来的版本中删除。
连接选项优先于连接选项uri中指定的选项

连接选项不区分大小写,只能定义一次。

如果一个选项被定义了不止一次,就会产生一个错误。

连接数据中指定的选项决定要使用的连接类型。

scheme选项定义了在连接上使用的协议,以下是可接受的值:

  • mysql: mysql协议连接。
  • mysqlx:用于使用X协议的连接。

如果在连接数据中没有指定协议,shell将首先尝试使用X协议进行连接,如果连接失败,它将尝试使用MySQL协议进行连接。

通常,Shell使用TCP连接连接到服务器,除非连接数据包含创建下面描述的任何连接所需的选项。

unix域套接字连接

要使用unix域套接字连接到本地MySQL服务器,必须将主机设置为'localhost',不应提供端口号,并提供套接字路径。

在使用MySQL协议时,可能不提供套接字路径,在这种情况下,将使用套接字文件的默认路径。

在使用连接字典时,将套接字路径设置为套接字选项的值。

当使用URI时,套接字路径必须是URL编码如下:

  • % 2 fto % 2 fsocket.sock user@ /路径
  • % 2 fto % 2 fsocket.sock user@. /路径
  • user@ % 2 fto % 2 fsocket.sock . . /路径

可以通过将套接字路径括在圆括号中来跳过URL编码:

  • user@路径(/ / / socket.sock)
  • user@(. /道路/ / socket.sock)
  • user@(. . /路径/ / socket.sock)

Windows命名管道连接

要使用命名管道连接到MySQL服务器,主机必须设置为'。,不应提供端口号。

如果没有提供管道名,则使用默认的管道名:MySQL。

使用连接字典时,将命名管道名称设置为套接字选项的值。

在使用URI时,如果命名管道的URL包含无效字符,则必须采用URL编码。URL编码可以通过将管道名括在圆括号中跳过:

  • user@ \ \ \ named.pipe
  • user@ (\ \ \ named.pipe)。

命名管道连接只支持MySQL协议。

Windows共享内存连接

只有当服务器使用默认的共享内存基名称MySQL启用了共享内存连接时,才允许共享内存连接。

要使用共享内存连接到本地MySQL服务器,主机应该设置为'localhost',不应该提供端口。

如果服务器没有使用默认基名启用共享内存连接,则连接将使用TCP完成。

共享内存连接只支持MySQL协议。

SSL模式

ssl-mode选项接受以下值:

  • 禁用
  • 首选
  • 要求
  • VERIFY_CA
  • VERIFY_IDENTITY

TLS版本

tls-version选项接受以下格式的值:TLSv<版本>,例如TLSv1.2, TLSv1.3。

身份验证方法

在经典会话的情况下,这是要使用的身份验证插件的名称,即caching_sha2_password。对于X协议会话,它应该是:

  • 汽车、
  • FROM_CAPABILITIES,
  • 回退,
  • MYSQL41,
  • 平原,
  • SHA256_MEMORY。

连接压缩

连接压缩由以下连接选项控制:“压缩”、“压缩算法”和“压缩级”。

"compression"接受以下值:

  • REQUIRED:只有在压缩协商成功时才会进行连接。
  • preferred:(X协议连接的默认值)shell将尝试在启用压缩的情况下建立连接,但如果压缩协商失败,将在没有压缩的情况下建立连接。
  • DISABLED:(经典协议连接的默认值)连接将在没有压缩的情况下建立。

为了方便起见,“压缩”也接受布尔值:'True', 'False', '1'和'0'分别映射到REQUIRED和DISABLED。

“压缩-算法”要求算法列表以逗号分隔。支持的算法包括:

  • zstd
  • zlib
  • lz4(仅X协议)
  • Uncompressed -特殊值,如果它出现在列表中,即使压缩协商失败,也会导致连接成功。

如果没有定义“compression”连接选项,它的值将从提供时的“compression-algorithms”值推导出来。

“压缩级”需要一个整数值。有效范围取决于压缩算法和服务器配置,但通常预期如下:

  • Zstd: 1-22(默认为3)
  • zlib: 1-9(默认为3),仅X协议支持
  • lz4: 0-16(默认为2),仅X协议支持。

连接属性

连接属性是在连接时发送到服务器的键-值对。它们存储在以下PERFORMANCE_SCHEMA表中:

  • Session_account_connect_attrs:当前会话和与会话帐户关联的其他会话的属性。
  • Session_connect_attrs:所有会话的属性。

这些属性应该在创建会话时定义,并且在会话的生命周期内不可变。

要在URI上定义连接属性,连接属性应该定义为URI的一部分,如下所示:

root@localhost:端口/模式?连接属性= [att1 = value1, att2 = val2…]

注意,用于属性名和值的字符必须遵循URI标准,也就是说,如果字符不允许,则必须按百分比编码。

为了在使用字典创建会话时定义连接属性,应该定义连接属性选项,它的值可以用以下格式设置:

  • "key=value"对的数组。
  • 包含键值对的字典。

注意,连接属性值应该是字符串,如果在字典中使用了其他数据类型,则使用的数据的字符串表示将存储在数据库中。

URL编码

URL编码的值只接受字母数字字符和下面的符号:-._~!$'()*+;

任何其他字符必须是URL编码的。

URL编码是通过将被编码的字符替换为序列:%XX来完成的

其中XX是被编码字符的十六进制ASCII值。

如果host是一个字面IPv6地址,它应该用“[”和“]”字符括起来。

如果host是带区域ID的IPv6地址,则需要对地址和区域ID之间的'%'字符进行URL编码。