朝花夕拾16章MySQL Shell 第 5 章 MySQL Shell 代码执行

原创由迪 2023-07-07

1117

第 5 章 MySQL Shell 代码执行

本节介绍 MySQL Shell 中代码执行的工作原理。

5.1 主动语言

MySQL Shell 可以执行 SQL、JavaScript 或 Python 代码，但一次只能使用一种语言。主动模式决定了执行的语句如何处理：

如果使用 SQL 模式，语句将被作为 SQL 处理，这意味着它们将被发送到 MySQL 服务器执行。
如果使用 JavaScript 模式，语句将作为 JavaScript 代码进行处理。
如果使用 Python 模式，语句将作为 Python 代码处理。

笔记

从版本 8.0.18 开始，MySQL Shell 使用 Python 3。对于包含系统支持的 Python 3 安装的平台，MySQL Shell 使用最新可用版本，最低支持版本为 Python 3.4.3。对于不包含 Python 3 的平台，MySQL Shell 捆绑 Python 3.7.4。MySQL Shell 保持与 Python 2.6 和 Python 2.7 的代码兼容性，因此如果您需要这些旧版本之一，则可以使用适当的 Python 版本从源代码构建 MySQL Shell。

在交互模式下运行 MySQL Shell 时，通过输入以下命令激活特定语言：\sql、 \js、\py。

在批处理模式下运行 MySQL Shell 时，通过传递以下任意命令行选项来激活特定语言： --js、 --py或 --sql。如果未指定，则默认模式是 JavaScript。

使用 MySQL Shell 将文件内容 code.sql作为 SQL 执行。

$> mysqlsh --sql < code.sql

使用 MySQL Shell 将文件内容 code.js作为 JavaScript 代码执行。

$> mysqlsh < code.js

使用 MySQL Shell 将文件内容 code.py作为 Python 代码执行。

$> mysqlsh --py < code.py

从 MySQL Shell 8.0.16 开始，您可以在另一种语言处于活动状态时执行单个 SQL 语句，方法是输入 \sql紧跟 SQL 语句的命令。例如：

mysql-py> \sql select * from sakila.actor limit 3;

SQL 语句不需要任何额外的引号，并且语句分隔符是可选的。该命令仅接受单行上的单个 SQL 查询。使用这种格式，MySQL Shell 不会像输入命令那样切换模式 \sql。执行 SQL 语句后，MySQL Shell 保持 JavaScript 或 Python 模式。

从 MySQL Shell 8.0.18 开始，您可以在任何语言处于活动状态时执行操作系统命令，只需输入 \system或\!命令，然后紧跟要执行的命令。例如：

mysql-py> \system echo Hello from MySQL Shell!

MySQL Shell 显示操作系统命令的输出，或者如果无法执行该命令则返回错误。

5.2 交互式代码执行

MySQL Shell 的默认模式提供您在命令提示符下键入的数据库操作的交互式执行。这些操作可以用 JavaScript、Python 或 SQL 编写，具体取决于当前的第 5.1 节“活动语言”。执行时，操作结果显示在屏幕上。

与任何其他语言解释器一样，MySQL Shell 对于语法非常严格。例如，以下 JavaScript 代码片段打开与 MySQL 服务器的会话，然后读取并打印集合中的文档：

var mySession = mysqlx.getSession('user:pwd@localhost');
var result = mySession.getSchema('world_x').getCollection('countryinfo').find().execute();
var record = result.fetchOne();
while(record){
  print(record);
  record = result.fetchOne();
}

如上所示，调用find()之后是函数execute()。execute()CRUD 数据库命令仅在调用时才在 MySQL 服务器上实际执行。但是，当以交互方式使用 MySQL Shell 时，每当您按下语句execute()时就会隐式调用。Return然后获取操作结果并将其显示在屏幕上。何时需要呼叫 execute()或不需要呼叫的规则如下：

当以这种方式使用 MySQL Shell 时，调用 execute()变为可选：
- Collection.add()
- Collection.find()
- Collection.remove()
- Collection.modify()
- Table.insert()
- Table.select()
- Table.delete()
- Table.update()
如果将对象分配给变量，则自动执行将被禁用。在这种情况下，execute() 必须调用才能执行该操作。
当处理一行并且函数返回任何可用Result对象时，Result 对象中包含的信息将自动显示在屏幕上。返回 Result 对象的函数包括：
- SQL执行和CRUD操作（上面列出）
- mysql和模块中会话对象的事务处理和删除功能mysqlx：-
  - startTransaction()
  - commit()
  - rollback()
  - dropSchema()
  - dropCollection()
  - ClassicSession.runSql()

根据上述规则，在MySQL Shell中以交互方式建立会话、查询、打印集合中的文档所需的语句如下：

mysql-js> var mySession = mysqlx.getSession('user:pwd@localhost');
mysql-js> mySession.getSchema('world_x').getCollection('countryinfo').find();

不需要调用execute()，并且会自动打印 Result 对象。

多行支持

可以在多行上指定语句。在 Python 或 JavaScript 模式下，当语句块开始时（例如函数定义、if/then 语句、for 循环等），会自动启用多行模式。\在 SQL 模式下，发出命令时会启动多行模式。

一旦启动多行模式，随后输入的语句就会被缓存。

例如：

mysql-sql> \
... create procedure get_actors()
... begin
...   select first_name from sakila.actor;
... end
...

笔记

\sql当您在另一种语言处于活动状态时使用带查询的命令来执行单个 SQL 语句时，不能使用多行模式。该命令仅接受单行上的单个 SQL 查询。

5.3 代码自动完成

MySQL Shell 支持通过按Tab键自动补全光标前面的文本。第 3.1 节“MySQL Shell 命令”可以在任何语言模式下自动完成。例如，键入 **\con**并按下该 Tab键会自动完成为 \connect。自动完成功能适用于 SQL、JavaScript 和 Python 语言关键字，具体取决于当前的第 5.1 节“活动语言”。

自动完成支持以下文本对象：

在 SQL 模式下，自动完成功能会识别当前活动模式的模式名称、表名称和列名称。
在 JavaScript 和 Python 模式中，自动完成功能可以识别对象成员，例如：
- 全局对象名称，例如session、 db、dba、 shell、mysql、 mysqlx等。
- 全局对象的成员，例如 session.connect()、 dba.configureLocalInstance()等。
- 全局用户定义变量
- 链接的对象属性引用，例如 shell.options.verbose.
- 链接的 X DevAPI 方法调用，例如 col.find().where().execute().fetchOne().

默认情况下，自动完成功能处于启用状态，要更改此行为，请参阅配置自动完成功能。

激活自动完成功能后，如果光标前面的文本恰好有一个可能的匹配项，则该文本将自动完成。如果自动完成功能找到多个可能的匹配项，它会发出蜂鸣声或使终端闪烁。如果Tab再次按下该键，则会显示可能完成的列表。如果未找到匹配项，则不会发生自动完成。

自动完成SQL

在 SQL 模式下，上下文感知自动补全功能会使用相关补全来补全任何单词。从 MySQL Shell 8.0.31 开始，可以自动完成以下内容：

模式
表格
意见
列
存储过程
功能
触发器
活动
引擎
用户定义函数
运行时函数
日志文件组
用户变量
系统变量
表空间
用户
字符集
校对
插件

如果您连接到 MySQL 实例但未选择架构，则自动补全可用于全局对象、字符集、引擎、架构等。例如，在默认 MySQL 安装中，USE建议检测到的所有模式的名称，除非提供模式名称中的一个或多个相关字符：

         SQL > use 
         information_schema  mysql  performance_schema  sys

如果选择模式，则会加载其他模式信息并可用于自动完成（表、事件等）。如果从一种模式切换到另一种模式，从前一种模式加载的对象仍可用于自动完成。\rehash但是，在运行该命令之前，会话期间添加的任何新对象都无法用于自动完成。

要获取建议列表或从所选架构中完成部分单词，请输入初始片段并按 Tab 按钮两次。例如：

在 SQL 提示符下，输入以下片段： SE。
按 Tab 键两次。

以下建议显示在您输入的下方：
```
            SET SELECT
```
在 SQL 提示符下，输入以下片段： SEL。
按 Tab 键两次。

片段自动完成为SELECT.

如果可能的结果有很多，系统会提示您是否显示结果。例如：

Display all 118 possibilities? (y or n)

SQL 自动完成 API

自动补全API通过以下函数暴露给开发者：

JavaScript：shell.autoCompleteSql(statement, options)
Python：shell.auto_complete_sql(statement, options)
声明：“ *string*”

用于自动完成的部分 SQL 语句。

这些返回自动完成的可行候选。

****选项****：

服务器版本：“ *string*”

必需的。服务器语法版本。其格式为major.minor.patch。 serverVersion:"8.0.31"，例如。
sql模式：“ *string*”

必需的。要使用的 SQL 模式。以逗号分隔的字符串， sqlMode: "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION"例如。有关详细信息，请参阅服务器 SQL 模式。
语句偏移：*number*

选修的。语句中插入符号从零开始的偏移位置。默认值是语句的长度。
大写关键字：[true|false]

默认true。返回的关键字是否为大写。
过滤：[真|假]

默认true。是否应使用自动完成的前缀来过滤结果中返回的显式候选名称。

此函数使用以下语法返回描述语句自动完成候选的字典：

        {
         "context": {
           "prefix": string,
           "qualifier": list of strings,
           "references": list of dictionaries,
           "labels": list of strings,
         },
         "keywords": list of strings,
         "functions": list of strings,
         "candidates": list of strings,
        }

context：自动完成操作的上下文。
prefix：正在自动完成的片段。
qualifier：如果有限定名称可用，则出现。

例如：
- SELECT s：前缀是 's'，不存在限定符。
- SELECT schema1.t: 前缀是 't'，限定符是 ['schema1']。
- SELECT schema1.table1.c: 前缀是'c'，限定符是 ['schema1','table1']。
- SELECT schema1.table1.column1 FR：前缀是'FR'，不存在限定符。
references：在声明中检测到的引用。
- schema: 模式的名称。
- table：语句中引用的表的名称。
- alias：表的别名。
labels：标记块中的标签。
keywords：候选关键词建议。
functions：候选 MySQL 库（运行时）函数，其名称也是关键字。
candidates：列出一名或多名受支持的候选人。模式、表、视图等。

例如：

          JS > shell.autoCompleteSql("select * from  ",{serverVersion: "8.0.30", sqlMode: "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION"})
            {
                "candidates": [
                    "schemas",
                    "tables",
                    "views"
                ],
                "context": {
                    "prefix": ""
                },
                "functions": [
                    "JSON_TABLE()"
                ],
                "keywords": [
                    "DUAL",
                    "LATERAL"
                ]
            }

自动完成 JavaScript 和 Python

在 JavaScript 和 Python 模式下，要完成的字符串都是从右到左确定的，从按**Tab时当前光标位置开始。**方法调用内的内容将被忽略，但语法必须正确。这意味着字符串、注释和嵌套方法调用都必须正确关闭和平衡。这允许正确处理链式方法。例如，当您发出：

print(db.user.select().where("user in ('foo', 'bar')").e

按Tab键会导致自动完成尝试完成文本 db.user.select().where().e，但此无效代码会产生未定义的行为。由 a 分隔的标记之间的任何空格（包括换行符）都 .将被忽略。

配置自动完成

默认情况下，自动完成引擎处于启用状态。本节介绍如何禁用自动完成以及如何使用 \rehashMySQL Shell 命令。自动补全使用 MySQL Shell 识别的数据库名称对象的缓存。启用自动完成后，此名称缓存会自动更新。例如，每当您加载架构时，自动完成引擎都会根据架构中找到的文本对象更新名称缓存，以便您可以自动完成表名称等。

要禁用此行为，您可以：

使用命令选项启动 MySQL Shell --no-name-cache。
修改autocomplete.nameCache和 devapi.dbObjectHandles键 shell.options以在 MySQL Shell 运行时禁用自动完成功能。

当自动完成名称缓存被禁用时，您可以通过发出来手动更新自动完成功能识别的文本对象 \rehash。这会强制根据当前活动模式重新加载名称缓存。

要在 MySQL Shell 运行时禁用自动完成功能，请使用以下shell.options键：

autocomplete.nameCache: boolean切换自动完成名称缓存以供 SQL 使用。
devapi.dbObjectHandles: boolean切换自动完成名称缓存以供 X DevAPI db对象使用，例如 db.mytable, db.mycollection。

两个键均默认设置为，如果使用命令选项则true设置为。要在 MySQL Shell 运行时更改 SQL 的自动完成名称缓存，请发出： false--no-name-cache

shell.options['autocomplete.nameCache']=true

使用该\rehash命令手动更新名称缓存。

要在 MySQL Shell 运行时更改 JavaScript 和 Python 的自动完成名称缓存，请发出：

shell.options['devapi.dbObjectHandles']=true

您再次可以使用该\rehash命令手动更新名称缓存。

5.4 编辑代码

MySQL Shell 的\edit命令（从 MySQL Shell 8.0.18 开始提供）在默认系统编辑器中打开命令进行编辑，然后在 MySQL Shell 中呈现编辑后的命令以供执行。还可以使用缩写形式 \e或组合键Ctrl-X Ctrl-E 来调用该命令。如果您为命令指定参数，则该文本将放置在编辑器中。如果不指定参数，MySQL Shell 历史记录中的最后一个命令将放置在编辑器中。

和环境变量用于标识默认的系统编辑器EDITOR。VISUAL如果无法从这些环境变量中识别默认系统编辑器，MySQL Shell 将 notepad.exe在 Windows 和 vi任何其他平台上使用。命令编辑发生在临时文件中，MySQL Shell 随后将其删除。

完成编辑后，必须保存文件并关闭编辑器，然后 MySQL Shell 会显示已编辑的文本，您可以按Enter执行，或者如果您不想继续，则按 Ctrl-C取消。

例如，此处用户使用 threads一组自定义列运行 MySQL Shell 内置报告，然后在系统编辑器中打开命令以添加某些列的显示名称：

\show threads --foreground -o tid,cid,user,host,command,state,lastwait,lastwaitl
\e
\show threads --foreground -o tid=thread_id,cid=conn_id,user,host,command,state,lastwait=last_wait_event,lastwaitl=wait_length

5.5 代码历史

您在 MySQL Shell 中发出的代码存储在历史记录中，然后可以使用向上和向下箭头键访问历史记录。您还可以使用增量历史搜索功能来搜索历史记录。要搜索历史记录，请使用Ctrl+R向后搜索，或使用Ctrl+S向前搜索历史记录。搜索激活后，键入字符将搜索历史记录中与其匹配的任何字符串，并显示第一个匹配项。使用Ctrl+S或 Ctrl+R搜索与当前搜索词的进一步匹配。键入更多字符可以进一步细化搜索。在搜索过程中，您可以按箭头键继续从当前搜索结果逐步浏览历史记录。按 Enter 接受显示的匹配。使用Ctrl+C 取消搜索。

MySQL history.maxSizeShell 配置选项设置历史记录中存储的最大条目数。默认值为 1000。如果历史条目数超过配置的最大值，则最旧的条目将被删除并丢弃。如果最大值设置为 0，则不存储任何历史条目。

默认情况下，会话之间不会保存历史记录，因此当您退出 MySQL Shell 时，当前会话期间发出的历史记录将会丢失。您可以通过启用 MySQL Shell history.autoSave选项来保存会话之间的历史记录。例如，要使此更改成为永久问题：

mysqlsh-js> \option --persist history.autoSave=1

启用该history.autoSave选项后，历史记录将存储在 MySQL Shell 配置路径中，该路径是~/.mysqlshLinux 和 macOS 上的目录，或%AppData%\MySQL\mysqlshWindows 上的文件夹。通过定义环境变量，可以在所有平台上覆盖此路径 MYSQLSH_USER_CONFIG_HOME。保存的历史记录由 MySQL Shell 自动创建，并且只能由所有者用户读取。如果无法读取或写入历史文件，MySQL Shell 会记录一条错误消息并跳过读取或写入操作。在版本 8.0.16 之前，历史记录条目保存到单个history文件，其中包含以所有 MySQL Shell 语言发布的代码。在 MySQL Shell 版本 8.0.16 及更高版本中，历史记录按活动语言进行拆分，文件名为history.sql、 history.js和 history.py。

发出 MySQL Shell\history命令会按照发出的顺序显示历史条目及其历史条目编号，这些条目可以与该命令一起使用。您可以手动删除单个历史记录条目、指定数字范围的历史记录条目或历史记录的尾部。您还可以使用手动删除整个历史记录。当您退出 MySQL Shell 时，如果配置选项已设置为，则保存历史文件中保留的历史条目，并且它们的编号将重置为从 1 开始。如果配置选项设置为，这是默认值，历史文件被清除。 \history delete *entry_number*``\history clear``history.autoSave``true``shell.options["history.autoSave"]``false

只有您在 MySQL Shell 提示符下以交互方式键入的代码才会添加到历史记录中。间接或内部执行的代码（例如\source 执行命令时）不会添加到历史记录中。当您发出多行代码时，历史条目中的新行字符将被删除。如果多次发出相同的代码，则只会在历史记录中存储一次，从而减少重复。

您可以使用命令选项自定义添加到历史记录中的条目--histignore。此外，当在 SQL 模式下使用 MySQL Shell 时，您可以配置不应添加到历史记录中的字符串。\sql当您在另一种语言处于活动状态时使用带有查询的命令来执行单个 SQL 语句时，也会应用此历史记录忽略列表。

默认情况下，与全局模式匹配的字符串 IDENTIFIED或PASSWORD不会添加到历史记录中。要配置更多字符串以匹配，请使用--histignore命令选项或 shell.options["history.sql.ignorePattern"]. 可以指定多个字符串，用冒号 (😃 分隔。历史匹配使用不区分大小写的全局模式，如匹配。支持的通配符为 *（匹配任意 0 个或多个字符）和 ? （精确匹配 1 个字符）。默认字符串指定为 "*IDENTIFIED*:*PASSWORD*"。

通过按向上箭头始终可以使用最近执行的语句，即使历史忽略列表适用于它。这样您就可以进行更正，而无需重新键入所有输入。如果过滤应用于最后执行的语句，则一旦输入另一条语句，或者执行该语句后立即退出 MySQL Shell，该语句就会从历史记录中删除。

5.6 批处理代码执行

除了交互式代码执行之外，MySQL Shell 还提供批处理代码执行：

加载用于处理的文件。
包含重定向到标准输入执行的代码的文件。
来自不同源的代码被重定向到标准输入来执行。

提示

作为批量执行文件的替代方法，您还可以从终端控制 MySQL Shell，请参见第 5.8 节 “API 命令行集成”。

在批处理模式下，第 5.2 节“交互式代码执行” 中描述的所有命令逻辑均不可用，只能执行活动语言的有效代码。处理SQL代码时，使用以下逻辑逐条执行：读取/处理/打印结果。处理非 SQL 代码时，它完全从输入源加载并作为一个单元执行。使用 --interactive(或 -i) 命令行选项配置 MySQL Shell 以处理输入源，就像以交互模式发出一样；这使得交互模式提供的所有功能都可以在批处理中使用。

笔记

在这种情况下，无论源是什么，都会逐行读取并使用交互式管道进行处理。

输入是根据 MySQL Shell 中选择的当前编程语言进行处理的，默认为 JavaScript。您可以使用 MySQL Shell 配置选项更改默认编程语言 defaultMode。无论默认编程语言如何，扩展名为.js、 .py、和的文件始终以适当的语言模式进行处理。.sql

此示例演示如何从文件加载 JavaScript 代码以进行批处理：

$> mysqlsh --file code.js

这里，JavaScript 文件被重定向到标准输入来执行：

$> mysqlsh < code.js

此示例演示如何将 SQL 代码重定向到标准输入以执行：

$> echo "show databases;" | mysqlsh --sql --uri user@192.0.2.20:33060

从 MySQL Shell 8.0.22 开始， --pym命令行选项可用于在 Python 模式下将指定的 Python 模块作为脚本执行。-m该选项的工作方式与 Python 的命令行选项相同。

可执行脚本

#!在 Linux 上，您可以通过包含一行作为脚本的第一行来创建与 MySQL Shell 一起运行的可执行脚本。此行应提供 MySQL Shell 的完整路径并包含该 --file选项。例如：

#!/usr/local/mysql-shell/bin/mysqlsh --file
print("Hello World\n");

脚本文件必须在文件系统中标记为可执行文件。运行脚本会调用 MySQL Shell 并执行脚本的内容。

脚本中的 SQL 执行

X 协议会话的 SQL 查询执行通常使用该 sql()函数，该函数将 SQL 语句作为字符串，并返回一个 SqlExecute 对象，您可以使用该对象绑定和执行查询并返回结果。在将 SQL 与会话结合使用中描述了此方法。然而，经典 MySQL 协议会话的 SQL 查询执行使用该 runSql()函数，该函数接受 SQL 语句及其参数，将指定参数绑定到指定查询中，并一步执行查询，返回结果。

如果您需要创建独立于连接 MySQL 服务器的协议的 MySQL Shell 脚本，MySQL Shell 提供了X 协议的函数，其工作方式与经典 MySQL 协议会话中的函数session.runSql() 相同。runSql()您只能在 MySQL Shell 中使用此函数来代替sql()，以便您的脚本可以使用 X 协议会话或经典 MySQL 协议会话。Session.runSql()返回一个SqlResult对象，该对象符合经典MySQL协议函数返回的ClassicResult对象的规范，因此可以用相同的方式处理结果。

笔记

Session.runSql()是 JavaScript 和 Python 中 MySQL Shell X DevAPI 实现所独有的，不是标准 X DevAPI 的一部分。

要浏览查询结果，您可以使用该 fetchOneObject()功能，该功能适用于经典MySQL协议和X协议。此函数将下一个结果作为脚本对象返回。列名用作字典中的键（如果它们是有效标识符，则用作对象属性），行值用作字典中的属性值。对对象所做的更新不会保留在数据库中。

例如，MySQL Shell 脚本中的此代码可与 X 协议会话或经典 MySQL 协议会话配合使用，以检索和输出给定国家/地区的城市名称：

var resultSet = mySession.runSql("SELECT * FROM city WHERE countrycode = ' AUT'");
var row = resultSet.fetchOneObject();
print(row['Name']);

5.7 输出格式

MySQL Shell 可以以表格、选项卡式或垂直格式打印结果，或者作为漂亮或原始的 JSON 输出。从 MySQL Shell 8.0.14 开始，MySQL Shell 配置选项 resultFormat可用于指定任何这些输出格式作为所有会话或仅当前会话的持久默认值。更改此选项会立即生效。有关设置 MySQL Shell 配置选项的说明，请参阅第 13.4 节 “配置 MySQL Shell 选项”。或者，可以在启动时使用命令行选项 --result-format或其别名（--table、 --tabbed、 --vertical）来指定会话的输出格式。有关命令行选项的列表，请参阅A.1 节，“mysqlsh — MySQL Shell”。

如果resultFormat未指定该配置选项，当MySQL Shell处于交互模式时，打印结果集的默认格式为格式化表，当MySQL Shell处于批处理模式时，打印结果集的默认格式为制表符分隔输出。当您使用配置选项设置默认值时resultFormat，该默认值适用于交互模式和批处理模式。

MySQL Shell 函数shell.dumpRows()可以将查询返回的结果集格式化为 MySQL Shell 支持的任何输出格式，并将其转储到控制台。（请注意，结果集由函数使用。）

为了帮助将 MySQL Shell 与外部工具集成，--json当您从命令行启动 MySQL Shell 时，您可以使用该选项来控制所有 MySQL Shell 输出的 JSON 包装。resultFormat 当 JSON 包装打开时，MySQL Shell 会生成漂亮打印的 JSON（默认）或原始 JSON，并且MySQL Shell 配置选项的值将被忽略。当关闭 JSON 包装或会话未请求 JSON 包装时，结果集将以 resultFormat配置选项指定的格式正常输出。

该outputFormat配置选项现已弃用。该选项结合了 JSON 包装和结果打印功能。如果您的 MySQL Shell 配置文件或脚本中仍然指定了此选项，则行为如下：

使用jsonor json/raw值， outputFormat分别使用漂亮或原始 JSON 激活 JSON 包装。
使用table、tabbed或vertical值， outputFormat关闭 JSON 包装并将resultFormat会话的配置选项设置为适当的值。

文档主页

MySQL 外壳 8.0

5.7.1 表格格式

当 MySQL Shell 处于交互模式时，默认使用表格式打印结果集。查询结果以格式化表格形式呈现，以便更好地查看并帮助分析。

要在批处理模式下运行时获得此输出格式，请使用 --result-format=table命令行选项（或其别名 --table）启动 MySQL Shell，或将 MySQL Shell 配置选项设置 resultFormat为table。

例 5.1 以表格格式输出

MySQL  localhost:33060+ ssl  world_x  JS > shell.options.set('resultFormat','table')
MySQL  localhost:33060+ ssl  world_x  JS > session.sql("select * from city where countrycode='AUT'")
+------+------------+-------------+---------------+-------------------------+
| ID   | Name       | CountryCode | District      | Info                    |
+------+------------+-------------+---------------+-------------------------+
| 1523 | Wien       | AUT         | Wien          | {"Population": 1608144} |
| 1524 | Graz       | AUT         | Steiermark    | {"Population": 240967}  |
| 1525 | Linz       | AUT         | North Austria | {"Population": 188022}  |
| 1526 | Salzburg   | AUT         | Salzburg      | {"Population": 144247}  |
| 1527 | Innsbruck  | AUT         | Tiroli        | {"Population": 111752}  |
| 1528 | Klagenfurt | AUT         | Kärnten       | {"Population": 91141}   |
+------+------------+-------------+---------------+-------------------------+
6 rows in set (0.0030 sec)

5.7.3 垂直格式

\G垂直格式选项垂直打印结果集，而不是在水平表中，其方式与查询终止符用于 SQL 查询时的方式相同。当较长的文本行是输出的一部分时，垂直格式更具可读性。

--result-format=vertical要获得此输出格式，请使用命令行选项（或其别名）启动 MySQL Shell --vertical，或将 MySQL Shell 配置选项设置 resultFormat为vertical。

例 5.3 以垂直格式输出

MySQL  localhost:33060+ ssl  world_x  JS > shell.options.set('resultFormat','vertical')
MySQL  localhost:33060+ ssl  world_x  JS > session.sql("select * from city where countrycode='AUT'")
*************************** 1. row ***************************
         ID: 1523
       Name: Wien
CountryCode: AUT
   District: Wien
       Info: {"Population": 1608144}
*************************** 2. row ***************************
         ID: 1524
       Name: Graz
CountryCode: AUT
   District: Steiermark
       Info: {"Population": 240967}
*************************** 3. row ***************************
         ID: 1525
       Name: Linz
CountryCode: AUT
   District: North Austria
       Info: {"Population": 188022}
*************************** 4. row ***************************
         ID: 1526
       Name: Salzburg
CountryCode: AUT
   District: Salzburg
       Info: {"Population": 144247}
*************************** 5. row ***************************
         ID: 1527
       Name: Innsbruck
CountryCode: AUT
   District: Tiroli
       Info: {"Population": 111752}
*************************** 6. row ***************************
         ID: 1528
       Name: Klagenfurt
CountryCode: AUT
   District: Kärnten
       Info: {"Population": 91141}
6 rows in set (0.0027 sec)

5.7.4 JSON格式输出

MySQL Shell 提供了许多 JSON 格式选项来打印结果集：

json或者json/pretty

这些选项都会生成打印精美的 JSON。
ndjson或者json/raw

这些选项都会生成由换行符分隔的原始 JSON。
json/array

此选项生成包装在 JSON 数组中的原始 JSON。

您可以通过使用命令行选项启动 MySQL Shell 或设置 MySQL Shell 配置选项来选择这些输出格式。 --result-format=*value*resultFormat

在批处理模式下，为了帮助将 MySQL Shell 与外部工具集成，您可以--json 在从命令行启动 MySQL Shell 时使用该选项来控制所有输出的 JSON 包装。resultFormat当 JSON 包装打开时，MySQL Shell 会生成漂亮打印的 JSON（默认）或原始 JSON，并且MySQL Shell 配置选项的值将被忽略。有关说明，请参阅第 5.7.5 节 “JSON 包装”。

示例 5.4 以漂亮打印的 JSON 格式输出（json或 json/pretty）

MySQL  localhost:33060+ ssl  world_x  JS > shell.options.set('resultFormat','json')
MySQL  localhost:33060+ ssl  world_x  JS > session.sql("select * from city where countrycode='AUT'")
{
    "ID": 1523,
    "Name": "Wien",
    "CountryCode": "AUT",
    "District": "Wien",
    "Info": {
        "Population": 1608144
    }
}
{
    "ID": 1524,
    "Name": "Graz",
    "CountryCode": "AUT",
    "District": "Steiermark",
    "Info": {
        "Population": 240967
    }
}
{
    "ID": 1525,
    "Name": "Linz",
    "CountryCode": "AUT",
    "District": "North Austria",
    "Info": {
        "Population": 188022
    }
}
{
    "ID": 1526,
    "Name": "Salzburg",
    "CountryCode": "AUT",
    "District": "Salzburg",
    "Info": {
        "Population": 144247
    }
}
{
    "ID": 1527,
    "Name": "Innsbruck",
    "CountryCode": "AUT",
    "District": "Tiroli",
    "Info": {
        "Population": 111752
    }
}
{
    "ID": 1528,
    "Name": "Klagenfurt",
    "CountryCode": "AUT",
    "District": "Kärnten",
    "Info": {
        "Population": 91141
    }
}
6 rows in set (0.0031 sec)

示例 5.5 带有换行符（ndjson或json/raw）的原始 JSON 格式输出

MySQL  localhost:33060+ ssl  world_x  JS > shell.options.set('resultFormat','ndjson')
MySQL  localhost:33060+ ssl  world_x  JS > session.sql("select * from city where countrycode='AUT'")
{"ID":1523,"Name":"Wien","CountryCode":"AUT","District":"Wien","Info":{"Population":1608144}}
{"ID":1524,"Name":"Graz","CountryCode":"AUT","District":"Steiermark","Info":{"Population":240967}}
{"ID":1525,"Name":"Linz","CountryCode":"AUT","District":"North Austria","Info":{"Population":188022}}
{"ID":1526,"Name":"Salzburg","CountryCode":"AUT","District":"Salzburg","Info":{"Population":144247}}
{"ID":1527,"Name":"Innsbruck","CountryCode":"AUT","District":"Tiroli","Info":{"Population":111752}}
{"ID":1528,"Name":"Klagenfurt","CountryCode":"AUT","District":"Kärnten","Info":{"Population":91141}}
6 rows in set (0.0032 sec)

示例 5.6 以原始 JSON 格式包装在 JSON 数组中的输出 ( json/array)

MySQL  localhost:33060+ ssl  world_x  JS > shell.options.set('resultFormat','json/array')
MySQL  localhost:33060+ ssl  world_x  JS > session.sql("select * from city where countrycode='AUT'")
[
{"ID":1523,"Name":"Wien","CountryCode":"AUT","District":"Wien","Info":{"Population":1608144}},
{"ID":1524,"Name":"Graz","CountryCode":"AUT","District":"Steiermark","Info":{"Population":240967}},
{"ID":1525,"Name":"Linz","CountryCode":"AUT","District":"North Austria","Info":{"Population":188022}},
{"ID":1526,"Name":"Salzburg","CountryCode":"AUT","District":"Salzburg","Info":{"Population":144247}},
{"ID":1527,"Name":"Innsbruck","CountryCode":"AUT","District":"Tiroli","Info":{"Population":111752}},
{"ID":1528,"Name":"Klagenfurt","CountryCode":"AUT","District":"Kärnten","Info":{"Population":91141}}
]
6 rows in set (0.0032 sec)

MySQL 外壳 8.0

5.7.5 JSON 包装

为了帮助将 MySQL Shell 与外部工具集成，--json当您从命令行启动 MySQL Shell 时，您可以使用该选项来控制所有 MySQL Shell 输出的 JSON 包装。该 --json选项仅对指定的 MySQL Shell 会话有效。

指定--json、 --json=pretty或 --json=raw打开会话的 JSON 包装。无论 --json=pretty指定或不指定值，都会生成打印精美的 JSON。使用 --json=raw，生成原始 JSON。

打开 JSON 包装后，resultFormat在配置文件或命令行（使用该选项--result-format 或其别名之一）中为 MySQL Shell 配置选项指定的任何值都将被忽略。

指定--json=off会关闭会话的 JSON 包装。当 JSON 包装关闭或会话未请求 JSON 包装时，结果集将以 resultFormatMySQL Shell 配置选项指定的格式正常输出。

示例 5.7 带有漂亮打印 JSON 包装的 MySQL Shell 输出（--json或 --json=pretty）

$> echo "select * from world_x.city where countrycode='AUT'" | mysqlsh --json --sql --uri user@localhost:33060
or
$> echo "select * from world_x.city where countrycode='AUT'" | mysqlsh --json=pretty --sql --uri user@localhost:33060
{
    "hasData": true,
    "rows": [
        {
            "ID": 1523,
            "Name": "Wien",
            "CountryCode": "AUT",
            "District": "Wien",
            "Info": {
                "Population": 1608144
            }
        },
        {
            "ID": 1524,
            "Name": "Graz",
            "CountryCode": "AUT",
            "District": "Steiermark",
            "Info": {
                "Population": 240967
            }
        },
        {
            "ID": 1525,
            "Name": "Linz",
            "CountryCode": "AUT",
            "District": "North Austria",
            "Info": {
                "Population": 188022
            }
        },
        {
            "ID": 1526,
            "Name": "Salzburg",
            "CountryCode": "AUT",
            "District": "Salzburg",
            "Info": {
                "Population": 144247
            }
        },
        {
            "ID": 1527,
            "Name": "Innsbruck",
            "CountryCode": "AUT",
            "District": "Tiroli",
            "Info": {
                "Population": 111752
            }
        },
        {
            "ID": 1528,
            "Name": "Klagenfurt",
            "CountryCode": "AUT",
            "District": "Kärnten",
            "Info": {
                "Population": 91141
            }
        }
    ],
    "executionTime": "0.0067 sec",
    "affectedRowCount": 0,
    "affectedItemsCount": 0,
    "warningCount": 0,
    "warningsCount": 0,
    "warnings": [],
    "info": "",
    "autoIncrementValue": 0
}

示例 5.8 使用原始 JSON 包装的 MySQL Shell 输出 ( --json=raw)

$> echo "select * from world_x.city where countrycode='AUT'" | mysqlsh --json=raw --sql --uri user@localhost:33060
{"hasData":true,"rows":[{"ID":1523,"Name":"Wien","CountryCode":"AUT","District":"Wien","Info":{"Population":1608144}},{"ID":1524,"Name":"Graz","CountryCode":"AUT","District":"Steiermark","Info":{"Population":240967}},{"ID":1525,"Name":"Linz","CountryCode":"AUT","District":"North Austria","Info":{"Population":188022}},{"ID":1526,"Name":"Salzburg","CountryCode":"AUT","District":"Salzburg","Info":{"Population":144247}},{"ID":1527,"Name":"Innsbruck","CountryCode":"AUT","District":"Tiroli","Info":{"Population":111752}},{"ID":1528,"Name":"Klagenfurt","CountryCode":"AUT","District":"Kärnten","Info":{"Population":91141}}],"executionTime":"0.0117 sec","affectedRowCount":0,"affectedItemsCount":0,"warningCount":0,"warningsCount":0,"warnings":[],"info":"","autoIncrementValue":0}

5.7.6 结果元数据

执行操作时，除了返回任何结果之外，还会返回一些附加信息。当满足以下任一条件时，这包括受影响的行数、警告、持续时间等信息：

JSON 格式用于输出
MySQL Shell 以交互模式运行。

当 JSON 格式用于输出时，元数据将作为 JSON 对象的一部分返回。在交互模式下，元数据在结果之后打印。

5.8 API 命令行集成

MySQL Shell 通过 API 命令行集成公开其大部分功能，使用的语法无需打开交互界面即可访问对象及其函数。这使您能够轻松地将 mysqlsh与其他工具集成。例如，如果您想使用 bash脚本自动创建 InnoDB 集群，则可以使用命令行集成来调用 AdminAPI 操作。此功能类似于使用--execute 选项，但命令行集成使用简化的参数语法，减少了终端可能需要的引用和转义。与批处理模式不同，命令行集成是无状态的。这意味着返回供进一步操作使用的对象的操作是不可能的。命令行集成调用操作或全局对象的函数，然后返回。

5.8.1 命令行集成概述

本节提供命令行集成的概述和一些基本使用示例。有关更多详细信息，请参阅第 5.8.2 节 “命令行集成详细信息”。

以下内置 MySQL Shell 全局对象可用：

session- 代表当前的全局会话。
db- 表示全局会话的默认数据库（如果该会话是使用指定默认数据库的 X 协议连接建立的）。请参阅使用 MySQL 作为文档存储。
dba- 提供对 AdminAPI 的访问，用于管理 InnoDB Cluster、InnoDB ClusterSet 和 InnoDB ReplicaSet 部署。请参阅第 6 章，MySQL AdminAPI。
cluster- 代表一个InnoDB集群。
rs- 代表一个InnoDB ReplicaSet。
shell- 提供对 MySQL Shell 功能的访问，例如shell.options配置 MySQL Shell 选项（请参见第 13.4 节“配置 MySQL Shell 选项”）。
util- 提供对 MySQL Shell 实用程序的访问。请参阅第 11 章，MySQL Shell 实用程序。

有关更多信息，请参见第 4.5 节 “MySQL Shell 全局对象”。

MySQL Shell 命令行集成语法

重要的

从 MySQL Shell 8.0.32 开始，MySQL Shell 默认读取 MySQL 服务器选项文件和登录路径。因此，如果您连接到使用选项文件的 MySQL 服务器，默认情况下将使用该选项文件，并尝试使用该配置创建全局会话。如果您不想使用选项文件，则必须将其添加 --no-defaults到命令行中。

您可以通过启动mysqlsh应用程序并传入特殊选项来访问命令行集成 --。当您以这种方式启动 MySQL Shell 时，表示--选项列表的末尾（例如要连接的服务器、要使用的语言等）以及传递到命令行集成之后的所有内容。命令行集成支持特定语法，该语法基于 MySQL Shell 交互界面中使用的对象和方法。要使用命令行集成语法执行操作，请在终端问题中执行以下操作：

mysqlsh [options] -- [shell_object]+ object_method [arguments]

语法元素是：

*shell_object*是映射到 MySQL Shell 全局对象的字符串。命令行集成支持嵌套对象。要调用嵌套对象中的函数，请提供层次结构中以空格分隔的对象列表，以到达所需的对象。
*object_method*是最后一个提供的方法的名称 shell_object。方法名称可以按照 JavaScript 或 Python 命名约定或替代的命令行集成友好格式提供，其中所有已知函数均使用小写字母，并且单词之间用连字符分隔。a 的名称 *object_method*自动从标准 JavaScript 风格的驼峰式名称转换而来，其中所有大小写更改都替换为 a -并转为小写。例如，createCluster变为 create-cluster.
arguments**object_method 是调用时传递给的参数。

*shell_object*必须与公开的全局对象之一匹配，并且任何嵌套对象必须是列表中提供的前一个对象的子对象。必须 *object_method*与列表方法中最后一个对象之一匹配，并且必须以有效格式之一定义（JavaScript、Python 或命令行友好）。如果它们不对应于有效的对象及其方法，MySQL Shell 将以状态 10 退出。

请参阅MySQL Shell 命令行集成示例中的示例。

命令行集成中可用的对象

要找出命令行集成中可用的对象和方法，最好查询您正在使用的 MySQL Shell。这是因为除了与 MySQL Shell 捆绑在一起的标准对象之外，还可能会暴露来自插件的其他对象。

要获取命令行集成支持的对象列表：

$ mysqlsh -- --help

这将显示对象列表以及该对象提供的内容的简短描述。

要获取命令行集成中可用的函数列表*object*：

$ mysqlsh -- object --help

有关更多信息，请参见第 5.8.2.4 节 “命令行帮助”。

MySQL Shell 命令行集成参数语法

该*arguments*列表是可选的，所有参数都必须遵循适合命令行使用的语法，如本节中所述。特殊字符（例如空格或 \）和引号在传递到 MySQL Shell 之前会由系统的 shell（bash、cmd等）进行处理。如果您不熟悉系统 shell 在解析命令时如何处理这些字符序列，则应尽量避免使用它们。例如，传递带有引号作为参数一部分的参数，例如“ list,of,names ”，仅在命令行上使用该语法是不够的。您需要使用系统的 shell 语法来转义这些引号。如果不这样做，MySQL Shell 可能不会收到实际的引号。请参见第 5.8.2.2 节“定义参数”。

参数列表中可以使用两种类型的参数：匿名参数和命名参数。匿名参数用于定义简单类型参数，例如字符串、数字、布尔值、null。命名参数用于定义列表参数的值和字典参数中的选项，它们是键值对，其中值是简单类型。它们的使用必须遵循以下模式：

[positional_argument | named_argument]*

语法的所有部分都是可选的，并且可以按任何顺序给出。然后，这些参数按以下顺序转换为传递给方法调用的参数：

来自列表的命名参数会导致将值附加到源自该命名参数的列表参数
来自字典的命名参数会导致将值添加到源自该命名参数的字典参数中
如果存在没有定义显式选项的字典参数，这会导致它接受不属于另一个列表或字典参数的 任何命名参数
提供给函数调用的任何剩余参数都按照提供的顺序进行处理

MySQL Shell 命令行集成示例

使用命令行集成，调用 MySQL Shell API 函数比使用选项更容易、更省事 --execute。以下示例展示了如何使用此功能：

检查服务器实例是否适合升级并将结果以 JSON 形式返回以供进一步处理：

  $ mysqlsh -- util check-for-server-upgrade --user=root --host=localhost --port=3301 --password='password' --outputFormat=JSON --config-path=/etc/mysql/my.cnf

MySQL Shell 交互模式下的等效命令：

  mysql-js> util.checkForServerUpgrade({user:'root', host:'localhost', port:3301}, {password:'password', outputFormat:'JSON', configPath:'/etc/mysql/my.cnf'})

要部署 InnoDB Cluster 沙箱实例，侦听端口 1234 并指定用于连接的密码：
```
$ mysqlsh -- dba deploy-sandbox-instance 1234 --password=password
```
MySQL Shell 交互模式下的等效命令：
```
mysql-js> dba.deploySandboxInstance(1234, {password: password})
```
要使用监听端口 1234 的沙盒实例并指定名称来创建 InnoDB 集群 mycluster：
```
$ mysqlsh root@localhost:1234 -- dba create-cluster mycluster
```
MySQL Shell 交互模式下的等效命令：
```
mysql-js> dba.createCluster('mycluster')
```
要使用监听端口 1234 的沙盒实例检查 InnoDB Cluster 的状态：
```
$ mysqlsh root@localhost:1234 -- cluster status
```
MySQL Shell 交互模式下的等效命令：
```
mysql-js> cluster.status()
```
要配置 MySQL Shell 以打开命令历史记录：
```
$ mysqlsh -- shell options set_persist history.autoSave true
```
MySQL Shell 交互模式下的等效命令：
```
mysql-js> shell.options.set_persist('history.autoSave', true);
```
5.8.2 命令行集成详细信息
本节提供有关 MySQL Shell 命令行集成的详细信息。

5.8.2.1 MySQL Shell API 函数的命令行集成

MySQL Shell 提供了公开不同功能的全局对象，例如dba用于 InnoDB Cluster 和 InnoDB ReplicaSet 管理操作、util实用函数等。全局对象提供从 MySQL Shell 中的脚本模式调用的函数。除了交互式 MySQL Shell 集成之外，您还可以使用命令行集成直接从终端调用对象函数，使您能够轻松与其他工具集成。

当您以交互模式使用 MySQL Shell 附带的 API 时，典型的函数语法如下：

object.functionName(parameter1, parameter2, ..., parameterN)

这些参数定义了向 API 函数提供数据的顺序。在大多数情况下，API 函数需要特定数据类型的参数，但也有一些例外，即特定参数可以处理多种数据类型。API 函数中参数使用的数据类型可以是以下之一：

标量：字符串、数字、布尔值、null
列表
字典：键值对，其中键是字符串
对象

列表参数通常被限制为包含预定义数据类型的元素，例如字符串列表，但是，可能存在支持不同数据类型的项目的列表参数。

字典参数接受 key-value 对，其中*keys*是字符串。与键关联的数据 *value*通常应该是预定义的数据类型。但是，在某些情况下，同一键的值可能支持不同的数据类型。因此，字典参数可以是以下类型之一：

允许使用预定义的键值对集，在这种情况下，指定不在预定义集中的键会导致错误。
不存在预定义的键值对集，字典接受任何键

换句话说，一些字典参数指定哪些键是有效的。对于这些参数，尝试使用该组之外的密钥会导致错误。当不存在预定义值集时，可以使用任何数据类型的任何值。没有预定义键列表的字典参数接受任何键值对，只要该键不在不同字典参数的预定义集中即可。

要使用命令行集成调用全局对象公开的 API 函数，而无需在 MySQL Shell 中启动交互式会话，您必须以正确的方式提供所需的数据。这包括定义调用 API 函数的方式，以及将其参数从命令行参数映射到 API 参数的方式。

重要的

命令行集成并未公开所有 MySQL Shell 函数。例如，诸如此类的函数 dba.getCluster()依赖于返回一个对象，然后在进一步的操作中使用该对象。命令行集成不会公开此类操作。

同样，MySQL Shell 命令行集成不支持对象作为参数。任何具有对象类型参数的 API 函数都不能与命令行集成一起使用。对象的生命周期仅限于创建它的 MySQL Shell 调用的生命周期。由于mysqlsh在通过此 API 语法执行对象方法后立即退出，因此从 API 调用接收或传递到 API 调用的任何对象将立即超出范围。在开发要通过命令行集成公开的 MySQL Shell 插件时应考虑这一点。

从命令行调用 MySQL Shell API 函数的一般格式是：

$ mysqlsh [shell options] -- [shell_object]+ object_function [anonymous_arguments|named arguments]*

在哪里：

shell_object：指定一个全局对象，其中包含供命令行使用的公开函数。支持以空格分隔的列表中的嵌套对象。
object_function：指定最后 *shell_object*要执行的API函数。
[anonymous_arguments|named arguments]\***object_function：指定传递给调用的参数

对于大多数可用的 API，都需要一个对象，例如：

$ mysqlsh -- shell status

但对于嵌套对象，必须指明对象列表。例如，要调用公开的函数 shell.options，例如 setPersist(optionName, value)，请使用以下语法：

$ mysqlsh -- shell options set-persist defaultMode py

MySQL Shell 插件中定义的嵌套对象可能会发生类似的情况。

传递给函数的参数可以分为以下类型：

匿名参数：它们是提供给命令的原始值。例如，在以下调用中 1，one和 true是匿名参数：
```
$ mysqlsh -- object command 1 one true
```
命名参数：以--key=value. 例如，在以下调用中，--sample和 --path是命名参数：
```
$ mysqlsh -- object command 1 one true --sample=3 --path=some/path
```

鉴于参数的这种划分，从命令行集成调用 API 函数的一般格式是：

$ mysqlsh [shell options] -- object command [anonymous arguments][named arguments]

任何的顺序*anonymous arguments都很重要，因为它们是以位置方式处理的。另一方面，named arguments*可以出现在任何地方，因为它们首先被处理并与相应的参数关联。一旦命名参数被处理，匿名参数就会以位置方式处理。

5.8.2.2 定义参数

如第 5.8.2.1 节“MySQL Shell API 函数的命令行集成” 中所述，MySQL Shell 中可用的大多数 API 都期望所提供的参数具有特定的数据类型。可以使用 JSON 规范提供命令行参数中的值，但需要注意以下事项。某些终端会对数据进行自己的预处理，这可能会影响向 MySQL Shell 提供数据的方式，这取决于所使用的终端。例如：

如果发现空格，某些终端会分割参数。
分割逻辑可能会忽略连续的空格。
引号可以被删除。

MySQL Shell 解释运行它的终端提供的值，因此您必须以正确格式向终端提供数据。例如：

重要的

某些终端需要转义引号
在以下情况下应引用字符串参数：
- 它们包含空格
- 该参数用于列表参数并包含逗号
- 它们包含转义字符
API 参数可以接受不同的数据类型，并且值（基于 JSON 规范）可能是错误的数据类型。
使用 JSON 定义参数时，请引用字符串值和字符串键。避免在引用的项目之外使用空格。

以下示例说明了一些参数的处理。

要传递多个参数（每个参数一个字符串），不需要引号：
```
$ mysqlsh -- object function simple string
```
在这种情况下，MySQL Shell 获取两个参数 - 参数 1 是*simple*，参数 2 是 string。
如果您希望将这两个字符串视为单个参数，则必须将它们括在引号中，如下所示
```
$ mysqlsh -- object function "simple string"
```
在这种情况下，MySQL Shell 获得一个参数 - 参数 1 是*simple string*。
要使用包含反斜杠等字符的参数，必须将字符串加引号。否则该字符将被忽略。例如：
```
$ mysqlsh -- object function simple\tstring
```
在这种情况下，MySQL Shell 获取一个参数 - simpletstring，反斜杠字符 ( \) 已被忽略。

为了确保反斜杠字符传递到 MySQL Shell，请用引号将字符串引起来：
```
$ mysqlsh -- object function "simple\tstring"
```
在这种情况下，MySQL Shell 获得一个参数 - simple\tstring。

使用命令行集成时，定义 JSON 数组有其自身的注意事项。例如，在 MySQL Shell 交互模式中，您将 JSON 数组定义为：

["simple",123]

要在命令行集成中使用相同的数组需要特定的引用。以下示例说明了如何正确引用 JSON 数组：

尝试以与交互模式相同的方式传递 JSON 数组不起作用：
```
$ mysqlsh -- object function ["simple", 123]
```
在本例中，MySQL Shell 获取两个参数 - 参数 1 是*[simple,*，参数 2 是 123]。
在数组中不使用空格会有所帮助，但它仍然是一个无效的 JSON 数组：
```
$ mysqlsh -- object function ["simple",123]
```
在这种情况下，MySQL Shell 获得一个参数 - [simple,123]。
要创建有效的 JSON 数组，请在已引用的字符串元素中添加转义引号，例如：
```
$ mysqlsh -- object function ["\"simple\"",123]
```
在这种情况下，MySQL Shell 获得一个参数 - ["simple",123]。

要使用包含 JSON 对象的 JSON 数组，需要以类似的方式引用。例如，在 MySQL Shell 交互模式中，您定义一个包含 JSON 对象的 JSON 数组，如下所示：

{"firstName":"John","lastName":"Smith"}

以下示例说明了如何在命令行集成中正确引用同一数组：

尝试以与交互模式相同的方式传递 JSON 数组不起作用：
```
$ mysqlsh -- object function {"firstName":"John","lastName":"Smith"}
```
在本例中，MySQL Shell 获取两个参数 - 参数 1 是*firstName:John，参数 2 是lastName:Smith*。
对字符串数据使用转义引号会导致：
```
$ mysqlsh -- object function {"\"firstName\"":"\"John\"","\"lastName\"":"\"Smith\""}
```
在本例中，MySQL Shell 获取两个参数 - 参数 1 是 "firstName":"John" ，参数 2 是 "lastName":"Smith"。
要解决此问题，您需要另外引用整个 JSON 对象，以获得：
```
$ mysqlsh -- object function "{"\"firstName\"":"\"John\"","\"lastName\"":"\"Smith\""}"
```
在这种情况下，MySQL Shell 获得一个参数 - {"firstName":"John","lastName":"Smith"}。

由于显示的困难以及不同平台中终端的行为方式可能不同的事实，支持以下格式。

字符串参数

仅在以下情况下才需要引用字符串：

该值包含空格
该值本身包含逗号并且用于列表参数（以避免拆分）
该值包含转义字符
该值是一个数字，null, true，false但它应该是一个字符串。在这些情况下，应该使用内部转义引号来引用该值。换句话说，如果字符串值为“true”，则应在 CLI 调用中将其定义为“true”。

列出参数

除了 JSON 数组之外，列表参数的参数还可以提供为：

逗号分隔的值列表
单独的匿名参数

当处理列表参数时（按位置顺序），所有剩余的匿名参数都是列表的一部分。以下 MySQL Shell CLI 调用是等效的：

使用逗号分隔的值列表：

$ mysqlsh root@localhost -- util dump-schemas sakila,employees

使用连续的匿名参数：

$ mysqlsh root@localhost -- util dump-schemas sakila employees

使用 JSON 数组：

$ mysqlsh root@localhost -- util dump-schemas ["\"sakila\"","\"employees\""]

字典参数

字典是使用键值对创建的，字典参数中键的值也可以使用命名参数指定：

--key=value

以下 MySQL Shell CLI 调用说明了如何为函数中的选项参数定义 threads和键： osBucketName``util.dumpInstance()

$ mysqlsh -- util dump-instance my-dump --threads=8 --osBucketName=my-bucket

列表键

您可以通过以下方式定义字典中列表键的值：

将值定义为 JSON 数组。
将值定义为逗号分隔的值列表。
重复定义键的值。

excludeSchemas例如，在以下调用中，传递给操作的键的定义 util.dumpInstance()是等效的：

使用逗号分隔的值列表：

$ mysqlsh root@localhost -- util dump-instance --outputUrl="my-dump" --excludeSchemas=sakila,employees

使用 JSON 数组：

$ mysqlsh root@localhost -- util dump-instance --outputUrl="my-dump" --excludeSchemas=["\"sakila\"","\"employees\""]

为键定义几个值 --excludeSchemas：

$ mysqlsh root@localhost -- util dump-instance --outputUrl="my-dump" --excludeSchemas=sakila --excludeSchemas=employees

字典键

支持嵌套字典但有以下限制：

仅支持一层嵌套。
不支持内部预定义键的验证。
不支持内部预期数据类型的验证。

为嵌套字典中的键定义值的语法如下：

--key=innerKey=value

例如，定义decodeColumns 键并将其传递给util.importTable() 操作：

$ mysqlsh -- util import-table --decodeColumns=myColumn=1

附加命名参数

如上一节所示，使用语法通过命名参数支持字典参数 --key=value。还有另一种情况，参数必须指定为命名参数：在列表参数之后定义的参数。提供属于列表参数的参数的最方便方法是使用匿名参数，例如列表参数中的示例所示：

$ mysqlsh root@localhost -- util dump-schemas sakila employees

但是，此示例缺少 outputUrl参数的实参，而该参数对于util.dumpSchemas()操作是必需的。由于所有剩余的匿名参数都作为项目包含在模式列表中，因此无法将指定outputUrl为匿名参数。例如，以下内容将 不起作用：

$ mysqlsh root@localhost -- util dump-schemas sakila employees path/to/dump

在此调用中，路径path/to/dump将被解释为模式列表中的另一个项目。因此，从命令行调用函数时，在列表参数之后定义的*任何参数都必须指定为命名参数。*例如：

$ mysqlsh root@localhost -- util dump-schemas sakila employees --outputUrl=path/to/dump

5.8.2.3 数据类型处理

一般来说，参数的数据类型是使用以下标准按优先级顺序解析的：

目标参数的预期数据类型。
基于 JSON 规范的值的数据类型。
用户指定的数据类型。

最后一种情况是一种复杂（且罕见）的情况，仅适用于命名参数。例如，假设您有一个 MySQL Shell 插件函数，例如：

def set_object_attributes(variables)

其中variables是一个没有预定义值集的字典，因此它接受任何键，因此接受任何数据类型的值。streetNumber要设置以 字符串值 123命名的字符串属性，请发出：

$ mysqlsh -- plugin set-object-attributes --streetNumber=123

由于没有预期的数据类型，因此 123根据 JSON 规范，该值被解释为数值，但我们希望将其存储为字符串，而不是数字。

笔记

目前不存在这样的 API 函数，除非用户创建如上所述的插件。

5.8.2.3.1 用户数据类型

为了避免 MySQL Shell 尝试猜测输入数据类型的问题，命令行集成支持通过使用以下语法指定命名参数来强制使用特定数据类型：

--key:type=value

其中之一在哪里*type*：

比特
整数
单位
漂浮
布尔值
列表
词典
json

要将值存储为字符串，请发出：

$ mysqlsh -- plugin set-object-attributes --streetNumber:str=1234

重要的

任何命名参数都允许使用此格式，但仅当参数没有预期的数据类型时才需要此格式。如果参数有预期的数据类型，而您指定了不同的数据类型，则会引发错误。

5.8.2.3.2 数据类型解析

当您不指定数据类型时，MySQL Shell 会尝试使用以下逻辑解析数据类型。此数据解释逻辑基于 JSON 规范，但有一些 MySQL Shell 特定的添加和限制：

字符串：
- 支持双引号和单引号字符串。
- 支持十六进制，例如 where是十六进制数字。它用于以十六进制格式表示 ASCII 字符。 \x*NN*NN
- 支持垂直制表符转义字符
还可以定义以下文字：
未定义：将值定义为未定义（CLI 中实际上不需要，因此不鼓励使用）。
true/false：创建布尔值。
null：定义一个空值。

JSON 规范和上述规则未涵盖的任何值都被解释为纯字符串。

5.8.2.4 命令行帮助

--help使用(-h) CLI 参数从命令行集成调用命令时，您可以访问 MySQL Shell 联机帮助。在全局、对象和命令级别支持帮助。

笔记

内置帮助 CLI 参数不会映射到任何 API 参数，并且在 CLI 中可用的所有对象和命令中均受支持。

命令和参数的描述取自目标 API 函数的现有文档。

全局 CLI 帮助

要检索可用于 CLI 调用的全局对象列表，请使用以下语法：

$ mysqlsh -- --help

在此示例中，--启动命令的命令行集成部分。之后单独使用 --help或选项会列出此接口中可用的全局对象。-h

对象帮助

要从命令行集成访问对象帮助，请使用以下语法：

$ mysqlsh -- object --help

哪里*object*是您需要帮助的地方，例如dba全局对象。此调用显示：

对象的简要描述。
可用命令的列表及其简短描述。

要检索嵌套对象的帮助，请在--help 参数之前提供完整的对象列表。例如，要获取有关 shell.options函数的帮助，请发出：

$ mysqlsh -- shell options --help

命令帮助

要显示命令行集成中命令的帮助，请使用以下语法：

$ mysqlsh -- object command --help

此调用显示有关的详细信息 command，包括：

该命令的作用的简要描述。
调用命令的签名。
匿名参数列表以及每个参数的简要描述。
命名参数的列表、它们的预期数据类型以及解释每个参数用途的简短描述。

对于嵌套对象中的命令的情况，应在命令之前提供完整的对象列表，例如：

$ mysqlsh shell options set-persist --help

对于需要特定数据类型的参数，参数列出为：

--name=type
Brief description of the parameter.

类型信息表示参数的预期数据类型，例如：str、 int、uint、 bool、list、 float或dict。

例如参数consistent的key dump-schemas：

$ mysqlsh -- util dump-schemas --help
...
--consistent=<bool>
Enable or disable consistent data dumps. Default: true.
...

对于支持不同数据类型的参数，参数列出为：

--name[:type]=value
Brief description of the parameter.

例如操作columns的按键 util.importTable()。

$ mysqlsh -- util import-table --help
...
--columns[:<type>]=<value>
Array of strings and/or integers (default: empty array) - This...

5.8.2.5 对 MySQL Shell 插件的支持

要将第 10.3 节 “MySQL Shell 插件”与命令行集成一起使用，必须显式定义函数以支持 CLI。当 MySQL Shell 插件中定义的对象启用命令行集成时，只有启用的特定函数可用于 CLI 调用。从 MySQL Shell 版本 8.0.24 开始，当您向对象添加函数成员时，它们支持cli布尔选项。当 cli设置为时true，该功能可从命令行集成使用。这 cli选项默认为 false，因此除非专门启用，否则无法从命令行集成中使用功能。任何具有cli启用该选项的功能的对象都会导致其父对象在命令行集成中可用。

要通过命令行集成使函数可用，请在添加扩展对象成员时将该cli选项设置为。true例如：

shell.addExtensionObjectMember(object, "exampleFunction", exampleFunction,
                      {
                        brief:"Retrieves brief information",
                        details: ["Retrieves detailed information"],
                        cli: true,    
                        parameters:
                        [
                          {
                            name: "param_a",
                            type: "string",
                            brief: "param_a brief"
                          }
                        ]
                      });

然后，您可以使用exampleFunction() 命令行集成中的函数，如下所示：

mysqlsh -- customObj exampleFunction 1

如果您使用 8.0.24 之前的 MySQL Shell 版本添加了扩展对象成员，并且想要将其与命令行集成一起使用，则必须启用该选项 cli。使用 addExtensionObjectMember此处所示的方法再次添加对象成员，这次启用该cli选项。

5.9 JSON 集成

从 MySQL Shell 8.0.27 开始，您可以激活 JSON shell 模式，以帮助将 MySQL Shell 与其他可以使用其功能的应用程序集成。在此模式下，MySQL Shell 接受 JSON 文档格式的命令。

要激活 JSON shell 模式，请定义 MYSQLSH_JSON_SHELL环境变量。然后可以使用以下命令：

{"execute":\*json-string\*}

在活动 MySQL Shell 模式（JavaScript、Python 或 SQL）中执行给定代码。代码作为一个完整的单元执行，如果不完整则返回错误。
{"command":\*json-string\*}

执行给定的 MySQL Shell 命令（请参见第 3.1 节“MySQL Shell 命令”）。
{"complete":{"data":\*json-string\*[, "offset": \*uint\*}}}

根据给定数据和当前 MySQL Shell 上下文确定自动完成选项。

mysql mysql shell

「喜欢这篇文章，您的关注和赞赏是给作者最好的鼓励」

关注作者