前提条件ステップ 1: プロジェクトを設定するステップ 2: ドライバーを初期化するステップ 3: テーブルとインデックスを作成するステップ 4: ドキュメントを挿入するステップ 5: ドキュメントにクエリを実行するステップ 6: ドキュメントを更新する完全なアプリケーションの実行

Node.js 用 Amazon QLDBドライバー — クイックスタートチュートリアル

重要

サポート終了通知: 既存のお客様は、07/31/2025 のサポート終了QLDBまで Amazon を使用できます。詳細については、「Amazon Ledger QLDB を Amazon Aurora Postgre に移行するSQL」を参照してください。

このチュートリアルでは、Node.js 用の Amazon QLDBドライバーを使用してシンプルなアプリケーションを設定する方法について説明します。このガイドには、ドライバーのインストール手順と、基本的な作成、読み取り、更新、削除 (CRUD) オペレーションの短い例と JavaScript TypeScript コード例が含まれています。これらのオペレーションを完全なサンプルアプリケーションで実行する詳細な例については、「Node.js チュートリアル」を参照してください。

注記

該当する場合、一部のステップでは、サポートされている Node.js 用QLDBドライバーのメジャーバージョンごとに異なるコード例があります。

前提条件

作業を始める前に、次の操作を実行してください。

Node.js ドライバー用の「前提条件」を完了します (まだ完了していない場合)。これには、へのサインアップ AWS、開発用のプログラムによるアクセスの付与、Node.js のインストールが含まれます。
quick-start という名前の台帳を作成します。

台帳の作成方法については、「Amazon QLDB台帳の基本オペレーション」、または「コンソールの開始方法」の「ステップ 1: 新しい台帳を作成する」を参照してください。

を使用している場合は TypeScript、以下のセットアップ手順も実行する必要があります。

をインストールするには TypeScript

TypeScript パッケージをインストールします。QLDB ドライバーは TypeScript 3.8.x で実行されます。
```
$ npm install --global typescript@3.8.0
```
パッケージをインストールしたら、次のコマンドを実行して、 TypeScript コンパイラがインストールされていることを確認します。
```
$ tsc --version
```

次の手順でコードを実行するには、まず TypeScript 次のようにファイルを実行可能 JavaScript コードにトランスパイルする必要があることに注意してください。


$ tsc app.ts; node app.js

ステップ 1: プロジェクトを設定する

まず、Node.js プロジェクトを設定します。

アプリケーション用のフォルダを作成します。
```
$ mkdir myproject
$ cd myproject
```
プロジェクトを初期化するには、次の npm コマンドを入力し、設定中に表示される質問に回答します。ほとんどの質問にはデフォルトを使用できます。
```
$ npm init
```
Node.js 用の Amazon QLDBドライバーをインストールします。
- バージョン 3.x の使用
```
$ npm install amazon-qldb-driver-nodejs --save
```
- バージョン 2.x の使用
```
$ npm install amazon-qldb-driver-nodejs@2.2.0 --save
```
- バージョン 1.x の使用
```
$ npm install amazon-qldb-driver-nodejs@1.0.0 --save
```

ドライバーのピア依存関係をインストールします。

バージョン 3.x の使用


$ npm install @aws-sdk/client-qldb-session --save
$ npm install ion-js --save
$ npm install jsbi --save

バージョン 2.x または 1.x の使用


$ npm install aws-sdk --save
$ npm install ion-js@4.0.0 --save
$ npm install jsbi@3.1.1 --save

に JavaScript、 app.jsにという名前の新しいファイルapp.tsを作成します TypeScript。

次に、次のステップのコード例を段階的に追加して、いくつかの基本的なCRUDオペレーションを試します。または、 step-by-step チュートリアルをスキップして、代わりに完全なアプリケーションを実行することもできます。

ステップ 2: ドライバーを初期化する

quick-start という名前の台帳に接続するドライバーのインスタンスを初期化します。次のコードを app.js または app.ts ファイルに追加します。

注記

このコード例では、us-east-1 台帳を作成した AWS リージョンを使用します。
簡単にするために、このガイドの残りのコード例では、次のバージョン 1.x の例で指定しているように、デフォルト設定のドライバーを使用しています。その代わりに、RetryConfig をカスタマイズすることで、独自のドライバーインスタンスを使用することもできます。

注記

このコード例では、us-east-1 台帳を作成した AWS リージョンを使用します。
バージョン 2.x には QldbDriver を初期化する RetryConfig という新しいオプションパラメータが導入されています。
簡単にするために、このガイドの残りのコード例では、次のバージョン 1.x の例で指定しているように、デフォルト設定のドライバーを使用しています。その代わりに、RetryConfig をカスタマイズすることで、独自のドライバーインスタンスを使用することもできます。
このコード例では、Keep-Alive オプションを設定して、既存の接続を再利用するドライバーを初期化します。詳細については、Node.js ドライバー向けの「セットアップの推奨事項」を参照してください。

注記

AWS_REGION 環境変数を設定して、リージョンを指定できます。詳細については、「AWS SDK for JavaScript デベロッパーガイド」の「AWS リージョンの設定」を参照してください。

ステップ 3: テーブルとインデックスを作成する

次のコード例は、CREATE TABLE ステートメントと CREATE INDEX ステートメントの実行方法を示しています。

次の関数を追加して People という名前のテーブルを作成します。

People テーブルの firstName フィールドのインデックスを作成する、以下の関数を追加します。インデックスは、クエリのパフォーマンスを最適化し、オプティミスティック同時実行制御 (OCC) の競合例外を制限するのに役立ちます。
JavaScript
```
async function createIndex(txn) {
    await txn.execute("CREATE INDEX ON People (firstName)");
}
```
TypeScript
```
async function createIndex(txn: TransactionExecutor): Promise<void> {
    await txn.execute("CREATE INDEX ON People (firstName)");
}
```

main 関数で最初に createTable を呼び出し、次に createIndex を呼び出します。

コードを実行して、テーブルとインデックスを作成します。
JavaScript
```
$ node app.js
```
TypeScript
```
$ tsc app.ts; node app.js
```

ステップ 4: ドキュメントを挿入する

次のコード例は、INSERT ステートメントの実行方法を示しています。QLDB は、PartiQLクエリ言語 (SQL互換) と Amazon Ion データ形式 ( のスーパーセット) をサポートしていますJSON。

次の関数を追加して People テーブルにドキュメントを挿入します。
JavaScript
```
async function insertDocument(txn) {
    const person = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}
```
TypeScript
```
async function insertDocument(txn: TransactionExecutor): Promise<void> {
    const person: Record<string, any> = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}
```
この例では、疑問符 (?) を変数プレースホルダーとして使用して、ドキュメント情報をステートメントに渡します。execute メソッドは、Amazon Ion 型と Node.js ネイティブ型の両方の値をサポートします。
ヒント
1 つの INSERT ステートメントを使用して複数のドキュメントを挿入するために、次のように型 list のパラメータをステートメントに渡すことができます。
```
// people is a list
txn.execute("INSERT INTO People ?", people);
```
リストを渡すときには、変数プレースホルダー (?) を二重山括弧 (<<...>>) で囲まないでください。マニュアルの PartiQL ステートメントでは、二重山括弧はバッグと呼ばれる順序付けされていないコレクションを表します。

main 関数で、createTable と createIndex の呼び出しを削除し、insertDocument への呼び出しを追加します。

ステップ 5: ドキュメントにクエリを実行する

次のコード例は、SELECT ステートメントの実行方法を示しています。

次の関数を追加して People テーブルのドキュメントにクエリを実行します。

main 関数で、次の fetchDocuments への呼び出しを、insertDocument への呼び出しの後に追加します。

ステップ 6: ドキュメントを更新する

次のコード例は、UPDATE ステートメントの実行方法を示しています。

次の関数を追加し、lastName を "Stiles" に変更して People テーブルのドキュメントを更新します。

main 関数で、次の updateDocuments への呼び出しを、fetchDocuments への呼び出しの後に追加します。次に、fetchDocuments を再度呼び出して、更新された結果を確認します。

コードを実行して、ドキュメントの挿入、クエリ、更新を行います。
JavaScript
```
$ node app.js
```
TypeScript
```
$ tsc app.ts; node app.js
```

完全なアプリケーションの実行

次のコード例は、app.js と app.ts の完全なバージョンを示しています。上のステップを個別に実行する代わりに、このコードを最初から最後まで実行することもできます。このアプリケーションは、という名前の台帳に対するいくつかの基本的なCRUDオペレーションを示していますquick-start。

注記

このコードを実行する前に、quick-start 台帳に People という名前のアクティブなテーブルが存在しないことを確認してください。

JavaScript


const qldb = require('amazon-qldb-driver-nodejs');

async function createTable(txn) {
    await txn.execute("CREATE TABLE People");
}

async function createIndex(txn) {
    await txn.execute("CREATE INDEX ON People (firstName)");
}

async function insertDocument(txn) {
    const person = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}

async function fetchDocuments(txn) {
    return await txn.execute("SELECT firstName, age, lastName FROM People WHERE firstName = ?", "John");
}

async function updateDocuments(txn) {
    await txn.execute("UPDATE People SET lastName = ? WHERE firstName = ?", "Stiles", "John");
}

async function main() {
    // Use default settings
    const driver = new qldb.QldbDriver("quick-start");

    var resultList = await driver.executeLambda(async (txn) => {
        console.log("Create table People");
        await createTable(txn);
        console.log("Create index on firstName");
        await createIndex(txn);
        console.log("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        await fetchDocuments(txn);
        console.log("Update document");
        await updateDocuments(txn);
        console.log("Fetch document after update");
        var result = await fetchDocuments(txn);
        return result.getResultList();
    });

    // Pretty print the result list
    console.log("The result List is ", JSON.stringify(resultList, null, 2));
    driver.close();
}

main();

TypeScript


import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";

async function createTable(txn: TransactionExecutor): Promise<void> {
    await txn.execute("CREATE TABLE People");
}

async function createIndex(txn: TransactionExecutor): Promise<void> {
    await txn.execute("CREATE INDEX ON People (firstName)");
}

async function insertDocument(txn: TransactionExecutor): Promise<void> {
    const person: Record<string, any> = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}

async function fetchDocuments(txn: TransactionExecutor): Promise<dom.Value[]> {
    return (await txn.execute("SELECT firstName, age, lastName FROM People WHERE firstName = ?", "John")).getResultList();
}

async function updateDocuments(txn: TransactionExecutor): Promise<void> {
    await txn.execute("UPDATE People SET lastName = ? WHERE firstName = ?", "Stiles", "John");
};

async function main(): Promise<void> {
    // Use default settings
    const driver: QldbDriver = new QldbDriver("quick-start");

    const resultList: dom.Value[] = await driver.executeLambda(async (txn: TransactionExecutor) => {
        console.log("Create table People");
        await createTable(txn);
        console.log("Create index on firstName");
        await createIndex(txn);
        console.log("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        await fetchDocuments(txn);
        console.log("Update document");
        await updateDocuments(txn);
        console.log("Fetch document after update");
        return await fetchDocuments(txn);
    });

    // Pretty print the result list
    console.log("The result List is ", JSON.stringify(resultList, null, 2));
    driver.close();
}

if (require.main === module) {
    main();
}

完全なアプリケーションを実行するには、次のコマンドを入力します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

Node.js ドライバー

クックブックリファレンス