# node-postgres용 Aurora DSQL 커넥터
<a name="SECTION_program-with-dsql-connector-for-node-postgres"></a>

 [node-postgres용 Aurora DSQL 커넥터](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres)는 JavaScript/TypeScript 애플리케이션을 Amazon Aurora DSQL 클러스터에 연결하기 위한 IAM 인증을 통합하는 [node-postgres](https://node-postgres.com/)를 기반으로 구축된 Node.js 커넥터입니다.

 Aurora DSQL 커넥터는 node-postgres의 클라이언트 및 풀 기능을 확장하는 인증 플러그인으로 설계되어 애플리케이션이 IAM 자격 증명을 사용하여 Amazon Aurora DSQL과 인증할 수 있도록 합니다.

## 커넥터 정보
<a name="about-the-connector"></a>

 Amazon Aurora DSQL은 PostgreSQL과 호환되는 클라우드 네이티브 분산 데이터베이스입니다. IAM 인증 및 시간 제한 토큰이 필요하지만 기존 Node.js 데이터베이스 드라이버에는 이러한 기본 지원이 없습니다.

 node-postgres용 Aurora DSQL 커넥터는 node-postgres와 원활하게 작동하는 인증 미들웨어를 구현하여 이 격차를 해소합니다. 이 접근 방식을 통해 개발자는 자동화된 토큰 관리를 통해 Aurora DSQL 클러스터에 대한 안전한 IAM 기반 액세스를 확보하면서 기존 노드 포스트 코드를 유지할 수 있습니다.

### Aurora DSQL 인증이란 무엇입니까?
<a name="what-is-aurora-dsql-authentication"></a>

 Aurora DSQL에서 인증에는 다음이 포함됩니다.
+  **IAM 인증**: 모든 연결은 시간 제한 토큰이 있는 IAM 기반 인증을 사용합니다.
+  **토큰 생성:** 인증 토큰은 AWS 자격 증명을 사용하여 생성되며 구성 가능한 수명이 있습니다.

 node-postgres용 Aurora DSQL JDBC 커넥터는 이러한 요구 사항을 이해하고 연결을 설정할 때 IAM 인증 토큰을 자동으로 생성하도록 설계되었습니다.

### 특성
<a name="features"></a>
+  **자동 IAM 인증** - DSQL 토큰 생성 및 새로 고침 처리 
+  **node-postgres 기반** - Node.js에 널리 사용되는 PostgreSQL 클라이언트를 활용합니다.
+  **원활한 통합**: 기존 node-postgres 연결 패턴과 호환 
+  **리전 자동 검색** - DSQL 클러스터 호스트 이름에서 AWS 리전 추출 
+  **전체 TypeScript 지원** - 전체 유형 안전 제공 
+  **AWS 자격 증명 지원** - 다양한 AWS 자격 증명 공급자(기본값, 프로필 기반, 사용자 지정) 지원 
+  **연결 풀링 호환성** - 기본 제공 연결 풀링과 원활하게 작동 

## 애플리케이션 예제
<a name="example-application"></a>

 [예제](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres/example)에는 node-postgres용 Aurora DSQL 커넥터를 사용하는 방법을 보여주는 샘플 애플리케이션이 포함되어 있습니다. 포함된 예제를 실행하려면 예제 [README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/node-postgres/example/README.md)를 참조하세요.

## 빠른 시작 설명서
<a name="quick-start-guide"></a>

### 요구 사항
<a name="requirements"></a>
+  Node.js 20\$1 
+  [Aurora DSQL 클러스터에 대한 액세스](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html) 
+  애플리케이션이 Aurora DSQL에 연결할 수 있도록 적절한 IAM 권한 설정 
+  AWS CLI, 환경 변수 또는 IAM 역할을 통해 AWS 자격 증명 구성 

## 설치
<a name="installation"></a>

```
npm install @aws/aurora-dsql-node-postgres-connector
```

## 피어 종속성
<a name="peer-dependencies"></a>

```
npm install @aws-sdk/credential-providers @aws-sdk/dsql-signer pg tsx
npm install --save-dev @types/pg
```

## 사용법
<a name="usage"></a>

### 클라이언트 연결
<a name="client-connection"></a>

```
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";

const client = new AuroraDSQLClient({
  host: "<CLUSTER_ENDPOINT>",
  user: "admin",
});
await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```

### 풀 연결
<a name="pool-connection"></a>

```
import { AuroraDSQLPool } from "@aws/aurora-dsql-node-postgres-connector";

const pool = new AuroraDSQLPool({
  host: "<CLUSTER_ENDPOINT>",
  user: "admin",
  max: 3,
  idleTimeoutMillis: 60000,
});

const result = await pool.query("SELECT NOW()");
```

### 고급 사용
<a name="advanced-usage"></a>

```
import { fromNodeProviderChain } from "@aws-sdk/credential-providers";
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";

const client = new AuroraDSQLClient({
  host: "example.dsql.us-east-1.on.aws",
  user: "admin",
  customCredentialsProvider: fromNodeProviderChain(), // Optionally provide custom credentials provider
});

await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```

## 구성 옵션
<a name="configuration-options"></a>


|  옵션  |  Type  |  필수  |  설명  | 
| --- | --- | --- | --- | 
|  host  |  string  |  예  |  DSQL 클러스터 호스트 이름  | 
|  username  |  string  |  예  |  DSQL 사용자 이름  | 
|  database  |  string  |  아니요  |  데이터베이스 이름  | 
|  region  |  string  |  아니요  |  AWS 리전(제공되지 않은 경우 호스트 이름에서 자동 감지됨)  | 
|  port  |  number  |  아니요  |  기본값: 5432  | 
|  customCredentialsProvider  |  AwsCredentialIdentity / AwsCredentialIdentityProvider  |  아니요  |  사용자 지정 AWS 자격 증명 공급자  | 
|  profile  |  string  |  아니요  |  IAM 프로파일 이름입니다. 기본값은 "default"입니다. | 
|  tokenDurationSecs  |  number  |  아니요  |  초 단위의 토큰 만료 시간  | 

 [클라이언트](https://node-postgres.com/apis/client)/[풀](https://node-postgres.com/apis/pool)의 다른 모든 파라미터가 지원됩니다.

## Authentication
<a name="authentication"></a>

 커넥터는 DSQL 클라이언트 토큰 생성기를 사용하여 토큰을 생성하여 DSQL 인증을 자동으로 처리합니다. AWS 리전이 제공되지 않으면 제공된 호스트 이름에서 자동으로 구문 분석됩니다.

 Aurora DSQL의 인증에 대한 자세한 내용은 [사용 설명서](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html)를 참조하세요.

### 관리자 및 일반 사용자
<a name="admin-vs-regular-users"></a>
+  "admin"이라는 사용자는 관리자 인증 토큰을 자동으로 사용 
+  다른 모든 사용자는 일반 인증 토큰을 사용합니다.
+  토큰은 각 연결에 대해 동적으로 생성됩니다.