QLDBControlador de Amazon para Node.js: tutorial de inicio rápido - Base de datos Amazon Quantum Ledger (AmazonQLDB)
Requisitos previosPaso 1: Configuración del proyectoPaso 2: inicializar el controladorPaso 3: crear una tabla y un índicePaso 4: insertar un documentoPaso 5: consulta del documentoPaso 6: actualizar el documentoEjecución de la aplicación completa

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

QLDBControlador de Amazon para Node.js: tutorial de inicio rápido

importante

Aviso de fin del soporte: los clientes actuales podrán utilizar Amazon QLDB hasta que finalice el soporte, el 31 de julio de 2025. Para obtener más información, consulte Migración de un Amazon QLDB Ledger a Amazon Aurora SQL Postgre.

En este tutorial, aprenderás a configurar una aplicación sencilla con el QLDB controlador de Amazon para Node.js. Esta guía incluye los pasos para instalar el controlador y ejemplos breves JavaScript y en TypeScript código de las operaciones básicas de creación, lectura, actualización y eliminación (CRUD). Para ver ejemplos más detallados que presentan estas operaciones en una aplicación de muestra completa, consulte Tutorial de Node.js.

nota

Cuando proceda, algunos pasos incluyen ejemplos de código diferentes para cada versión principal compatible del QLDB controlador de Node.js.

Requisitos previos

Antes de comenzar, asegúrese de que hace lo siguiente:

  1. Si aún no lo ha hecho, complete el Requisitos previos para el controlador Node.js. Esto incluye registrarse AWS, conceder acceso mediante programación para el desarrollo e instalar Node.js.

  2. Cree un libro mayor denominado quick-start.

    Para obtener más información sobre cómo crear un libro mayor, consulte Operaciones básicas para los libros de QLDB contabilidad de Amazon o Paso 1: crear un nuevo libro mayor en Introducción a la consola.

Si lo está utilizando TypeScript, también debe realizar los siguientes pasos de configuración.

Para instalar TypeScript

  1. Instale el TypeScript paquete. El QLDB controlador se ejecuta en la versión TypeScript 3.8.x.

    $ npm install --global typescript@3.8.0

  2. Una vez instalado el paquete, ejecute el siguiente comando para asegurarse de que el TypeScript compilador está instalado.

    $ tsc --version

Para ejecutar el código en los siguientes pasos, tenga en cuenta que primero debe transpilar el TypeScript archivo a JavaScript código ejecutable, de la siguiente manera.

$ tsc app.ts; node app.js

Paso 1: Configuración del proyecto

En primer lugar, configure su proyecto de Node.js.

  1. Cree una carpeta para su aplicación.

    $ mkdir myproject
$ cd myproject

  2. Para inicializar el proyecto, introduzca el siguiente comando npm y responda a las preguntas que se le formulen durante la configuración. Puede utilizar los valores predeterminados para la mayoría de las preguntas.

    $ npm init

  3. Instale el QLDB controlador de Amazon para Node.js.

    • Uso de la versión 3.x

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

    • Uso de la versión 2.x

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

    • Uso de la versión 1.x

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

  4. Instale las dependencias homólogas del controlador.

    • Uso de la versión 3.x

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

    • Uso de la versión 2.x o 1.x

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

  5. Cree un archivo nuevo con el nombre app.js de JavaScript, o app.ts para TypeScript.

    A continuación, añada gradualmente los ejemplos de código en los siguientes pasos para intentar realizar algunas CRUD operaciones básicas. O bien, puede omitir el step-by-step tutorial y ejecutar la aplicación completa.

Paso 2: inicializar el controlador

Inicialice una instancia del controlador que se conecte al libro mayor denominado quick-start. Agregue el siguiente código a su archivo app.js o app.ts.

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

function main() {
    const maxConcurrentTransactions = 10;
    const retryLimit = 4;

    const agentForQldb = new https.Agent({
        maxSockets: maxConcurrentTransactions
    });

    const lowLevelClientHttpOptions = {
       httpAgent: agentForQldb
    }

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

    // Use driver's default backoff function for this example (no second parameter provided to RetryConfig)
    var retryConfig = new qldb.RetryConfig(retryLimit);
    var driver = new qldb.QldbDriver("quick-start", serviceConfigurationOptions, lowlevelClientHttpOptions, maxConcurrentTransactions, retryConfig);
}

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

function main(): void {
    const maxConcurrentTransactions: number = 10;
    const agentForQldb: Agent = new Agent({
        maxSockets: maxConcurrentTransactions
    });

    const lowLevelClientHttpOptions: NodeHttpHandlerOptions = {
      httpAgent: agentForQldb
    };

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

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

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

  • En este ejemplo de código, sustituya us-east-1 con el Región de AWS lugar en el que creó el libro mayor.

  • Para simplificar, el resto de los ejemplos de código de esta guía utilizan un controlador con la configuración predeterminada, tal y como se especifica en el siguiente ejemplo de la versión 1.x. También puede utilizar su propia instancia de controlador con una RetryConfig personalizada en su lugar.

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

function main() {
    var maxConcurrentTransactions = 10;
    var retryLimit = 4;

    var agentForQldb = new https.Agent({
        keepAlive: true,
        maxSockets: maxConcurrentTransactions
    });

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

    // Use driver's default backoff function for this example (no second parameter provided to RetryConfig)
    var retryConfig = new qldb.RetryConfig(retryLimit);
    var driver = new qldb.QldbDriver("quick-start", serviceConfigurationOptions, maxConcurrentTransactions, retryConfig);
}

main();
TypeScript
import { QldbDriver, RetryConfig } from "amazon-qldb-driver-nodejs";
import { ClientConfiguration } from "aws-sdk/clients/acm";
import { Agent } from "https";

function main(): void {
    const maxConcurrentTransactions: number = 10;
    const agentForQldb: Agent = new Agent({
        keepAlive: true,
        maxSockets: maxConcurrentTransactions
    });
    const serviceConfigurationOptions: ClientConfiguration = {
        region: "us-east-1",
        httpOptions: {
            agent: agentForQldb
        }
    };
    const retryLimit: number = 4;
    // Use driver's default backoff function for this example (no second parameter provided to RetryConfig)
    const retryConfig: RetryConfig = new RetryConfig(retryLimit);
    const driver: QldbDriver = new QldbDriver("quick-start", serviceConfigurationOptions, maxConcurrentTransactions, retryConfig);
}

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

  • En este ejemplo de código, sustituya us-east-1 con el Región de AWS lugar en el que creó el libro mayor.

  • La versión 2.x introduce el nuevo parámetro opcional RetryConfig para la inicialización de QldbDriver.

  • Para simplificar, el resto de los ejemplos de código de esta guía utilizan un controlador con la configuración predeterminada, tal y como se especifica en el siguiente ejemplo de la versión 1.x. También puede utilizar su propia instancia de controlador con una RetryConfig personalizada en su lugar.

  • Este ejemplo de código inicializa un controlador que reutiliza las conexiones existentes mediante la configuración de opciones keep-alive. Para obtener más información, consulte Recomendaciones de configuración para el controlador de Node.js.

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

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

main();
TypeScript
import { QldbDriver } from "amazon-qldb-driver-nodejs";

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

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

Puede establecer la región mediante la variable de entorno AWS_REGION. Para obtener más información, consulte Configurar Región de AWS en la Guía para desarrolladores de AWS SDK for JavaScript .

Paso 3: crear una tabla y un índice

Los siguientes ejemplos de código muestran cómo ejecutar las instrucciones CREATE TABLE y CREATE INDEX.

  1. Agregue la siguiente función que crea una tabla llamada People.

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

  2. Agregue la siguiente función que crea un índice para el campo firstName de la tabla People. Los índices son necesarios para optimizar el rendimiento de las consultas y ayudar a limitar las excepciones optimistas en materia de control de simultaneidad (OCC) conflictos.

    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)");
}

  3. En la función main, primero llame a createTable y después llame a createIndex.

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

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

    await driver.executeLambda(async (txn) => {
        console.log("Create table People");
        await createTable(txn);
        console.log("Create index on firstName");
        await createIndex(txn);
    });

    driver.close();
}

main();
    TypeScript
    import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";

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

    await driver.executeLambda(async (txn: TransactionExecutor) => {
        console.log("Create table People");
        await createTable(txn);
        console.log("Create index on firstName");
        await createIndex(txn);
    });

    driver.close();
}

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

  4. Ejecute el código para crear la tabla y el índice.

    JavaScript
    $ node app.js
    TypeScript
    $ tsc app.ts; node app.js

Paso 4: insertar un documento

El siguiente ejemplo de código muestra cómo ejecutar una instrucción INSERT. QLDBadmite el lenguaje de consultas PartiQL (SQLcompatible) y el formato de datos Amazon Ion (superconjunto de). JSON

  1. Añada la siguiente función para insertar un documento en la tabla People.

    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);
}

    En este ejemplo se emplea un signo de interrogación (?) como marcador de posición variable para pasar la información del documento a la instrucción. El método execute admite valores tanto en los tipos de Amazon Ion como en los tipos nativos de Node.js.

    sugerencia

    Para insertar varios documentos mediante una sola instrucción INSERT, puede pasar un parámetro del tipo list a la instrucción de la siguiente manera.

    // people is a list
txn.execute("INSERT INTO People ?", people);

    No coloque el marcador de posición variable (?) entre corchetes de doble ángulo (<<...>>) al pasar una lista. En las instrucciones PartiQL manuales, los corchetes de doble ángulo indican una colección desordenada conocida como bolsa.

  2. En la función main, elimine las llamadas createTable y createIndex y añada una llamada a insertDocument.

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

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

    await driver.executeLambda(async (txn) => {
        console.log("Insert document");
        await insertDocument(txn);
    });

    driver.close();
}

main();
    TypeScript
    import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";

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

    await driver.executeLambda(async (txn: TransactionExecutor) => {
        console.log("Insert document");
        await insertDocument(txn);
    });

    driver.close();
}

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

Paso 5: consulta del documento

El siguiente ejemplo de código muestra cómo ejecutar una instrucción SELECT.

  1. Agregue la siguiente función para consultar un documento de la tabla People.

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

  2. En la función main, añada la siguiente llamada a fetchDocuments después de la llamada a insertDocument.

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

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

    var resultList = await driver.executeLambda(async (txn) => {
        console.log("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        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 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("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        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();
}

Paso 6: actualizar el documento

El siguiente ejemplo de código muestra cómo ejecutar una instrucción UPDATE.

  1. Añada la siguiente función para actualizar un documento de la tabla People actualizando lastName a "Stiles".

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

  2. En la función main, añada la siguiente llamada a updateDocuments después de la llamada a fetchDocuments. A continuación, vuelva a llamar a fetchDocuments para ver los resultados actualizados.

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

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

    var resultList = await driver.executeLambda(async (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 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("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();
}

  3. Ejecute el código para insertar, consultar y actualizar un documento.

    JavaScript
    $ node app.js
    TypeScript
    $ tsc app.ts; node app.js

Ejecución de la aplicación completa

Los siguientes ejemplos de código son las versiones completas de app.js y app.ts. En lugar de seguir los pasos anteriores de forma individual, también puede ejecutar este ejemplo de código de principio a fin. Esta aplicación muestra algunas CRUD operaciones básicas en el libro mayor denominado. quick-start

nota

Antes de ejecutar este código, asegúrese de no tener ya una tabla activa con el nombre People en el libro mayor quick-start.

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();
}

Introduzca el siguiente comando para ejecutar la aplicación completa.

JavaScript
$ node app.js
TypeScript
$ tsc app.ts; node app.js