MySQL Shell 8.0 官方手册【第四章：入门操作】

本章讲解 MySQL Shell 的一些入门操作。

一、MySQL Shell 会话

我们通过执行 mysqlsh 命令开启一个 MySQL Shell 客户端。

> mysqlsh

开启 MySQL Shell 后，没有连接 MySQL 服务器，默认以 JavaScript 模式登录（可以设置），你可以通过 \py 或 \sql 命令切换不同脚本模式。

1.1 在开启 MySQL Shell 时创建一个全局会话对象

直接执行 mysqlsh 并没有连接 MySQL 服务器产生会话对象，可以通过添加选项参数来，在开启客户端时就创建一个全局会话对象。

兼容传统 mysql 客户端登录选项，第一次登录会提示是否保存密码。

那上面的--mc 选项是什么？

是连接协议，默认 mysql（端口 3306），可以切换为 X 协议（端口 33060）.
如果想 直接选择 SQL 模式，并指定协议，请参考以下选项：

登录信息的格式还有很多种，可以根据自己喜好：

以上连接信息包括一种新的连接格式： URI-LIKE Strings ，详见《使用 URI 连接服务器》

1.2 在开启 MySQL Shell 之后创建一个全局会话对象

简单的说，就是在打开 MySQL Shell 终端后用 \connect or \c 命令连接服务器。可以通过选项 --mc or --mx 选择连接协议， 格式固定为：

URL format is: [user[:password]@hostname[:port]]

SQL 模式连接：

JS 模式连接：

1.3 Javascript 和 Python 的脚本模式

使用 shell.connect() 方法。用的太少，自查 Scripting Sessions in JavaScript and Python Mode

二、MySQL Shell 连接

MySQL Shell 连接无论是 X 协议还是经典 MySQL 协议，处理密码都是很重要的。默认登陆需要输入密码（最大长度为128个字符），并可以使用密码存储区进行存储，后面详述。

配置连接超时请使用 connect-timeout 参数，必须为非负整数，以毫秒为单位定义时间范围，默认为 10000 毫秒或者 10 秒。

// Decrease the timeout to 2 seconds.
mysql-js> \connect user@example.com?connect-timeout=2000
// Increase the timeout to 20 seconds
mysql-js> \connect user@example.com?connect-timeout=20000

禁用超时则设置为 0，意味着客户端等待知道基础套接字超时为止，取决于系统。

2.1 加密连接

当连接到启用了 TLS（有时称为 SSL）的 MySQL 服务器时，可以使用加密连接。

要在启动MySQL Shell时配置加密连接，请使用以下命令选项：

• –ssl：已弃用，将在以后的版本中删除。使用 --ssl-mode。此选项启用或禁用加密的连接。
• –ssl-mode ：此选项指定到服务器连接的所需安全状态。
• –ssl-ca=file_name：PEM格式的文​​件的路径，其中包含受信任的SSL证书颁发机构的列表。
• –ssl-capath=dir_name：包含PEM格式的受信任SSL证书颁发机构证书的目录的路径。
• –ssl-cert=file_name：PEM格式的SSL证书文件的名称，用于建立加密连接。
• –ssl-cipher=name：用于建立加密连接的SSL密码的名称。
• –ssl-key=file_name：PEM格式的SSL密钥文件的名称，用于建立加密连接。
• –ssl-crl=name：包含PEM格式的证书吊销列表的文件的路径。
• –ssl-crlpath=dir_name：目录路径，该目录包含包含PEM格式的证书吊销列表的文件。
• –tls-version=version：允许用于加密连接的TLS协议，以逗号分隔的列表形式指定。例如 。 --tls-version=TLSv1.1,TLSv1.2
• –tls-ciphersuites=suites：允许用于加密连接的TLS密码套件，指定为以冒号分隔的TLS密码套件名称列表。例如 。在8.0.18版本中添加。
• –tls-ciphersuites=TLS_DHE_PSK_WITH_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256

或者，可以将 SSL 选项编码为类 URI 的连接字符串的一部分，并将其作为查询元素的一部分。可用的 SSL 选项与上面列出的选项相同，但没有前面的连字符。例如， ssl-ca 等于 --ssl-ca。

在类似 URI 的字符串中指定的路径必须经过百分比编码，例如：

[email protected]?ssl-ca%3D%2Froot%2Fclientcert%2Fca-cert.pem%26ssl-cert%3D%2Fro\
ot%2Fclientcert%2Fclient-cert.pem%26ssl-key%3D%2Froot%2Fclientcert%2Fclient-key
.pem

要在 JavaScript 或 Python 模式下为脚本会话建立加密连接，请在 connectionData 字典中设置 SSL 信息 。例如：

mysql-js> var session=mysqlx.getSession({host: 'localhost',
                                             user: 'root',
                                             password: 'password',
                                             ssl_ca: "path_to_ca_file",
                                             ssl_cert: "path_to_cert_file",
                                             ssl_key: "path_to_key_file"});

有关更多信息，请参见使用键值对进行连接。

2.2 压缩连接

2.2.1 MySQL Shell 8.0.20 及更高版本的压缩控制

从 MySQL Shell 8.0.20 开始，对于 X 协议连接和经典 MySQL 协议连接，无论何时创建会话对象来管理与 MySQL Server 实例的连接，都可以指定该连接是需要压缩，首选压缩还是禁用压缩。

压缩行为指定

• required 向服务器请求压缩的连接，如果服务器不支持压缩或无法在压缩协议上与 MySQL Shell 达成协议，则连接将失败。

• preferred 请求来自服务器的压缩连接，如果服务器不支持压缩或无法在压缩协议上与 MySQL Shell 达成一致，则退回至未压缩的连接。这是 X 协议连接的默认设置。

• disabled 请求未压缩的连接，并且如果服务器仅允许压缩的连接，则连接失败。这是经典 MySQL 协议连接的默认设置。

压缩算法支持

在 MySQL Shell 8.0.20 中，您还可以选择允许连接的压缩算法。默认情况下，MySQL Shell 向服务器建议用于 X 协议连接的 zlib，LZ4 和 zstd 算法，以及用于经典 MySQL 协议连接（不支持 LZ4 算法）的 zlib 和 zstd 算法。您可以指定这些算法的任意组合。指定压缩算法的顺序是 MySQL Shell 提出压缩算法的优先顺序，但是服务器可能不受此优先顺序的影响，具体取决于协议和服务器配置。

要从 MySQL Shell 8.0.20 请求压缩连接，请使用以下方法之一：

• 请使用 --compress or -C 选项，指定是需要压缩，首选压缩还是禁用压缩。

shell> mysqlsh --mysqlx -u user -h localhost -C required

• 可通过使用 --compression-algorithms 选项指定一个以逗号分隔的允许算法列表来指定字符串。对于 X 协议的连接，你可以使用 zlib，lz4 以及 zstd 以任意组合和优先顺序。对于经典的 MySQL 协议连接，您可以使用 zlib 和 zstd 以任何组合和优先顺序排列。

shell> mysqlsh --mysql -u user -h localhost -C preferred --compression-algorithms=zstd

• 您也可以 --compression-algorithms 不使用 --compress or -C 选项来请求压缩。在这种情况下，uncompressed 如果要允许未压缩的连接，请将其添加到算法列表中，如果不想允许它们，则将其省略。这种连接压缩控制风格与其他 MySQL 客户端（例如 mysql 和 mysqlbinlog）兼容。以下用于经典 MySQL 协议连接的示例与上面的示例具有相同的效果，其中 preferred 被指定为单独的选项，也就是说，建议使用 zstd 算法进行压缩，但会退回到未压缩的连接：

shell> mysqlsh --mysql -u user -h localhost --compression-algorithms=zstd,uncompressed

• 您可以使用 --compression-level 或 --zstd-compression-level 选项配置压缩级别 ，这些选项已针对经典 MySQL 协议连接进行了验证，但不适用于 X 协议连接。 --compression-level 为 X 协议连接的任何算法或仅在经典 MySQL 协议连接上的 zstd 算法指定压缩级别的整数。 --zstd-compression-level 为 zstd 算法的压缩级别指定一个 1 - 22 之间的整数，并且与其他 MySQL 客户端（例如 mysql 和 mysqlbinlog）兼容。例如，用于 X 协议连接的这些连接参数指定全局会话需要压缩，并且必须使用 LZ4 或 zstd 算法，请求的压缩级别为 5：

shell> mysqlsh --mysqlx -u user -h localhost -C required --compression-algorithms=lz4,zstd --compression-level=5

• URI 版本范例：

// bash
shell> mysqlsh mysqlx://user@localhost:33060?compression=disabled
// sql
mysql-js> \connect [email protected]?compression=preferred
mysql-js> \connect [email protected]:33060?compression=preferred&compression-algorithms=zlib,zstd&compression-level=4
mysql-js> \connect [email protected]:33060?compression-algorithms=zlib,zstd,uncompressed&compression-level=4
mysql-js>  var s1=mysqlx.getSession({host: 'localhost',
                                     user: 'root',
                                     password: 'password',
                                     compression: 'required'});

2.2.2 MySQL Shell 8.0.14 至 8.0.19 的压缩控制

在这些MySQL Shell版本中，压缩控制仅限于为连接启用（通过指定true）或禁用（通过指定false）压缩。
如果要从命令行启动 MySQL Shell，并使用单独的命令选项指定连接参数，请使用 --compress （-C） 选项，例如：

shell> mysqlsh --mysql -u user -h localhost -C

如果要使用类似 URI 的连接字符串从命令行，MySQL Shell 的 \connect 命令或 shell.connect() 方法中指定连接参数，请 compression=true 在查询字符串中使用该参数：

mysql-js> \connect user@example.com?compression=true
shell> mysqlsh mysql://user@localhost:3306?compression=true

如果要通过 MySQL Shell 的 \connect 命令或 mysql.getClassicSession() 方法使用键值对指定连接参数 ，请使用 compression 选项字典中的参数：

mysql-js> var s1=mysql.getClassicSession({host: 'localhost',
                                          user: 'root',
                                          password: 'password',
                                          compression: 'true'});

三、密码存储插件

为了使 MySQL Shell 工作更加安全，可以使用密码存储插件为服务连接保存密码。

mysql-js> \connect user@localhost:3310
Creating a session to 'user@localhost:3310'
Please provide the password for 'user@localhost:3310': ********
Save password for 'user@localhost:3310'? [Y]es/[N]o/Ne[v]er (default No): y

一旦存储了服务器 URL 的密码，每当 MySQL Shell 打开会话时，它都会从已配置的 Secret Store Helper 中检索密码，以登录到服务器，而 无需交互输入密码。MySQL Shell 执行的脚本也是如此。如果未配置任何 Secret Store Helper，则以交互方式请求密码。

注意：
MySQL Shell 仅通过 Secret Store 保留服务器 URL 和密码，而不自行保留密码。

密码只有在 手动输入 时才会保留。如果在运行 mysqlsh 时使用类似于服务器 URI 的连接字符串或在命令行中提供了密码，则该密码不会保留。

连接到 MySQL Shell 所接受的最大密码长度为128个字符。

在以下情况下执行自动密码存储和检索：

• 建立第一个会话时，使用任何连接选项调用 mysqlsh

• 您使用内置 \connect 命令

• 你用的 shell.connect() 方法

• 您使用任何需要连接的 AdminAPI 方法