QLDB シェルを使用した Amazon QLDB へのアクセス (データ API のみ) - Amazon Quantum Ledger Database (Amazon QLDB)
前提条件シェルのインストールシェルの呼び出しシェルパラメータコマンドリファレンス個別のステートメントの実行トランザクションの管理シェルの終了例

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

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

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

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

注記

Amazon QLDB シェルは、qldb-session トランザクションデータ API のみをサポートしています。この API は、QLDB 台帳に対して PartiQL ステートメントを実行するためにのみ使用します。

コマンドラインインターフェイスを使用して qldb 管理 API オペレーションとやり取りするには、「AWS CLI (管理 API のみ)を使用した Amazon QLDB へのアクセス」を参照してください。

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

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

前提条件

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

  1. 「Amazon QLDB へのアクセス」にある AWS の設定手順に従います。これには以下が含まれます。

    1. AWS にサインアップする。

    2. QLDB の適切なアクセス許可を持つユーザーを作成します。

    3. 開発に必要なプログラムへのアクセスを提供します。

  2. AWS の認証情報とデフォルトの AWS リージョン を設定します。指示については、「AWS Command Line Interface ユーザーガイド」の「設定の基本」を参照してください。

    利用可能なリージョンの完全なリストについては、「AWS 全般のリファレンス」の「Amazon QLDB エンドポイントとクォータ」を参照してください。

  3. STANDARD アクセス許可モードの台帳では、適切なテーブルで PartiQL ステートメントを実行するために、アクセス許可を付与する IAM ポリシーを作成します。これらのポリシーを作成する方法については、「Amazon 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]
FLAGS
-h, --help

ヘルプ情報を表示します。

-v, --verbose

ログ記録の詳細を設定します。デフォルトの場合、シェルはエラーのみをログに記録します。詳細レベルを上げるには、この引数を繰り返します (例: -vv)。最高レベルは -vvv であり、これは trace 詳細レベルに相当します。

-V, --version

バージョン情報を表示します。

OPTIONS
-l, --ledger LEDGER_NAME

接続先の台帳の名前です。config.ion ファイルに default_ledger が設定されていない場合、このシェルパラメータが必要です。このファイルでは、リージョンなどの追加オプションを設定できます。

-c, --config CONFIG_FILE

シェル設定オプションを定義できるファイルです。形式の詳細と、設定オプションの詳細なリストについては、GitHub の README.md ファイルを参照してください。

-f, --format ion|table

クエリ結果の出力形式です。デフォルトは ion です。

-p, --profile PROFILE

認証に使用する AWS 認証情報プロファイルの場所です。

指定しない場合、シェルは、~/.aws/credentials にあるデフォルトの AWS プロファイルを使用します。

-r, --region REGION_CODE

接続先の QLDB 台帳の AWS リージョン コードです。例: us-east-1。

指定しない場合、シェルは、AWS プロファイルで指定されたデフォルトの AWS リージョン に接続します。

-s, --qldb-session-endpoint QLDB_SESSION_ENDPOINT

接続先の qldb-session API エンドポイントです。

QLDB リージョンとエンドポイントの完全なリストについては、「AWS 全般のリファレンス」の「Amazon QLDB エンドポイントとクォータ」を参照してください。

コマンドリファレンス

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

シェルキー
キー 機能の説明
Enter ステートメントを実行します。

Escape+Enter (macOS、Linux)

Shift+Enter (Windows)

複数の行にまたがるステートメントを入力するために、新しい行を作成します。複数行の入力テキストをコピーして、シェルに貼り付けることもできます。

macOS で、Escape ではなく Option をメタキーとしてセットアップする手順については、OS X Daily サイトを参照してください。
Ctrl+C 現在のコマンドをキャンセルします。
Ctrl+D ファイルの終了 (EOF) を通知し、シェルの現在のレベルを終了します。アクティブなトランザクションでない場合は、シェルを終了します。アクティブなトランザクションの場合、トランザクションを中断します。
シェルデータベースコマンド
コマンド 機能の説明
help ヘルプ情報を表示します。
begin トランザクションを開始します。
start transaction
commit トランザクションを台帳のジャーナルにコミットします。
abort トランザクションを停止し、行った変更を拒否します。
exit シェルを終了します。
quit
注記

すべての QLDB シェルコマンドで、大文字と小文字の区別がありません。

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

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

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

トランザクションの管理

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

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

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

  1. トランザクションを開始するには、begin コマンドを入力します。

    qldb> begin

    トランザクションを開始すると、次のコマンドプロンプトがシェルに表示されます。

    qldb *>

  2. その後、入力した各ステートメントが、同じトランザクションで実行されます。

    • 例えば、単一のステートメントを次のように実行できます。

      qldb *> SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'

      Enter を押すと、ステートメントの結果がシェルに表示されます。

    • 複数のステートメントまたはコマンドを、次のようにセミコロン (;) の記号で区切って入力することもできます。

      qldb *> SELECT * FROM Vehicle WHERE VIN = '1N4AL11D75C109151'; commit

  3. トランザクションを終了するには、次のコマンドのいずれかを入力します。

    • commit コマンドを入力すると、トランザクションが台帳のジャーナルにコミットされます。

      qldb *> commit

    • abort コマンドを入力すると、トランザクションが停止され、行った変更が拒否されます。

      qldb *> abort
transaction was aborted

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

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 シェルは、この例の各 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