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 オペレーションについては、「」を参照してください。を使用した Amazon QLDB へのアクセスAWS CLI(管理 API のみ)

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

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

前提条件

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

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

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

    2. QLDB の適切なアクセス許可を持つ AWS Identity and Access Management (IAM) ユーザーを作成します。

    3. 開発用の IAM アクセスキーを取得します。

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

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

  3. STANDARD アクセス許可モードの台帳では、適切なテーブルで PartiQL ステートメントを実行するために、アクセス許可を付与する IAM ポリシーを作成します。これらのポリシーを作成する方法については、「Amazon QLDB の標準アクセス許可モードの開始方法」を参照してください。

シェルのインストール

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

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]

-h, --help

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

-v, --verbose

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

-V, --version

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

OPTIONS

-l, --ledger LEDGER_NAME

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

-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 $

[Example] (例)

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