{"id":16287,"library":"amazon-qldb-driver-nodejs","title":"Amazon QLDB Node.js Driver","description":"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.","status":"active","version":"3.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/awslabs/amazon-qldb-driver-nodejs","tags":["javascript","api","amazon","aws","qldb","ledger","typescript"],"install":[{"cmd":"npm install amazon-qldb-driver-nodejs","lang":"bash","label":"npm"},{"cmd":"yarn add amazon-qldb-driver-nodejs","lang":"bash","label":"yarn"},{"cmd":"pnpm add amazon-qldb-driver-nodejs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Underlying AWS SDK client for QLDB operations.","package":"@aws-sdk/client-qldb","optional":false},{"reason":"Required for establishing and managing QLDB sessions, fundamental to driver operations.","package":"@aws-sdk/client-qldb-session","optional":false},{"reason":"Required for serializing and deserializing Amazon ION data, which QLDB uses for all data exchange.","package":"ion-js","optional":false},{"reason":"Needed for handling large integers (BigInts) within the ION data format, ensuring data integrity.","package":"jsbi","optional":false}],"imports":[{"note":"Since v3.0.0, the driver is optimized for ESM, making CommonJS `require()` patterns less idiomatic and potentially problematic with default import behavior. Always use named imports for core components.","wrong":"const QldbDriver = require('amazon-qldb-driver-nodejs').QldbDriver;","symbol":"QldbDriver","correct":"import { QldbDriver } from 'amazon-qldb-driver-nodejs';"},{"note":"All main driver components, including configuration interfaces like `RetryConfig`, are exposed as named exports. Default imports are not used.","wrong":"import RetryConfig from 'amazon-qldb-driver-nodejs';","symbol":"RetryConfig","correct":"import { RetryConfig } from 'amazon-qldb-driver-nodejs';"},{"note":"The `ResultReadable` interface is used for processing streamed results from QLDB queries, which is particularly useful for handling large datasets efficiently.","symbol":"ResultReadable","correct":"import { ResultReadable } from 'amazon-qldb-driver-nodejs';"}],"quickstart":{"code":"import { QLDBSessionClientConfig } from \"@aws-sdk/client-qldb-session\";\nimport { QldbDriver, TransactionExecutor } from \"amazon-qldb-driver-nodejs\";\n\n// Configure the QLDB session client (using AWS SDK v3)\nconst qldbClientConfig: QLDBSessionClientConfig = {\n    region: \"us-east-1\", // Specify your AWS region\n    credentials: {\n        accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '', // Ensure AWS credentials are set\n        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? ''\n    }\n};\n\n// Initialize the QLDB Driver for a specific ledger\nconst ledgerName = \"my-test-ledger\"; // Replace with your QLDB ledger name\nconst qldbDriver: QldbDriver = new QldbDriver(ledgerName, qldbClientConfig);\n\nasync function main() {\n    try {\n        console.log(`Listing tables in ledger: ${ledgerName}`);\n        const tableNames = await qldbDriver.getTableNames();\n        console.log(\"Existing tables:\", tableNames);\n\n        // Example of executing a transaction to insert data\n        const newDocument = {\n            id: `doc-${Date.now()}`,\n            name: \"Example Item\",\n            quantity: 10,\n            status: \"available\"\n        };\n\n        await qldbDriver.execute(async (txn: TransactionExecutor) => {\n            console.log(\"Attempting to insert document...\");\n            // The driver automatically handles conversion of plain JS objects to Amazon ION\n            await txn.execute(`INSERT INTO Products VALUE ?`, newDocument);\n            console.log(\"Document inserted successfully.\");\n        });\n\n        // Example of querying data\n        await qldbDriver.execute(async (txn: TransactionExecutor) => {\n            console.log(\"Querying for inserted document...\");\n            const result = await txn.execute(`SELECT * FROM Products WHERE id = ?`, newDocument.id);\n            const docs = await result.toArray();\n            console.log(\"Queried documents:\", JSON.stringify(docs, null, 2));\n        });\n\n    } catch (error) {\n        console.error(\"Error interacting with QLDB:\", error);\n    } finally {\n        // Close the driver to release resources and end active sessions\n        await qldbDriver.close();\n        console.log(\"QLDB Driver closed.\");\n    }\n}\n\nmain();","lang":"typescript","description":"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."},"warnings":[{"fix":"Follow the AWS SDK for JavaScript V3 migration guide and ensure all peer dependencies like `@aws-sdk/client-qldb-session` are updated to compatible V3 major versions (e.g., `^3.x.x`).","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Review application code against the official QLDB Node.js driver documentation to ensure compliance with supported API usage and retry configurations, especially around session and transaction lifecycle.","message":"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.","severity":"breaking","affected_versions":">=2.2.0"},{"fix":"Upgrade the driver to version 2.2.0 or newer to resolve these transaction-related stability issues. Version 2.2.0 introduced significant improvements to retry logic and session handling that mitigate these errors.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0 <2.2.0"},{"fix":"Ensure all required peer dependencies, especially the `@aws-sdk` client packages and `ion-js`, are explicitly installed in your project's `package.json` with compatible versions. For driver v3.x.x, `@aws-sdk` packages must also be v3.x.x.","message":"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.","severity":"gotcha","affected_versions":"*"},{"fix":"Set `AWS_SDK_LOAD_CONFIG=1` in your application's environment, or explicitly configure AWS credentials and region within the `QLDBSessionClientConfig` object when initializing the driver.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade the `amazon-qldb-driver-nodejs` package to version `3.0.1` or newer, which includes a bug fix for this session management issue.","cause":"A driver session became null after a timeout and was not correctly re-established before an attempt to execute a lambda.","error":"Cannot read properties of null (reading 'executeLambda')"},{"fix":"Upgrade the `amazon-qldb-driver-nodejs` package to `v2.2.0` or newer to resolve known transaction handling bugs.","cause":"Internal bug in older driver versions leading to incorrect transaction state management.","error":"No open transaction"},{"fix":"Install or update `@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.","cause":"Missing or incompatible `@aws-sdk` peer dependencies, especially after migrating to driver v3.0.0 without updating AWS SDK client packages to their V3 versions.","error":"TypeError: Cannot read properties of undefined (reading 'Client') or similar related to @aws-sdk client"},{"fix":"Verify that AWS credentials and region are correctly configured through environment variables, `~/.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.","cause":"The driver failed to acquire or establish a QLDB session, typically due to incorrect AWS credentials, an invalid region configuration, or network connectivity issues.","error":"Error: No QLDB Session"}],"ecosystem":"npm"}