Amazon QLDB Node.js Driver
raw JSON →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
error Cannot read properties of null (reading 'executeLambda') ↓
amazon-qldb-driver-nodejs package to version 3.0.1 or newer, which includes a bug fix for this session management issue. error No open transaction ↓
amazon-qldb-driver-nodejs package to v2.2.0 or newer to resolve known transaction handling bugs. error TypeError: Cannot read properties of undefined (reading 'Client') or similar related to @aws-sdk client ↓
@aws-sdk/client-qldb and @aws-sdk/client-qldb-session to compatible V3 major versions (e.g., ^3.x.x) that align with the driver's requirements. error Error: No QLDB Session ↓
~/.aws/config (with AWS_SDK_LOAD_CONFIG=1), or explicitly in the QLDBSessionClientConfig. Check network access to AWS QLDB endpoints and the QLDB service status. Warnings
breaking Version 3.0.0 introduced breaking changes by migrating to the AWS SDK for JavaScript V3. This requires updating all related `@aws-sdk` client dependencies to their V3 versions. ↓
breaking Version 2.2.0 refined the internal retry logic and API definition more strictly. This could lead to breaking changes if the driver was being used in ways not explicitly supported by previous documentation, particularly concerning session management and error handling. ↓
gotcha Versions 2.0.0, 2.0.0-rc.1, 2.1.0, and 2.1.1 contained a critical bug leading to 'No open transaction' or 'Transaction already open' errors due to issues in transaction state management. These versions are unstable for production use. ↓
gotcha The driver explicitly requires several peer dependencies (`@aws-sdk/client-qldb`, `@aws-sdk/client-qldb-session`, `ion-js`, `jsbi`) to be installed by the consuming application. Failure to install these will result in runtime errors. ↓
gotcha To correctly load AWS configuration from `~/.aws/config` files, the `AWS_SDK_LOAD_CONFIG` environment variable must be set to a truthy value (e.g., '1'). Without it, region and credentials might not be loaded as expected from shared config files. ↓
Install
npm install amazon-qldb-driver-nodejs yarn add amazon-qldb-driver-nodejs pnpm add amazon-qldb-driver-nodejs Imports
- QldbDriver wrong
const QldbDriver = require('amazon-qldb-driver-nodejs').QldbDriver;correctimport { QldbDriver } from 'amazon-qldb-driver-nodejs'; - RetryConfig wrong
import RetryConfig from 'amazon-qldb-driver-nodejs';correctimport { RetryConfig } from 'amazon-qldb-driver-nodejs'; - ResultReadable
import { ResultReadable } from 'amazon-qldb-driver-nodejs';
Quickstart
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();