# 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 コネクタは、これらの要件を理解し、接続の確立時に IAM 認証トークンを自動的に生成するように設計されています。

### 機能
<a name="features"></a>
+  **自動 IAM 認証** - DSQL トークンの生成と更新を処理 
+  **node-postgres 上に構築** - Node.js 用の一般的な PostgreSQL クライアントを活用 
+  **シームレスな統合** 既存の node-postgres 接続パターンで動作 
+  **リージョンの自動検出** - DSQL クラスターホスト名から AWS リージョンを抽出 
+  **フル TypeScript サポート** - フルタイプのセキュリティを提供 
+  **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 以降 
+  [Aurora DSQL クラスターへのアクセス](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html) 
+  アプリケーションが Aurora DSQL に接続できるように、適切な IAM アクセス許可を設定します。
+  AWS 認証情報の設定 (AWS CLI、環境変数、または IAM ロール経由) 

## インストール
<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
```

## Usage
<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>


|  オプション  |  タイプ  |  必須  |  説明  | 
| --- | --- | --- | --- | 
|  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)からの他のすべてのパラメータがサポートされています。

## 認証
<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」という名前のユーザーは、管理者認証トークンを自動的に使用します。
+  他のすべてのユーザーは通常の認証トークンを使用します。
+  トークンは接続ごとに動的に生成されます。