QLDBAmazon-Treiber für Node.js — Schnellstartanleitung - Amazon Quantum Ledger-Datenbank (AmazonQLDB)
VoraussetzungenSchritt 1: Einrichten des Projekts Schritt 2: Initialisieren des TreibersSchritt 3: Erstellen einer Tabelle und eines IndexSchritt 4: Einfügen eines DokumentsSchritt 5: Abfragen des DokumentsSchritt 6: Aktualisieren des DokumentsAusführen der vollständigen Anwendung

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

QLDBAmazon-Treiber für Node.js — Schnellstartanleitung

Wichtig

Hinweis zum Ende des Supports: Bestandskunden können Amazon QLDB bis zum Ende des Supports am 31.07.2025 nutzen. Weitere Informationen finden Sie unter Migrieren eines Amazon QLDB Ledgers zu Amazon Aurora SQL Postgre.

In diesem Tutorial erfahren Sie, wie Sie mit dem QLDB Amazon-Treiber für Node.js eine einfache Anwendung einrichten. Dieses Handbuch enthält Schritte zur Installation des Treibers sowie kurze TypeScript Codebeispiele für grundlegende Erstellungs JavaScript -, Lese-, Aktualisierungs- und Löschvorgänge (CRUD). Ausführlichere Beispiele, die diese Vorgänge in einer vollständigen Beispielanwendung veranschaulichen, finden Sie im Anleitung zu Node.js.

Anmerkung

Gegebenenfalls enthalten einige Schritte unterschiedliche Codebeispiele für jede unterstützte Hauptversion des QLDB Treibers für Node.js.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass die folgende Voraussetzung erfüllt ist:

  1. Führen Sie die Voraussetzungen für den Node.js-Treiber aus, sofern Sie dies noch nicht getan haben. Dazu gehören die Registrierung für AWS, die Gewährung von programmatischem Zugriff für die Entwicklung und die Installation von Node.js.

  2. Ledger mit dem Namen quick-start erstellen.

    Informationen zum Erstellen eines Ledgers finden Sie unter Grundlegende Operationen für QLDB Amazon-Ledger oder Schritt 1: Erstellen Sie ein neues Hauptbuch in Erste Schritte mit der Konsole.

Wenn Sie verwenden TypeScript, müssen Sie auch die folgenden Einrichtungsschritte ausführen.

Um zu installieren TypeScript

  1. Installieren Sie das TypeScript Paket. Der QLDB Treiber läuft auf TypeScript 3.8.x.

    $ npm install --global typescript@3.8.0

  2. Führen Sie nach der Installation des Pakets den folgenden Befehl aus, um sicherzustellen, dass der TypeScript Compiler installiert ist.

    $ tsc --version

Beachten Sie, dass Sie Ihre TypeScript Datei zunächst wie folgt in ausführbaren Code umwandeln müssen, um den JavaScript Code in den folgenden Schritten auszuführen.

$ tsc app.ts; node app.js

Schritt 1: Einrichten des Projekts

Richten Sie zuerst Ihr Node.js-Projekt ein.

  1. Erstellen Sie einen Ordner für Ihre Anwendung.

    $ mkdir myproject
$ cd myproject

  2. Um Ihr Projekt zu initialisieren, geben Sie den folgenden npm-Befehl ein und beantworten Sie die Fragen, die während der Einrichtung gestellt werden. Sie können für die meisten Fragen Standardwerte verwenden.

    $ npm init

  3. Installieren Sie den QLDB Amazon-Treiber für Node.js.

    • Verwenden Sie Version 3.x

      $ npm install amazon-qldb-driver-nodejs --save

    • Mit Version 2.x

      $ npm install amazon-qldb-driver-nodejs@2.2.0 --save

    • Mit Version 1.x

      $ npm install amazon-qldb-driver-nodejs@1.0.0 --save

  4. Installieren Sie die Peer-Abhängigkeiten des Treibers.

    • Mit Version 3.x

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

    • Mit Version 2.x oder 1.x

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

  5. Erstellen Sie eine neue Datei mit dem Namen JavaScript, oder app.js app.ts für. TypeScript

    Fügen Sie dann schrittweise die Codebeispiele in den folgenden Schritten hinzu, um einige grundlegende CRUD Operationen auszuprobieren. Sie können das step-by-step Tutorial auch überspringen und stattdessen die gesamte Anwendung ausführen.

Schritt 2: Initialisieren des Treibers

Initialisieren Sie eine Instance des Treibers, der eine Verbindung mit dem Ledger quick-start herstellt. Fügen Sie den folgenden Code zu Ihrer app.js app.ts OR-Datei hinzu.

JavaScript
var qldb = require('amazon-qldb-driver-nodejs');
var https = require('https');

function main() {
    const maxConcurrentTransactions = 10;
    const retryLimit = 4;

    const agentForQldb = new https.Agent({
        maxSockets: maxConcurrentTransactions
    });

    const lowLevelClientHttpOptions = {
       httpAgent: agentForQldb
    }

    const serviceConfigurationOptions = {
        region: "us-east-1"
    };

    // Use driver's default backoff function for this example (no second parameter provided to RetryConfig)
    var retryConfig = new qldb.RetryConfig(retryLimit);
    var driver = new qldb.QldbDriver("quick-start", serviceConfigurationOptions, lowlevelClientHttpOptions, maxConcurrentTransactions, retryConfig);
}

main();
TypeScript
import { Agent } from "https";
import { NodeHttpHandlerOptions } from "@aws-sdk/node-http-handler";
import { QLDBSessionClientConfig } from "@aws-sdk/client-qldb-session";
import { QldbDriver, RetryConfig } from "amazon-qldb-driver-nodejs";

function main(): void {
    const maxConcurrentTransactions: number = 10;
    const agentForQldb: Agent = new Agent({
        maxSockets: maxConcurrentTransactions
    });

    const lowLevelClientHttpOptions: NodeHttpHandlerOptions = {
      httpAgent: agentForQldb
    };

    const serviceConfigurationOptions: QLDBSessionClientConfig = {
        region: "us-east-1"
    };

    const retryLimit: number = 4;
    // Use driver's default backoff function for this example (no second parameter provided to RetryConfig)
    const retryConfig: RetryConfig = new RetryConfig(retryLimit);
    const driver: QldbDriver = new QldbDriver("quick-start", serviceConfigurationOptions, lowLevelClientHttpOptions, maxConcurrentTransactions, retryConfig);
}

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

  • Ersetzen Sie in diesem Codebeispiel us-east-1 durch den AWS-Region Ort, an dem Sie Ihr Hauptbuch erstellt haben.

  • Der Einfachheit halber verwenden die übrigen Codebeispiele in diesem Handbuch einen Treiber mit Standardeinstellungen, wie im folgenden Beispiel für Version 1.x angegeben. Sie können RetryConfig stattdessen auch Ihre eigene Treiberinstanz mit einer benutzerdefinierten verwenden.

JavaScript
var qldb = require('amazon-qldb-driver-nodejs');
var https = require('https');

function main() {
    var maxConcurrentTransactions = 10;
    var retryLimit = 4;

    var agentForQldb = new https.Agent({
        keepAlive: true,
        maxSockets: maxConcurrentTransactions
    });

    var serviceConfigurationOptions = {
        region: "us-east-1",
        httpOptions: {
            agent: agentForQldb
        }
    };

    // Use driver's default backoff function for this example (no second parameter provided to RetryConfig)
    var retryConfig = new qldb.RetryConfig(retryLimit);
    var driver = new qldb.QldbDriver("quick-start", serviceConfigurationOptions, maxConcurrentTransactions, retryConfig);
}

main();
TypeScript
import { QldbDriver, RetryConfig } from "amazon-qldb-driver-nodejs";
import { ClientConfiguration } from "aws-sdk/clients/acm";
import { Agent } from "https";

function main(): void {
    const maxConcurrentTransactions: number = 10;
    const agentForQldb: Agent = new Agent({
        keepAlive: true,
        maxSockets: maxConcurrentTransactions
    });
    const serviceConfigurationOptions: ClientConfiguration = {
        region: "us-east-1",
        httpOptions: {
            agent: agentForQldb
        }
    };
    const retryLimit: number = 4;
    // Use driver's default backoff function for this example (no second parameter provided to RetryConfig)
    const retryConfig: RetryConfig = new RetryConfig(retryLimit);
    const driver: QldbDriver = new QldbDriver("quick-start", serviceConfigurationOptions, maxConcurrentTransactions, retryConfig);
}

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

  • Ersetzen Sie in diesem Codebeispiel us-east-1 durch den AWS-Region Ort, an dem Sie Ihr Hauptbuch erstellt haben.

  • Version 2.x führt den neuen optionalen Parameter RetryConfig für die Initialisierung ein. QldbDriver

  • Der Einfachheit halber verwenden die übrigen Codebeispiele in diesem Handbuch einen Treiber mit Standardeinstellungen, wie im folgenden Beispiel für Version 1.x angegeben. Sie können RetryConfig stattdessen auch Ihre eigene Treiberinstanz mit einer benutzerdefinierten verwenden.

  • In diesem Codebeispiel wird ein Treiber initialisiert, der bestehende Verbindungen wiederverwendet, indem er Keep-Alive-Optionen festlegt. Weitere Informationen finden Sie unter Empfehlungen zur Einrichtung zum Treiber Node.js.

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

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

main();
TypeScript
import { QldbDriver } from "amazon-qldb-driver-nodejs";

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

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

Sie können die AWS_REGION Umgebungsvariable festlegen, um die Region anzugeben. Weitere Informationen finden Sie unter Einstellung von AWS-Region im AWS SDK for JavaScript Entwicklerhandbuch.

Schritt 3: Erstellen einer Tabelle und eines Index

Die folgenden Codebeispiele zeigen, wie CREATE TABLE- und CREATE INDEX-Anweisungen ausgeführt werden.

  1. Fügen Sie die folgende Funktion hinzu, die eine Tabelle mit dem Namen People erstellt.

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

  2. Fügen Sie die folgende Funktion hinzu, die einen Index für das Feld firstName in der Tabelle People erstellt. Indizes sind erforderlich, um die Abfrageleistung zu optimieren und zur Begrenzung von Konfliktausnahmen bei optimistischer Parallelitätssteuerung (OCC) beizutragen.

    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)");
}

  3. In der main Funktion rufen Sie zuerst auf und rufen createTable dann auf. createIndex

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

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

    await driver.executeLambda(async (txn) => {
        console.log("Create table People");
        await createTable(txn);
        console.log("Create index on firstName");
        await createIndex(txn);
    });

    driver.close();
}

main();
    TypeScript
    import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";

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

    await driver.executeLambda(async (txn: TransactionExecutor) => {
        console.log("Create table People");
        await createTable(txn);
        console.log("Create index on firstName");
        await createIndex(txn);
    });

    driver.close();
}

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

  4. Führen Sie den Code aus, um die Tabelle und den Index zu erstellen.

    JavaScript
    $ node app.js
    TypeScript
    $ tsc app.ts; node app.js

Schritt 4: Einfügen eines Dokuments

Im folgenden Codebeispiel wird veranschaulicht, wie eine INSERT-Anweisung ausgeführt wird. QLDBunterstützt die PartiQL-Abfragesprache (SQLkompatibel) und das Amazon Ion-Datenformat (Superset vonJSON).

  1. Fügen Sie die folgende Funktion hinzu, die ein Dokument in die Tabelle People einfügt.

    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);
}

    In diesem Beispiel wird ein Fragezeichen (?) als Variablenplatzhalter verwendet, um die Dokumentinformationen an die Anweisung zu übergeben. Die execute Methode unterstützt Werte sowohl in Amazon Ion-Typen als auch in systemeigenen Typen von Node.js.

    Tipp

    Um mehrere Dokumente mithilfe einer einzigen INSERT Anweisung einzufügen, können Sie der Anweisung wie folgt einen Parameter vom Typ list übergeben.

    // people is a list
txn.execute("INSERT INTO People ?", people);

    Sie setzen den Platzhalter für die Variable (?) nicht in doppelte spitze Klammern (<<...>>), wenn Sie eine Liste übergeben. In manuellen PartiQL-Anweisungen bezeichnen doppelte spitze Klammern eine ungeordnete Sammlung, die als Tasche bezeichnet wird.

  2. Entfernen Sie in der main Funktion die createIndex Aufrufe createTable und und fügen Sie einen Aufruf von hinzu. insertDocument

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

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

    await driver.executeLambda(async (txn) => {
        console.log("Insert document");
        await insertDocument(txn);
    });

    driver.close();
}

main();
    TypeScript
    import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";

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

    await driver.executeLambda(async (txn: TransactionExecutor) => {
        console.log("Insert document");
        await insertDocument(txn);
    });

    driver.close();
}

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

Schritt 5: Abfragen des Dokuments

Im folgenden Codebeispiel wird veranschaulicht, wie eine SELECT-Anweisung ausgeführt wird.

  1. Fügen Sie die folgende Funktion hinzu, die ein Dokument aus der Tabelle People abfragt.

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

  2. Fügen Sie in der main Funktion fetchDocuments nach dem Aufruf von den folgenden Call to hinzuinsertDocument.

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

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

    var resultList = await driver.executeLambda(async (txn) => {
        console.log("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        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 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("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        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();
}

Schritt 6: Aktualisieren des Dokuments

Im folgenden Codebeispiel wird veranschaulicht, wie eine UPDATE-Anweisung ausgeführt wird.

  1. Fügen Sie die folgende Funktion hinzu, die ein Dokument in der People-Tabelle aktualisiert, indem Sie lastName in "Stiles" ändern.

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

  2. Fügen Sie in der main Funktion updateDocuments nach dem Aufruf von den folgenden Call to hinzufetchDocuments. Rufen Sie dann fetchDocuments erneut auf, um die aktualisierten Ergebnisse zu sehen.

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

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

    var resultList = await driver.executeLambda(async (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 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("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();
}

  3. Führen Sie den Code aus, um ein Dokument einzufügen, abzufragen und zu aktualisieren.

    JavaScript
    $ node app.js
    TypeScript
    $ tsc app.ts; node app.js

Ausführen der vollständigen Anwendung

Die folgenden Codebeispiele sind die vollständigen Versionen von app.js undapp.ts. Anstatt die vorherigen Schritte einzeln auszuführen, können Sie diesen Code auch von Anfang bis Ende ausführen. Diese Anwendung demonstriert einige grundlegende CRUD Operationen auf dem genannten quick-start Hauptbuch.

Anmerkung

Bevor Sie diesen Code ausführen, stellen Sie sicher, dass Sie noch keine aktive Tabelle mit dem Namen People im quick-start-Ledger besitzen.

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();
}

Geben Sie den folgenden Befehl ein, um die vollständige Anwendung auszuführen.

JavaScript
$ node app.js
TypeScript
$ tsc app.ts; node app.js