Amazon QLDB Node.js Driver

3.1.0 · active · verified Wed Apr 22

The `amazon-qldb-driver-nodejs` package provides an official Node.js driver for interacting with Amazon Quantum Ledger Database (QLDB). It simplifies common tasks like managing sessions, executing transactions, and handling retries for transient errors with QLDB. Currently at stable version 3.1.0, the driver integrates seamlessly with the AWS SDK for JavaScript V3, requiring its V3 client peer dependencies for operation. It facilitates the exchange of data using Amazon ION documents, which is QLDB's underlying immutable data format. Releases occur periodically, with significant updates often aligning with AWS SDK version changes, ensuring compatibility and leveraging the latest AWS features. This package is an official offering from AWS Labs, differentiating it from community-driven alternatives by offering direct support for QLDB's unique ledger-first, immutable data model and providing robust transaction management and error handling.

Common errors

Warnings

Install

Imports

Quickstart

Initializes the QLDB driver, retrieves a list of table names, and demonstrates a basic transaction to insert a document, followed by a query to retrieve it.

import { QLDBSessionClientConfig } from "@aws-sdk/client-qldb-session";
import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";

// Configure the QLDB session client (using AWS SDK v3)
const qldbClientConfig: QLDBSessionClientConfig = {
    region: "us-east-1", // Specify your AWS region
    credentials: {
        accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '', // Ensure AWS credentials are set
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? ''
    }
};

// Initialize the QLDB Driver for a specific ledger
const ledgerName = "my-test-ledger"; // Replace with your QLDB ledger name
const qldbDriver: QldbDriver = new QldbDriver(ledgerName, qldbClientConfig);

async function main() {
    try {
        console.log(`Listing tables in ledger: ${ledgerName}`);
        const tableNames = await qldbDriver.getTableNames();
        console.log("Existing tables:", tableNames);

        // Example of executing a transaction to insert data
        const newDocument = {
            id: `doc-${Date.now()}`,
            name: "Example Item",
            quantity: 10,
            status: "available"
        };

        await qldbDriver.execute(async (txn: TransactionExecutor) => {
            console.log("Attempting to insert document...");
            // The driver automatically handles conversion of plain JS objects to Amazon ION
            await txn.execute(`INSERT INTO Products VALUE ?`, newDocument);
            console.log("Document inserted successfully.");
        });

        // Example of querying data
        await qldbDriver.execute(async (txn: TransactionExecutor) => {
            console.log("Querying for inserted document...");
            const result = await txn.execute(`SELECT * FROM Products WHERE id = ?`, newDocument.id);
            const docs = await result.toArray();
            console.log("Queried documents:", JSON.stringify(docs, null, 2));
        });

    } catch (error) {
        console.error("Error interacting with QLDB:", error);
    } finally {
        // Close the driver to release resources and end active sessions
        await qldbDriver.close();
        console.log("QLDB Driver closed.");
    }
}

main();

view raw JSON →