本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
使用 QLDB Shell 访问Amazon QLDB(仅限数据 API)
重要
终止支持通知:现有客户将能够使用 Amazon QLDB,直到 2025 年 7 月 31 日终止支持。有关更多详细信息,请参阅将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL
Amazon QLDB 提供了一个命令行 Shell,用于与事务数据 API 进行交互。使用 QLDB Shell,您可以对分类账数据运行 PartiQL语句。
这个 shell 的最新版本是用 Rust 编写的,在默认分支的 awslabs/ GitHubmain
Python 版本(v1)也仍然可以在 master
分支的同一个存储库中使用。
注意
Amazon QLDB Shell 仅支持qldb-session
事务数据 API。此 API 仅用于在 QLDB 分类账上运行 PartiQL 语句。
要使用命令行界面与 qldb
管理 API 操作进行交互,请参阅 使用 AWS CLI (仅限管理 API)访问亚马逊 QLDB。
此工具不会整合至应用程序中或用于生产目的。该工具旨在让您快速试验 QLDB 和 PartiQL。
以下各节介绍如何开始使用 QLDB Shell。
先决条件
开始使用 QLDB Shell之前,您必须执行以下操作:
-
按照中的 AWS 设置说明进行操作访问 Amazon QLDB。这包括以下这些:
-
报名参加 AWS.
-
创建具有适当 QLDB 权限的用户。
-
授权以编程方式访问开发。
-
-
设置您的 AWS 凭据和默认凭证 AWS 区域。有关说明,请参阅 AWS Command Line Interface 用户指南中的配置基础。
有关可用区域的完整列表,请参阅 AWS 一般参考 中的 Amazon QLDB 端点和限额。
-
在分类账的
STANDARD
权限模式下,您必须创建 IAM 策略,以授予在适当表格上运行 PartiQL 语句的权限。要了解如何创建这些策略,请参阅 请参阅《Amazon QLDB 开发人员》中的标准权限模式入门。
安装 Shell
要安装最新版本的 QLDB 外壳,请参阅上的 README.md 文件。
对于 macOS,Shell 与aws/tap
Homebrew
$
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
参数。有关配置选项的完整列表,请参阅上的 README.md
调用 Shell
要在命令行终端上为特定分类账调用 QLDB Shell,请运行以下命令。my-example-ledger
用您的账本名称替换。
$
qldb --ledger
my-example-ledger
此命令连接到您的默认命令 AWS 区域。要明确指定区域,您可以使用 --region
或 --qldb-session-endpoint
参数运行命令,如下一节所述。
调用 qldb
Shell 会话后,您可输入以下类型的输入:
Shell 参数
要查看调用 Shell 的可用标志和选项的完整列表,请按如下方式运行带有 --help
标志的 qldb
命令。
$
qldb --help
以下是 qldb
命令的一些键标和选项。您可以添加这些可选参数来覆盖凭证配置文件、端点、结果格式和其他配置选项。 AWS 区域
用法
$
qldb [FLAGS]
[OPTIONS]
FLAGS
-h
,--help
-
打印帮助信息。
-v
,--verbose
-
配置日志详细程度。默认情况下,Shell 程序仅记录错误。要提高详细程度,请重复此参数(例如
-vv
)。最高等级为对应于trace
的-vvv
。 -V
,--version
-
打印版本信息。
选项
-l
,--ledger
LEDGER_NAME
-
要连接的分类账的名称。如果
default_ledger
未在您的config.ion
文件中设置,则其为 Shell 必填参数。在此文件中,您可以设置其他选项,如区域。 -c
,--config
CONFIG_FILE
-
可在其中定义任何 Shell 配置选项的文件。有关格式的详细信息和配置选项的完整列表,请参阅上的 README.md
文件。 GitHub -f
,--format
ion|table
-
查询结果的输出格式。默认为
ion
。 -p
,--profile
PROFILE
-
用于身份验证的 AWS 凭证配置文件的位置。
如果未提供,shell 将使用您的默认 AWS 配置文件,该配置文件位于
~/.aws/credentials
。 -r
,--region
REGION_CODE
-
要 AWS 区域 连接的 QLDB 账本的代码。例如:
us-east-1
。如果未提供,则 shell 将连接到您的 AWS 配置文件中指定的默认值 AWS 区域 。
-s
,--qldb-session-endpoint
QLDB_SESSION_ENDPOINT
-
用于连接的
qldb-session
API 端点。有关可用 QLDB 区域和端点的完整列表,请参阅 AWS 一般参考中的 Amazon S3 端点和限额。
命令参考
调用 qldb
会话后,Shell 支持以下密钥和数据库命令:
键 | 函数描述 |
---|---|
Enter | 运行语句。 |
Escape+Enter(macOS, Linux) Shift+Enter(Windows) |
开始新行,输入一条跨越多行的语句。您也可以复制多行输入文本,然后将其粘贴至 Shell。 有关在 macOS 中设置Option而非Escape作为元密钥的说明,请参阅OS X Daily |
Ctrl+C | 取消当前命令。 |
Ctrl+D | 发出文件结束信号(EOF)并退出 Shell 的当前级别。如不在活动事务中,则退出 Shell。在活动事务中,请中止该事务。 |
命令 | 函数描述 |
---|---|
help |
显示帮助信息。 |
begin |
开始事务。 |
start transaction |
|
commit |
将您的事务提交至分类账日志账中。 |
abort |
停止您的事务,并拒绝您所做的任何更改。 |
exit |
退出 Shell。 |
quit |
注意
所有 QLDB Shell 命令均不区分大小写。
运行单独语句
除了 README.mdauto-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