Amazon QLDB driver for Node.js - Amazon Quantum Ledger Database (Amazon QLDB)

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.

Driver resources

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

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 an AWS Identity and Access Management (IAM) user with the appropriate QLDB permissions.

    3. Get an IAM access key for development.

  2. Install Node.js version 10.x or later from the Node.js downloads site.

  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 control plane 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

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

2.x
npm install amazon-qldb-driver-nodejs
1.x
npm install amazon-qldb-driver-nodejs@1.0.0

Installing the driver also installs TypeScript 3.5.x as a dependency.

In addition, the driver has peer dependencies on aws-sdk (AWS SDK for JavaScript), ion-js (Amazon Ion data format), and jsbi (pure JavaScript implementation of BigInt). You must also install these packages as dependencies in your project.

npm install aws-sdk
npm install ion-js@4.0.0
npm install jsbi@3.1.2

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.

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

By default, the default Node.js HTTP/HTTPS agent creates a new TCP connection for every new request. To reduce latency and 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, pass the keepAlive and maxSockets properties of httpOptions in the ClientConfiguration parameter. Set keepAlive to true, and maxSockets to the same value that you set for maxConcurrentTransactions, as follows.

    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.