先决条件安装 Shell 调用 Shell Shell 参数命令参考运行单独语句管理事务退出 Shell 示例

使用 QLDB Shell 访问Amazon QLDB (仅限数据 API)

Amazon QLDB 提供了一个命令行 Shell，用于与事务数据 API 进行交互。使用 QLDB Shell，您可以对分类账数据运行 PartiQL语句。

这个 Shell 的最新版本是用 Rust 编写的，在默认main分支上的 GitHub 存储库awslabs/amazon-qldb-shell中是开源的。Python 版本 (v1) 也仍然可以在 master 分支的同一个存储库中使用。

注意

Amazon QLDB Shell 仅支持qldb-session事务数据 API。此 API 仅用于在 QLDB 分类账上运行 PartiQL 语句。

要使用命令行界面与 qldb 管理 API 操作进行交互，请参阅使用 AWS CLI （仅限管理 API）访问亚马逊 QLDB。

此工具不会整合至应用程序中或用于生产目的。该工具旨在让您快速试验 QLDB 和 PartiQL。

以下各节介绍如何开始使用 QLDB Shell。

先决条件

开始使用 QLDB Shell之前，您必须执行以下操作：

按照访问 Amazon QLDB 中的 AWS 的设置说明进行操作。这包括以下这些：
1. 注册AWS。
2. 创建具有适当 QLDB 权限的用户。
3. 授权以编程方式访问开发。
设置您的AWS凭据和默认凭据AWS 区域。有关说明，请参阅 AWS Command Line Interface 用户指南中的配置基础。

有关可用区域的完整列表，请参阅 AWS 一般参考 中的 Amazon QLDB 端点和限额。
在分类账的 STANDARD 权限模式下，您必须创建 IAM 策略，以授予在适当表格上运行 PartiQL 语句的权限。要了解如何创建这些策略，请参阅请参阅《Amazon QLDB 开发人员》中的标准权限模式入门。

安装 Shell

要安装 QLDB Shell 的最新版本，请参阅 GitHub 中的README.md。QLDB 在 GitHub 存储库的发布部分提供了适用于 Linux、macOS 和 Windows 的预建二进制文件。

对于 macOS，Shell 与aws/tap Homebrew 选项卡集成。若要使用 Homebrew 在 macOS 上安装 Shell，请运行以下命令。


$ xcode-select --install # Required to use Homebrew
$ brew tap aws/tap # Add AWS as a Homebrew tap
$ brew install qldbshell

配置

安装后，Shell 会加载初始化 $XDG_CONFIG_HOME/qldbshell/config.ion 期间位于的默认配置文件。在 Linux 和 macOS，此文件通常位于 ~/.config/qldbshell/config.ion。如果这样的文件不存在，Shell 将按默认设置运行。

安装后可以手动创建 config.ion 文件。此配置文件采用 Amazon Ion 数据格式。以下是最小 config.ion 文件的示例。


{
  default_ledger: "my-example-ledger"
}

如果配置文件中未设置default_ledger，则在调用 Shell 时必须使用--ledger参数。有关配置选项的完整列表，请参阅 GitHub 的 README.md 文件。

调用 Shell

要在命令行终端上为特定分类账调用 QLDB Shell，请运行以下命令。用你的分类账名称替换my-example-ledger 。


$ qldb --ledger my-example-ledger

此命令连接至您的默认AWS 区域。要明确指定区域，您可以使用 --region 或 --qldb-session-endpoint 参数运行命令，如下一节所述。

调用 qldb Shell 会话后，您可输入以下类型的输入：

Shell 命令
在单独的事务中采用单个 Partiql 语句
单个事务中包含多个 PartiQL 语句

Shell 参数

要查看调用 Shell 的可用标志和选项的完整列表，请按如下方式运行带有 --help 标志的 qldb 命令。


$ qldb --help

以下是 qldb 命令的一些键标和选项。您可以添加这些可选参数以覆盖AWS 区域、凭据配置文件、端点、结果格式和其他配置选项。

用量


$ qldb [FLAGS] [OPTIONS]

FLAGS

-h, --help: 打印帮助信息。
-v, --verbose: 配置日志详细程度。默认情况下，Shell 程序仅记录错误。要提高详细程度，请重复此参数 (例如-vv)。最高等级为对应于trace的-vvv。
-V, --version: 打印版本信息。

OPTIONS

-l, --ledger LEDGER_NAME

要连接的分类账的名称。如果default_ledger未在您的config.ion文件中设置，则其为 Shell 必填参数。在此文件中，您可以设置其他选项，如区域。

-c, --config CONFIG_FILE

可在其中定义任何 Shell 配置选项的文件。有关格式详细信息和配置选项的完整列表，请参见 GitHub 上的 README.md 文件。

-f, --format ion|table

查询结果的输出格式。默认为 ion。

-p, --profile PROFILE

用于身份验证的 AWS 凭据配置文件的位置。

如果未提供，Shell 可使用您的默认AWS配置文件，该配置文件位于~/.aws/credentials。

-r, --region REGION_CODE

要连接的 QLDB 分类账AWS 区域代码。例如：us-east-1。

如果未提供，则 Shell 将连接至您的AWS配置文件中指定的默认AWS 区域。

-s, --qldb-session-endpoint QLDB_SESSION_ENDPOINT

用于连接的 qldb-session API 端点。

有关可用 QLDB 区域和端点的完整列表，请参阅 AWS 一般参考中的 Amazon S3 端点和限额。

命令参考

调用 qldb会话后，Shell 支持以下密钥和数据库命令：

Shell 秘钥
键	函数描述
Enter	运行语句。
Escape+Enter (macOS, Linux) Shift+Enter (Windows)	开始新行，输入一条跨越多行的语句。您也可以复制多行输入文本，然后将其粘贴至 Shell。有关在 macOS 中设置Option而非Escape作为元密钥的说明，请参阅OS X Daily网站。
Ctrl+C	取消当前命令。
Ctrl+D	发出文件结束信号 (EOF) 并退出 Shell 的当前级别。如不在活动事务中，则退出 Shell。在活动事务中，请中止该事务。

Shell 数据库命令
命令	函数描述
`help`	显示帮助信息。
`begin`	开始事务。
`start transaction`	开始事务。
`commit`	将您的事务提交至分类账日志账中。
`abort`	停止您的事务，并拒绝您所做的任何更改。
`exit`	退出 Shell。
`quit`	退出 Shell。

注意

所有 QLDB Shell 命令均不区分大小写。

运行单独语句

除了 README.md 中列出的数据库命令和 Shell 元命令外，Shell 程序会将您输入的每条命令解释为单独的 PartiQL 语句。默认情况下，Shell 会启用auto-commit模式。此模式为可配置。

在auto-commit模式下，Shell 会在自己的事务中隐式运行每条语句，如果未发现错误，则自动提交事务。这意味着您不必在每次运行语句时都手动运行start transaction (或 begin) 和 commit。

管理事务

或者，QLDB Shell 允许您手动控制事务。您可在事务中以交互方式运行多个语句，也可以通过按顺序批处理命令和语句来以非交互方式运行多个语句。

交互式事务

若要运行交互式事务，请执行以下步骤。

要开始事务，请输入 begin 命令。
```
qldb> begin
```
开始事务后，Shell 将显示以下命令提示符。
```
qldb *>  
```
然后，您输入的每条事务都在同一笔事务中运行。
- 例如，您可按以下方式运行单个语句。
```
qldb *> SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'
```
  按下Enter后，Shell 会显示语句的结果。
- 您也可以输入多个由分号 (;) 分隔符分隔的语句或者命令，如下所示。
```
qldb *> SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'; commit
```
若要结束事务，请输入以下命令之一。
- 输入commit命令将您的事务提交至分类账日志账中。
```
qldb *> commit
```
- 输入abort命令，以停止您的事务并拒绝您所做的任何更改。
```
qldb *> abort
transaction was aborted
```

事务超时限制

交互式事务遵守 QLDB 事务超时限制。如果您未在事务启动后的 30 秒内提交此事务，QLDB 会自动使该事务过期，并拒绝事务期间所做的任何更改。

然后，Shell 不显示语句结果，而是显示一条过期错误消息并返回到普通的命令提示符。要重试，必须再次输入 begin 命令才能开始新的事务。

transaction failed after 1 attempts, last error: communication failure: Transaction 2UMpiJ5hh7WLjVgEiMLOoO has expired

非交互式事务

您可以按以下顺序对命令和语句进行批处理，从而运行包含多条语句的完整事务。


qldb> begin; SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'; SELECT * FROM Person p, DriversLicense l WHERE p.GovId = l.LicenseNumber; commit

必须用分号 (;) 分隔符分隔每条命令与语句。如果事务中的任何语句无效，则 Shell 会自动拒绝该事务。Shell 不会继续处理您随后输入的任何语句项。

您还可设置多笔事务。


qldb> begin; statement1; commit; begin; statement2; statement3; commit

与前面的示例类似的是，如果事务失败，Shell 将不会继续处理您输入的任何后续事务或语句。

如果您不结束事务，Shell 会切换至交互模式，并提示您输入下一个命令或语句。


qldb> begin; statement1; commit; begin
qldb *>

退出 Shell

要退出当前 qldb Shell 会话，请输入exit或quit命令，或者在 Shell 不在事务中时使用键盘快捷键Ctrl+D。


qldb> exit
$


qldb> quit
$

示例

有关在 QLDB 中编写 PartiQL 语句的信息，请参阅Amazon QLDB PartiQL 参考。

以下示例显示基本命令常见序列。

注意

QLDB Shell 程序在自己的事务中运行本示例中的每条 PartiQL 语句。

此示例假设分类账 test-ledger 已经存在且处于活动状态。


$ qldb --ledger test-ledger --region us-east-1

qldb> CREATE TABLE TestTable
qldb> INSERT INTO TestTable `{"Name": "John Doe"}`
qldb> SELECT * FROM TestTable
qldb> DROP TABLE TestTable
qldb> exit

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

使用 AWS CLI （仅限管理 API）

使用 API