QLDBDriver Amazon para Node.js — Tutorial de início rápido - Banco de dados Amazon Quantum Ledger (AmazonQLDB)
Pré-requisitosEtapa 1: configurar o projeto do Etapa 2: Inicializar o driverEtapa 3: Crie uma tabela e um índiceEtapa 4: Inserir um documentoEtapa 5: consultar o documentoEtapa 6: Atualize o documentoExecutar o aplicativo completo

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

QLDBDriver Amazon para Node.js — Tutorial de início rápido

Importante

Aviso de fim do suporte: os clientes existentes poderão usar a Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte Migrar um Amazon QLDB Ledger para o Amazon Aurora Postgre. SQL

Neste tutorial, você aprende a configurar um aplicativo simples usando o QLDB driver da Amazon para Node.js. Este guia inclui etapas para instalar o driver e exemplos curtos JavaScript e de TypeScript código das operações básicas de criação, leitura, atualização e exclusão (CRUD). Para obter exemplos mais detalhados que demonstram essas operações em um aplicativo de amostra completo, consulte o Tutorial Node.js.

nota

Quando aplicável, algumas etapas têm exemplos de código diferentes para cada versão principal compatível do QLDB driver para Node.js.

Pré-requisitos

Antes de iniciar, certifique-se de fazer o seguinte:

  1. Complete a Pré-requisitos para o driver Node.js, caso ainda não o tenha feito. Isso inclui se inscrever AWS, conceder acesso programático para desenvolvimento e instalar o Node.js.

  2. Crie um ledger chamado quick-start.

    Para saber como criar um ledger, consulte Operações básicas para livros contábeis da Amazon QLDB ou Etapa 1: criar um novo ledger em Conceitos básicos do console.

Se você estiver usando TypeScript, você também deve seguir as etapas de configuração a seguir.

Para instalar TypeScript

  1. Instale o TypeScript pacote. O QLDB driver é executado em TypeScript 3.8.x.

    $ npm install --global typescript@3.8.0

  2. Depois que o pacote for instalado, execute o comando a seguir para garantir que o TypeScript compilador esteja instalado.

    $ tsc --version

Para executar o código nas etapas a seguir, observe que você deve primeiro transpilar seu TypeScript arquivo em JavaScript código executável, da seguinte maneira.

$ tsc app.ts; node app.js

Etapa 1: configurar o projeto do

Primeiro, configure seu projeto Node.js.

  1. Crie uma pasta para o seu aplicativo.

    $ mkdir myproject
$ cd myproject

  2. Para inicializar seu projeto, digite o comando npm a seguir e responda às perguntas feitas durante a configuração. Você pode usar padrões para a maioria das perguntas.

    $ npm init

  3. Instale o QLDB driver da Amazon para Node.js.

    • Usar a versão 3.x

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

    • Usar a versão 2.x

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

    • Usar a versão 1.x

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

  4. Instale as dependências de pares do driver.

    • Usar a versão 3.x

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

    • Usar a versão 2.x ou 1.x

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

  5. Crie um novo arquivo com app.js o nome JavaScript de ou app.ts para TypeScript.

    Em seguida, adicione incrementalmente os exemplos de código nas etapas a seguir para experimentar algumas CRUD operações básicas. Ou você pode pular o step-by-step tutorial e, em vez disso, executar o aplicativo completo.

Etapa 2: Inicializar o driver

Inicialize uma instância do driver que se conecta ao ledger chamado quick-start. Adicione o seguinte código ao seu arquivo app.js ou 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

  • Neste exemplo de código, substitua us-east-1 com o Região da AWS local onde você criou seu livro contábil.

  • Para simplificar, os exemplos de código restantes neste guia usam um driver com configurações padrão, conforme especificado no exemplo a seguir para a versão 1.x. Também é possível usar sua própria instância de driver com uma RetryConfig personalizada.

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

  • Neste exemplo de código, substitua us-east-1 com o Região da AWS local onde você criou seu livro contábil.

  • A versão 2.x introduz o novo parâmetro opcional RetryConfig para inicialização QldbDriver.

  • Para simplificar, os exemplos de código restantes neste guia usam um driver com configurações padrão, conforme especificado no exemplo a seguir para a versão 1.x. Também é possível usar sua própria instância de driver com uma RetryConfig personalizada.

  • Este exemplo de código inicializa um driver que reutiliza conexões existentes definindo as opções keep-alive. Para saber mais, consulte Recomendações de configuração para o driver 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

Você pode definir a variável de ambiente AWS_REGION para especificar a Região. Para obter mais informações, consulte Configurar a Região da AWS no Guia do desenvolvedor do AWS SDK for JavaScript .

Etapa 3: Crie uma tabela e um índice

Os exemplos de código a seguir mostram como executar as instruções CREATE TABLE e CREATE INDEX.

  1. Adicione a função a seguir que cria uma tabela chamada 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. Adicione a função a seguir que cria um índice para o campo firstName na tabela People. Os índices são necessários para otimizar o desempenho da consulta e ajudar a limitar as exceções otimistas de conflitos do controle de simultaneidade (OCC).

    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. Na função main, você chama primeiro createTable e depois chama 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. Execute o código para criar a tabela e o índice.

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

Etapa 4: Inserir um documento

O exemplo de código a seguir mostra como executar uma instrução INSERT. QLDBsuporta a linguagem de consulta partiQL (SQLcompatível) e o formato de dados Amazon Ion (superconjunto de). JSON

  1. Adicione o código a seguir que insere um documento na tabela 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);
}

    Este exemplo usa um ponto de interrogação (?) como um marcador variável para passar as informações do documento para a instrução. O método execute suporta valores nos tipos Amazon Ion e nos tipos nativos do Python.

    dica

    Para inserir vários documentos usando uma única instrução INSERT, você pode passar um parâmetro do tipo lista para a instrução da seguinte maneira.

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

    Você não coloca o marcador variável (?) entre colchetes angulares duplos (<<...>>) ao passar uma lista. Nas instruções manuais do PartiQL, colchetes angulares duplos denotam uma coleção não ordenada conhecida como bolsa.

  2. Na função main, remova as chamadas createTable e createIndex e adicione uma chamada 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();
}

Etapa 5: consultar o documento

O exemplo de código a seguir mostra como executar uma instrução SELECT.

  1. Adicione o código a seguir que insere um documento da tabela 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. Na função main, adicione a seguinte chamada fetchDocuments após a chamada para 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();
}

Etapa 6: Atualize o documento

O exemplo de código a seguir mostra como executar uma instrução UPDATE.

  1. Adicione o código a seguir que insere um documento na tabela People, mudando de lastName para "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. Na função main, adicione a seguinte chamada updateDocuments após a chamada para fetchDocuments. Em seguida, chame fetchDocuments novamente para ver os resultados atualizados.

    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. Execute o código para inserir, consultar e atualizar um documento.

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

Executar o aplicativo completo

Os exemplos de código a seguir são as versões completas de app.js e app.ts. Em vez de executar as etapas anteriores individualmente, você também pode copiar e executar esse exemplo de código do início ao fim. Este aplicativo demonstra algumas CRUD operações básicas no livro contábil chamado. quick-start

nota

Antes de executar esse código, verifique se você ainda não tem uma tabela ativa chamada People no ledger 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();
}

Para executar o aplicativo completo, insira o comando a seguir.

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