Node.js 용 아마존 QLDB 드라이버 — 퀵 스타트 튜토리얼 - Amazon Quantum 원장 데이터베이스(Amazon QLDB)

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

Node.js 용 아마존 QLDB 드라이버 — 퀵 스타트 튜토리얼

중요

지원 종료 알림: 기존 고객은 2025년 7월 31일 지원이 종료될 QLDB 때까지 Amazon을 사용할 수 있습니다. 자세한 내용은 아마존 QLDB 원장을 Amazon Aurora SQL Postgre로 마이그레이션을 참조하십시오.

이 자습서에서는 Node.js 용 Amazon QLDB 드라이버를 사용하여 간단한 애플리케이션을 설정하는 방법을 알아봅니다. 이 안내서에는 드라이버 설치 단계와 기본 생성, 읽기, 업데이트 JavaScript 및 삭제 (CRUD) 작업에 대한 간단한 TypeScript 코드 예제가 포함되어 있습니다. 전체 샘플 애플리케이션에서 이러한 작업을 보여 주는 자세한 예를 보려면 Node.js 자습서 섹션을 참조하세요.

참고

해당하는 경우 일부 단계에는 지원되는 Node.js QLDB 드라이버의 주요 버전마다 다른 코드 예제가 있습니다.

사전 조건

시작하기 전에 다음을 수행해야 합니다.

  1. Node.js. 드라이버에 대한 사전 조건을 아직 완료하지 않은 경우, 완료하세요. 여기에는 가입 AWS, 개발을 위한 프로그래밍 방식 액세스 권한 부여, Node.js 설치가 포함됩니다.

  2. quick-start라는 명칭의 원장을 생성합니다.

    원장 생성 방법을 알아보려면 콘솔 시작하기Amazon QLDB 원장의 기본 작업 또는 1단계: 새 원장 생성 섹션을 참조하세요.

를 사용하는 TypeScript 경우 다음 설정 단계도 수행해야 합니다.

설치하려면 TypeScript
  1. TypeScript 패키지를 설치합니다. QLDB드라이버는 TypeScript 3.8.x에서 실행됩니다.

    $ npm install --global typescript@3.8.0
  2. 패키지를 설치한 후 다음 명령을 실행하여 TypeScript 컴파일러가 설치되었는지 확인합니다.

    $ tsc --version

다음 단계에서 코드를 실행하려면 먼저 다음과 같이 TypeScript 파일을 실행 JavaScript 코드로 변환해야 합니다.

$ tsc app.ts; node app.js

1단계: 프로젝트 설정

먼저 Node.js 프로젝트를 설정합니다.

  1. 애플리케이션을 위한 폴더를 생성합니다.

    $ mkdir myproject $ cd myproject
  2. 프로젝트를 초기화하려면 다음 npm 명령을 입력하고 설정 중에 나타나는 질문에 답하세요. 대부분의 질문에 기본값을 사용할 수 있습니다.

    $ npm init
  3. Node.js 용 아마존 QLDB 드라이버를 설치합니다.

    • 버전 3.x 사용

      $ npm install amazon-qldb-driver-nodejs --save
    • 버전 2.x 사용

      $ npm install amazon-qldb-driver-nodejs@2.2.0 --save
    • 버전 1.x 사용

      $ npm install amazon-qldb-driver-nodejs@1.0.0 --save
  4. 드라이버의 피어 종속 항목을 설치합니다.

    • 버전 3.x 사용

      $ npm install @aws-sdk/client-qldb-session --save $ npm install ion-js --save $ npm install jsbi --save
    • 버전 2.x 또는 1.x 사용

      $ npm install aws-sdk --save $ npm install ion-js@4.0.0 --save $ npm install jsbi@3.1.1 --save
  5. or app.js app.ts for JavaScript 라는 이름을 가진 새 파일을 TypeScript 생성하십시오.

    그런 다음 다음 단계의 코드 예제를 점진적으로 추가하여 몇 가지 기본 CRUD 작업을 시도해 보십시오. 또는 step-by-step 자습서를 건너뛰고 대신 전체 응용 프로그램을 실행할 수도 있습니다.

2단계: 드라이버 초기화

quick-start라는 명칭의 원장에 연결되는 드라이버의 인스턴스를 초기화합니다. 다음 코드를 app.js 또는 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(); }
참고
  • 이 코드 예제에서는 다음을 대체하십시오.us-east-1 원장을 생성한 AWS 리전 곳으로 바꾸세요.

  • 간소화를 위해 이 가이드의 나머지 코드 예에서는 다음 예 버전 1.x에 지정된 대로 기본 설정이 있는 드라이버를 사용합니다. 사용자 지정 RetryConfig 대신 자체 드라이버 인스턴스를 사용할 수도 있습니다.

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(); }
참고
  • 이 코드 예제에서는 다음을 대체합니다.us-east-1 원장을 생성한 AWS 리전 곳으로 바꾸세요.

  • 버전 2.x에는 QldbDriver 초기화를 위한 새로운 옵션 파라미터 RetryConfig가 도입되었습니다.

  • 간소화를 위해 이 가이드의 나머지 코드 예에서는 다음 예 버전 1.x에 지정된 대로 기본 설정이 있는 드라이버를 사용합니다. 사용자 지정 RetryConfig 대신 자체 드라이버 인스턴스를 사용할 수도 있습니다.

  • 이 코드 예는 연결 유지 옵션을 설정하여 기존 연결을 재사용하는 드라이버를 초기화합니다. 자세한 설명은 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(); }
참고

AWS_REGION 환경 변수를 설정하여 지역을 지정할 수 있습니다. 자세한 설명은 AWS SDK for JavaScript 개발자 가이드AWS 리전의 설정을 참조하세요.

3단계: 테이블 및 인덱스 생성

다음 코드 예는 CREATE TABLECREATE INDEX 문을 실행하는 방법을 보여줍니다.

  1. 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. People 표의 firstName 필드에 대한 인덱스를 만드는 다음 함수를 추가합니다. 인덱스는 쿼리 성능을 최적화하고 낙관적 동시성 제어 () 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. main 함수에서는 먼저 createTable를 호출한 다음 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. 코드를 실행하여 표와 인덱스를 생성합니다.

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

4단계: 문서 삽입

다음 코드 예에서는 INSERT 문을 실행하는 방법을 보여줍니다. QLDBPartiQL 쿼리 언어 SQL (호환 가능) 및 Amazon Ion 데이터 형식 (상위 세트) 을 지원합니다. JSON

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

    이 예에서는 물음표(?)를 변수 자리 표시자로 사용하여 문서 정보를 해당 문에 전달합니다. 이 execute 메서드는 Amazon Ion 타입과 Node.js 네이티브 타입 모두의 값을 지원합니다.

    작은 정보

    단일 INSERT 문을 사용하여 여러 문서를 삽입하려면 다음과 같이 목록 타입의 파라미터를 해당 문에 전달할 수 있습니다.

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

    목록을 전달할 때 변수 자리 표시자(?)를 이중 꺾쇠 괄호( <<...>> )로 묶지 마세요. 수동 PartiQL 문에서 이중 꺾쇠 괄호는 으로 알려진 정렬되지 않은 모음을 의미합니다.

  2. main함수에서 createTablecreateIndex 호출을 제거하고 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(); }

5단계: 문서 쿼리

다음 코드 예에서는 SELECT 문을 실행하는 방법을 보여줍니다.

  1. 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. main 함수에서 insertDocument 호출 뒤에 다음 fetchDocuments 호출을 추가합니다.

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

6단계: 문서 업데이트

다음 코드 예에서는 UPDATE 문을 실행하는 방법을 보여줍니다.

  1. lastName"Stiles"으로 변경함으로써 People 표의 문서를 업데이트하는 다음 함수를 추가합니다.

    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. main 함수에서 fetchDocuments 호출 뒤에 다음 updateDocuments 호출을 추가합니다. 그런 다음 fetchDocuments를 다시 호출하여 업데이트된 결과를 확인합니다.

    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. 코드를 실행하여 문서를 삽입, 쿼리 및 업데이트합니다.

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

전체 애플리케이션 실행

다음 코드 예는 app.jsapp.ts의 전체 버전입니다. 이전 단계를 개별적으로 수행하는 대신 이 코드를 처음부터 끝까지 실행할 수도 있습니다. 이 애플리케이션은 이름이 지정된 원장에 대한 몇 가지 기본 CRUD 작업을 보여줍니다. quick-start

참고

이 코드를 실행하기 전에 quick-start 원장에 People이라는 명칭의 활성 테이블이 아직 없는지 확인하세요.

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

전체 애플리케이션을 실행하려면 다음 명령을 입력하세요.

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