Prerequisites Step 1: Set up your project Step 2: Initialize the driver Step 3: Create a table and an index Step 4: Insert a document Step 5: Query the document Step 6: Update the document Running the complete application

Amazon QLDB driver for Node.js – Quick start tutorial

Important

End of support notice: Existing customers will be able to use Amazon QLDB until end of support on 07/31/2025. For more details, see Migrate an Amazon QLDB Ledger to Amazon Aurora PostgreSQL.

In this tutorial, you learn how to set up a simple application using the Amazon QLDB driver for Node.js. This guide includes steps for installing the driver, and short JavaScript and TypeScript code examples of basic create, read, update, and delete (CRUD) operations. For more in-depth examples that demonstrate these operations in a full sample application, see the Node.js tutorial.

Note

Where applicable, some steps have different code examples for each supported major version of the QLDB driver for Node.js.

Prerequisites

Before you get started, make sure that you do the following:

Complete the Prerequisites for the Node.js driver, if you haven't already done so. This includes signing up for AWS, granting programmatic access for development, and installing Node.js.
Create a ledger named quick-start.

To learn how to create a ledger, see Basic operations for Amazon QLDB ledgers or Step 1: Create a new ledger in Getting started with the console.

If you're using TypeScript, you must also do the following setup steps.

To install TypeScript

Install the TypeScript package. The QLDB driver runs on TypeScript 3.8.x.
```
$ npm install --global typescript@3.8.0
```
After the package is installed, run the following command to make sure that the TypeScript compiler is installed.
```
$ tsc --version
```

To run the code in the following steps, note that you must first transpile your TypeScript file to executable JavaScript code, as follows.


$ tsc app.ts; node app.js

Step 1: Set up your project

First, set up your Node.js project.

Create a folder for your application.
```
$ mkdir myproject
$ cd myproject
```
To initialize your project, enter the following npm command and answer the questions that are asked during the setup. You can use defaults for most of the questions.
```
$ npm init
```

Install the Amazon QLDB driver for Node.js.

Using version 3.x


$ npm install amazon-qldb-driver-nodejs --save

Using version 2.x


$ npm install amazon-qldb-driver-nodejs@2.2.0 --save

Using version 1.x


$ npm install amazon-qldb-driver-nodejs@1.0.0 --save

Install the peer dependencies of the driver.

Using version 3.x


$ npm install @aws-sdk/client-qldb-session --save
$ npm install ion-js --save
$ npm install jsbi --save

Using version 2.x or 1.x


$ npm install aws-sdk --save
$ npm install ion-js@4.0.0 --save
$ npm install jsbi@3.1.1 --save

Create a new file named app.js for JavaScript, or app.ts for TypeScript.

Then, incrementally add the code examples in the following steps to try some basic CRUD operations. Or, you can skip the step-by-step tutorial and instead run the complete application.

Step 2: Initialize the driver

Initialize an instance of the driver that connects to the ledger named quick-start. Add the following code to your app.js or app.ts file.

Note

In this code example, replace us-east-1 with the AWS Region where you created your ledger.
For simplicity, the remaining code examples in this guide use a driver with default settings, as specified in the following example for version 1.x. You can also use your own driver instance with a custom RetryConfig instead.

Note

In this code example, replace us-east-1 with the AWS Region where you created your ledger.
Version 2.x introduces the new optional parameter RetryConfig for initializing QldbDriver.
For simplicity, the remaining code examples in this guide use a driver with default settings, as specified in the following example for version 1.x. You can also use your own driver instance with a custom RetryConfig instead.
This code example initializes a driver that reuses existing connections by setting keep-alive options. To learn more, see Setup recommendations for the Node.js driver.

Note

You can set the AWS_REGION environment variable to specify the Region. For more information, see Setting the AWS Region in the AWS SDK for JavaScript Developer Guide.

Step 3: Create a table and an index

The following code examples show how to run CREATE TABLE and CREATE INDEX statements.

Add the following function that creates a table named People.

Add the following function that creates an index for the firstName field on the People table. Indexes are required to optimize query performance and help to limit optimistic concurrency control (OCC) conflict exceptions.
JavaScript
```
async function createIndex(txn) {
    await txn.execute("CREATE INDEX ON People (firstName)");
}
```
TypeScript
```
async function createIndex(txn: TransactionExecutor): Promise<void> {
    await txn.execute("CREATE INDEX ON People (firstName)");
}
```

In the main function, you first call createTable, and then call createIndex.

Run the code to create the table and index.
JavaScript
```
$ node app.js
```
TypeScript
```
$ tsc app.ts; node app.js
```

Step 4: Insert a document

The following code example shows how to run an INSERT statement. QLDB supports the PartiQL query language (SQL compatible) and the Amazon Ion data format (superset of JSON).

Add the following function that inserts a document into the People table.
JavaScript
```
async function insertDocument(txn) {
    const person = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}
```
TypeScript
```
async function insertDocument(txn: TransactionExecutor): Promise<void> {
    const person: Record<string, any> = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}
```
This example uses a question mark (?) as a variable placeholder to pass the document information to the statement. The execute method supports values in both Amazon Ion types and Node.js native types.
Tip
To insert multiple documents by using a single INSERT statement, you can pass a parameter of type list to the statement as follows.
```
// people is a list
txn.execute("INSERT INTO People ?", people);
```
You don't enclose the variable placeholder (?) in double angle brackets ( <<...>> ) when passing a list. In manual PartiQL statements, double angle brackets denote an unordered collection known as a bag.

In the main function, remove the createTable and createIndex calls, and add a call to insertDocument.

Step 5: Query the document

The following code example shows how to run a SELECT statement.

Add the following function that queries a document from the People table.

In the main function, add the following call to fetchDocuments after the call to insertDocument.

Step 6: Update the document

The following code example shows how to run an UPDATE statement.

Add the following function that updates a document in the People table by changing lastName to "Stiles".

In the main function, add the following call to updateDocuments after the call to fetchDocuments. Then, call fetchDocuments again to see the updated results.

Run the code to insert, query, and update a document.
JavaScript
```
$ node app.js
```
TypeScript
```
$ tsc app.ts; node app.js
```

Running the complete application

The following code examples are the complete versions of app.js and app.ts. Instead of doing the previous steps individually, you can also run this code from start to end. This application demonstrates some basic CRUD operations on the ledger named quick-start.

Note

Before you run this code, make sure that you don't already have an active table named People in the quick-start ledger.

JavaScript


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

async function createTable(txn) {
    await txn.execute("CREATE TABLE People");
}

async function createIndex(txn) {
    await txn.execute("CREATE INDEX ON People (firstName)");
}

async function insertDocument(txn) {
    const person = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}

async function fetchDocuments(txn) {
    return await txn.execute("SELECT firstName, age, lastName FROM People WHERE firstName = ?", "John");
}

async function updateDocuments(txn) {
    await txn.execute("UPDATE People SET lastName = ? WHERE firstName = ?", "Stiles", "John");
}

async function main() {
    // Use default settings
    const driver = new qldb.QldbDriver("quick-start");

    var resultList = await driver.executeLambda(async (txn) => {
        console.log("Create table People");
        await createTable(txn);
        console.log("Create index on firstName");
        await createIndex(txn);
        console.log("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        await fetchDocuments(txn);
        console.log("Update document");
        await updateDocuments(txn);
        console.log("Fetch document after update");
        var result = await fetchDocuments(txn);
        return result.getResultList();
    });

    // Pretty print the result list
    console.log("The result List is ", JSON.stringify(resultList, null, 2));
    driver.close();
}

main();

TypeScript


import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";

async function createTable(txn: TransactionExecutor): Promise<void> {
    await txn.execute("CREATE TABLE People");
}

async function createIndex(txn: TransactionExecutor): Promise<void> {
    await txn.execute("CREATE INDEX ON People (firstName)");
}

async function insertDocument(txn: TransactionExecutor): Promise<void> {
    const person: Record<string, any> = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}

async function fetchDocuments(txn: TransactionExecutor): Promise<dom.Value[]> {
    return (await txn.execute("SELECT firstName, age, lastName FROM People WHERE firstName = ?", "John")).getResultList();
}

async function updateDocuments(txn: TransactionExecutor): Promise<void> {
    await txn.execute("UPDATE People SET lastName = ? WHERE firstName = ?", "Stiles", "John");
};

async function main(): Promise<void> {
    // Use default settings
    const driver: QldbDriver = new QldbDriver("quick-start");

    const resultList: dom.Value[] = await driver.executeLambda(async (txn: TransactionExecutor) => {
        console.log("Create table People");
        await createTable(txn);
        console.log("Create index on firstName");
        await createIndex(txn);
        console.log("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        await fetchDocuments(txn);
        console.log("Update document");
        await updateDocuments(txn);
        console.log("Fetch document after update");
        return await fetchDocuments(txn);
    });

    // Pretty print the result list
    console.log("The result List is ", JSON.stringify(resultList, null, 2));
    driver.close();
}

if (require.main === module) {
    main();
}

To run the complete application, enter the following command.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Node.js driver

Cookbook reference

Amazon QLDB driver for Node.js – Quick start tutorial

Important

Note

Topics

Prerequisites

To install TypeScript

Step 1: Set up your project

Step 2: Initialize the driver

Note

Note

Note

Step 3: Create a table and an index

Step 4: Insert a document

Tip

Step 5: Query the document

Step 6: Update the document

Running the complete application

Note