Amazon QLDB driver for Node.js

To work with data in your ledger, you can connect to Amazon QLDB from your Node.js application by using an AWS provided driver. The following topics describe how to get started with the QLDB driver for Node.js.

Topics

• Driver resources
• Prerequisites
• Installation
• Setup recommendations
• Quick start tutorial
• Cookbook reference

Driver resources

For more information about the functionality supported by the Node.js driver, see the following resources:

• API reference: 3.x, 2.x, 1.x

• Driver source code (GitHub)

• Sample application source code (GitHub)

• Amazon Ion code examples

• Build a simple CRUD operation and data stream on QLDB using AWS Lambda (AWS Blog)

Prerequisites

Before you get started with the QLDB driver for Node.js, you must do the following:

1. Follow the AWS setup instructions in Accessing Amazon QLDB. This includes the following:

   1. Sign up for AWS.

   2. Create a user with the appropriate QLDB permissions.

   3. Grant programmatic access for development.

2. Install Node.js version 14.x or later from the Node.js downloads site. (Previous versions of the driver support Node.js version 10.x or later.)

3. Configure your development environment for the AWS SDK for JavaScript in Node.js:

   1. Set up your AWS credentials. We recommend creating a shared credentials file.

      For instructions, see Loading credentials in Node.js from the shared credentials file in the AWS SDK for JavaScript Developer Guide.

   2. Set your default AWS Region. To learn how, see Setting the AWS Region.

      For a complete list of available Regions, see Amazon QLDB endpoints and quotas in the AWS General Reference.

Next, you can download the complete tutorial sample application—or you can install only the driver in a Node.js project and run short code examples.

• To install the QLDB driver and the AWS SDK for JavaScript in Node.js in an existing project, proceed to Installation.

• To set up a project and run short code examples that demonstrate basic data transactions on a ledger, see the Quick start tutorial.

• To run more in-depth examples of both data and management API operations in the complete tutorial sample application, see the Node.js tutorial.

Installation

QLDB supports the following driver versions and their Node.js dependencies.

Driver version	Node.js version	Status	Latest release date
1.x	10.x or later	Production release	June 5, 2020
2.x	10.x or later	Production release	May 6, 2021
3.x	14.x or later	Production release	November 4, 2022

To install the QLDB driver using npm (the Node.js package manager), enter the following command from your project root directory.

3.x

npm install amazon-qldb-driver-nodejs

2.x

npm install amazon-qldb-driver-nodejs@2.2.0

1.x

npm install amazon-qldb-driver-nodejs@1.0.0

The driver has peer dependencies on the following packages. You must also install these packages as dependencies in your project.

3.x

Modular aggregated QLDB client (management API)

npm install @aws-sdk/client-qldb

Modular aggregated QLDB Session client (data API)

npm install @aws-sdk/client-qldb-session

Amazon Ion data format

npm install ion-js

Pure JavaScript implementation of BigInt

npm install jsbi

2.x

AWS SDK for JavaScript

npm install aws-sdk

Amazon Ion data format

npm install ion-js@4.0.0

Pure JavaScript implementation of BigInt

npm install jsbi@3.1.1

1.x

AWS SDK for JavaScript

npm install aws-sdk

Amazon Ion data format

npm install ion-js@4.0.0

Pure JavaScript implementation of BigInt

npm install jsbi@3.1.1

Using the driver to connect to a ledger

Then you can import the driver and use it to connect to a ledger. The following TypeScript code example shows how to create a driver instance for a specified ledger name and AWS Region.

3.x

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

const maxConcurrentTransactions: number = 10;
const retryLimit: number = 4;

//Reuse connections with keepAlive
const lowLevelClientHttpOptions: NodeHttpHandlerOptions = {
    httpAgent: new Agent({
      maxSockets: maxConcurrentTransactions
    })
};

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

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

qldbDriver.getTableNames().then(function(tableNames: string[]) {
    console.log(tableNames);
});

2.x

import { Agent } from 'https';
import { QldbDriver, RetryConfig  } from 'amazon-qldb-driver-nodejs';

const maxConcurrentTransactions: number = 10;
const retryLimit: number = 4;

//Reuse connections with keepAlive
const agentForQldb: Agent = new Agent({
    keepAlive: true,
    maxSockets: maxConcurrentTransactions
});

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

//Use driver's default backoff function for this example (no second parameter provided to RetryConfig)
const retryConfig: RetryConfig = new RetryConfig(retryLimit);
const qldbDriver: QldbDriver = new QldbDriver("testLedger", serviceConfigurationOptions, maxConcurrentTransactions, retryConfig);

qldbDriver.getTableNames().then(function(tableNames: string[]) {
    console.log(tableNames);
});

1.x

import { Agent } from 'https';
import { QldbDriver } from 'amazon-qldb-driver-nodejs';

const poolLimit: number = 10;
const retryLimit: number = 4;

//Reuse connections with keepAlive
const agentForQldb: Agent = new Agent({
    keepAlive: true,
    maxSockets: poolLimit
});

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

const qldbDriver: QldbDriver = new QldbDriver("testLedger", serviceConfigurationOptions, retryLimit, poolLimit);
qldbDriver.getTableNames().then(function(tableNames: string[]) {
    console.log(tableNames);
});

For short code examples of how to run basic data transactions on a ledger, see the Cookbook reference.

Setup recommendations

Reusing connections with keep-alive

QLDB Node.js driver v3

The default Node.js HTTP/HTTPS agent creates a new TCP connection for every new request. To avoid the cost of establishing a new connection, the AWS SDK for JavaScript v3 reuses TCP connections by default. For more information and to learn how to disable reusing connections, see Reusing connections with keep-alive in Node.js in the AWS SDK for JavaScript Developer Guide.

We recommend using the default setting to reuse connections in the QLDB driver for Node.js. During driver initialization, set the low-level client HTTP option maxSockets to the same value that you set for maxConcurrentTransactions.

For example, see the following JavaScript or TypeScript code.

JavaScript

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

//Replace this value as appropriate for your application
const maxConcurrentTransactions = 50;

const agentForQldb = new https.Agent({
    //Set this to the same value as `maxConcurrentTransactions`(previously called `poolLimit`)
    //Do not rely on the default value of `Infinity`
    "maxSockets": maxConcurrentTransactions
});

const lowLevelClientHttpOptions = {
    httpAgent: agentForQldb
}

let driver = new qldb.QldbDriver("testLedger", undefined, lowLevelClientHttpOptions, maxConcurrentTransactions);

TypeScript

import { Agent } from 'https';
import { NodeHttpHandlerOptions } from "@aws-sdk/node-http-handler";
import { QldbDriver } from 'amazon-qldb-driver-nodejs';

//Replace this value as appropriate for your application
const maxConcurrentTransactions: number = 50;

const agentForQldb: Agent = new Agent({
    //Set this to the same value as `maxConcurrentTransactions`(previously called `poolLimit`)
    //Do not rely on the default value of `Infinity`
    maxSockets: maxConcurrentTransactions
});

const lowLevelClientHttpOptions: NodeHttpHandlerOptions = {
    httpAgent: agentForQldb
};

let driver = new QldbDriver("testLedger", undefined, lowLevelClientHttpOptions, maxConcurrentTransactions);

QLDB Node.js driver v2

The default Node.js HTTP/HTTPS agent creates a new TCP connection for every new request. To avoid the cost of establishing a new connection, we recommend reusing an existing connection.

To reuse connections in the QLDB driver for Node.js, use one of the following options:

• During driver initialization, set the following low-level client HTTP options:

  • keepAlive – true

  • maxSockets – The same value that you set for maxConcurrentTransactions

  For example, see the following JavaScript or TypeScript code.

  JavaScript

  const qldb = require('amazon-qldb-driver-nodejs');
  const https = require('https');
  
  //Replace this value as appropriate for your application
  const maxConcurrentTransactions = 50;
  
  const agentForQldb = new https.Agent({
      "keepAlive": true,
      //Set this to the same value as `maxConcurrentTransactions`(previously called `poolLimit`)
      //Do not rely on the default value of `Infinity`
      "maxSockets": maxConcurrentTransactions
  });
  
  const serviceConfiguration = { "httpOptions": {
      "agent": agentForQldb
  }};
  
  let driver = new qldb.QldbDriver("testLedger", serviceConfiguration, maxConcurrentTransactions);

  TypeScript

  import { Agent } from 'https';
  import { ClientConfiguration } from 'aws-sdk/clients/acm';
  import { QldbDriver } from 'amazon-qldb-driver-nodejs';
  
  //Replace this value as appropriate for your application
  const maxConcurrentTransactions: number = 50;
  
  const agentForQldb: Agent = new Agent({
      keepAlive: true,
      //Set this to the same value as `maxConcurrentTransactions`(previously called `poolLimit`)
      //Do not rely on the default value of `Infinity`
      maxSockets: maxConcurrentTransactions
  });
  
  const serviceConfiguration: ClientConfiguration = { httpOptions: {
      agent: agentForQldb
  }};
  
  let driver = new QldbDriver("testLedger", serviceConfiguration, maxConcurrentTransactions);

• Alternatively, you can set the AWS_NODEJS_CONNECTION_REUSE_ENABLED environment variable to 1. For more information, see Reusing Connections with Keep-Alive in Node.js in the AWS SDK for JavaScript Developer Guide.

  Note

  If you set this environment variable, it affects all of the AWS services that use the AWS SDK for JavaScript.