QLDB シェルを使用した Amazon QLDB へのアクセス (データ API のみ)

Amazon QLDB には、トランザクションデータ API とやり取りするためのコマンドラインシェルが用意されています。QLDB シェルを使用すると、台帳データに対して PartiQL ステートメントを実行できます。

このシェルの最新バージョンは Rust で記述されており、GitHub リポジトリのデフォルト main ブランチの awslabs/amazon-qldb-shell でオープンソースとして公開されています。Python バージョン (v1) も、master ブランチの同じリポジトリに用意されています。

このツールは、アプリケーションに組み込んだり、本番環境で採用したりすることを意図したものではありません。このツールの目的は、QLDB と PartiQL を迅速に実験できるようにすることです。

以下のセクションでは、QLDB シェルの使用を開始する方法について説明します。

前提条件

QLDB シェルを開始する前に、以下の操作を実行する必要があります。

シェルのインストール

QLDB シェルの最新バージョンをインストールするには、GitHub の README.md ファイルを参照してください。QLDB では、GitHub リポジトリの「Releases」セクションにある、Linux、macOS、Windows 向け事前構築済みファイルを利用できます。

macOS の場合、aws/tap Homebrew タップを使用して、シェルを統合します。Homebrew を使用してシェルを macOS にインストールするには、次のコマンドを実行します。

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

設定

インストール後、シェルは $XDG_CONFIG_HOME/qldbshell/config.ion にあるデフォルト設定ファイルを、初期化中にロードします。Linux と macOS の場合、このファイルは通常 ~/.config/qldbshell/config.ion にあります。そのようなファイルが存在しない場合、シェルはデフォルト設定で実行されます。

インストール後、config.ion ファイルを手動で作成できます。この設定ファイルでは、Amazon Ion データ形式が使用されます。次は、最小の config.ion ファイルの例です。

{
  default_ledger: "my-example-ledger"
}

設定ファイルに default_ledger が設定されていない場合、シェルを呼び出す際に --ledger パラメータが必要です。設定オプションの詳細なリストについては、GitHub の README.md ファイルを参照してください。

シェルの呼び出し

コマンドラインターミナルで特定の台帳に対して QLDB シェルを呼び出すには、以下のコマンドを実行します。my-example-ledger を台帳名に置き換えます。

$ qldb --ledger my-example-ledger

このコマンドは、デフォルトに接続します AWS リージョン。リージョンを明示的に指定するには、次のセクションで説明するように、--region または --qldb-session-endpoint パラメータを指定してコマンドを実行できます。

qldb シェルセッションを呼び出した後、次のインプットタイプで入力できます。

シェルパラメータ

シェルの呼び出しに使用できるフラグとオプションの詳細なリストを確認するには、次のように、--help フラグを使用して qldb コマンドを実行します。

$ qldb --help

qldb コマンドのキーフラグとオプションのいくつかを次に示します。これらのオプションパラメータを追加して AWS リージョン、、認証情報プロファイル、エンドポイント、結果形式、およびその他の設定オプションを上書きできます。

使用方法

$ qldb [FLAGS] [OPTIONS]

コマンドリファレンス

qldb セッションを呼び出すと、シェルでは、次のキーとデータベースコマンドがサポートされます。

個別のステートメントの実行

README.md にリストされているデータベースコマンドとシェルメタコマンドを除き、シェルは、入力された各コマンドを個別の PartiQL ステートメントとして解釈します。デフォルトの場合、シェルでは、auto-commit モードが有効になります。このモードは設定可能です。

auto-commit モードの場合、シェルは、独自のトランザクションで各ステートメントを暗黙的に実行し、エラーがない場合はトランザクションを自動的にコミットします。つまり、ステートメントの実行のたびに、start transaction (または begin) を実行して、手動で commit する必要はありません。

トランザクションの管理

QLDB シェルでは、トランザクションを手動で制御することもできます。トランザクション内の複数のステートメントは、インタラクティブに実行することも、コマンドとステートメントを順番にバッチ処理して非インタラクティブに実行することもできます。

インタラクティブトランザクション

インタラクティブトランザクションを実行するには、次の手順に従います。

トランザクションタイムアウト制限

QLDB のトランザクションタイムアウト制限に準拠するには、トランザクションをインタラクティブに行います。開始後 30 秒以内にトランザクションをコミットしない場合、QLDB ではトランザクションの有効期限が自動的に切れ、トランザクション中に行った変更がすべて拒否されます。

その場合、ステートメントの結果ではなく、有効期限切れのエラーメッセージが表示され、シェルは通常のコマンドプロンプトに戻ります。再試行するには、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

各コマンドとステートメントは、セミコロン (;) の記号で区切る必要があります。トランザクション内のいずれかのステートメントが有効でない場合、シェルはトランザクションを自動的に拒否します。入力した後続のステートメントを続行しません。

複数のトランザクションも設定できます。

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

前の例と同様に、トランザクションが失敗すると、シェルは、入力した後続のトランザクションまたはステートメントを処理しません。

トランザクションを終了しない場合、シェルがインタラクティブモードに切り替わり、次のコマンドまたはステートメントの入力が求められます。

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

シェルの終了

現在の qldb シェルセッションを終了するには、そのシェルでトランザクションを実行していないときに、exit または quit コマンドを入力するか、キーボードショートカットの Ctrl+D を使用します。

qldb> exit
$ 

qldb> quit
$ 

例

QLDB での PartiQL ステートメントの記述については、「Amazon QLDB の PartiQL リファレンス」を参照してください。

$ 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