# Node.js 用 Aurora DSQL コネクタ
<a name="SECTION_Node-js-connectors"></a>

node-postgres 用 Aurora DSQL コネクタおよび Postgres.js 用 Aurora DSQL コネクタは、node-postgres および Postgres.js クライアントの機能を拡張して、IAM 認証情報を使用してアプリケーションが Aurora DSQL で認証できるようにする認証プラグインです。

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

# Postgres.js 用 Aurora DSQL コネクタ
<a name="SECTION_program-with-dsql-connector-for-postgresjs"></a>

 [Postgres.js 用 Aurora DSQL コネクタ](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js)は、JavaScript アプリケーションを Amazon Aurora DSQL クラスターに接続するための IAM 認証を統合する [Postgres.js](https://github.com/porsager/postgres) 上に構築された Node.js コネクタです。

 Postgres.js 用 Aurora DSQL コネクタは Postgres.js のクライアント機能を拡張して、アプリケーションが IAM 認証情報を使用して Amazon Aurora DSQL で認証できるようにする認証プラグインとして設計されています。コネクタはデータベースに直接接続しませんが、基盤となる Postgres.js ドライバー上でシームレスな IAM 認証を提供します。

## コネクタについて
<a name="about-the-connector"></a>

 Amazon Aurora DSQL は、PostgreSQL 互換アプリケーションに高可用性とスケーラビリティを提供する分散 SQL データベースサービスです。Aurora DSQL には、既存の Node.js ドライバーがネイティブにサポートしていない時間制限付きトークンを使用した IAM ベースの認証が必要です。

 Postgres.js 用 Aurora DSQL コネクタの考え方は、IAM トークン生成を処理する Postgres.js クライアントの上に認証レイヤーを追加することです。これにより、ユーザーは既存の Postgres.js ワークフローを変更せずに Aurora DSQL に接続できます。

 Postgres.js 用 Aurora DSQL コネクタは、ほとんどのバージョンの Postgres.js で動作します。ユーザーは Postgres.js を直接インストールして独自のバージョンを提供します。

### Aurora DSQL 認証とは
<a name="what-is-aurora-dsql-authentication"></a>

 Aurora DSQL では、認証に以下が含まれます。
+  **IAM 認証**: すべての接続で、時間制限付きトークンによる IAM ベースの認証が使用されます 
+  **トークン生成:** 認証トークンは AWS 認証情報を使用して生成され、設定可能な有効期間があります 

 Postgres.js 用 Aurora DSQL Connector は、これらの要件を理解し、接続の確立時に IAM 認証トークンを自動的に生成するように設計されています。

### 機能
<a name="features"></a>
+  **自動 IAM 認証** - DSQL トークンの生成と更新を処理 
+  **Postgres.js 上に構築** - Node.js 用の高速 PostgreSQL クライアントを活用 
+  **シームレスな統合** - 既存の Postgres.js 接続パターンで動作 
+  **リージョンの自動検出** - DSQL クラスターホスト名から AWS リージョンを抽出 
+  **フル TypeScript サポート** - フルタイプのセキュリティを提供 
+  **AWS 認証情報のサポート**: さまざまな 認証情報プロバイダー (デフォルト、プロファイルベース、カスタム) をサポート 
+  **接続プーリングの互換性** - Postgres.js の組み込み接続プーリングとシームレスに連携 

## クイックスタートガイド
<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-postgresjs-connector
# Postgres.js is a peer-dependency, so users must install it themselves
npm install postgres
```

### 基本的な使用法
<a name="basic-usage"></a>

```
import { auroraDSQLPostgres } from '@aws/aurora-dsql-postgresjs-connector';

const sql = auroraDSQLPostgres({
  host: 'your-cluster.dsql.us-east-1.on.aws',
  username: 'admin',
    
});

// Execute queries
const result = await sql`SELECT current_timestamp`;
console.log(result);

// Clean up
await sql.end();
```

#### ホストの代わりにクラスター ID を使用する
<a name="using-cluster-id-instead-of-host"></a>

```
const sql = auroraDSQLPostgres({
  host: 'your-cluster-id',
  region: 'us-east-1',
  username: 'admin',
    
});
```

### 接続文字列
<a name="connection-string"></a>

```
const sql = AuroraDSQLPostgres(
  'postgres://admin@your-cluster.dsql.us-east-1.on.aws'
);

const result = await sql`SELECT current_timestamp`;
```

### 高度な設定
<a name="advanced-configuration"></a>

```
import { fromNodeProviderChain } from '@aws-sdk/credential-providers';

const sql = AuroraDSQLPostgres({
  host: 'your-cluster.dsql.us-east-1.on.aws',
  database: 'postgres',
  username: 'admin',
  customCredentialsProvider: fromNodeProviderChain(), // Optionally provide custom credentials provider
  tokenDurationSecs: 3600,                            // Token expiration (seconds)
  
  // Standard Postgres.js options
  max: 20,                              // Connection pool size
  ssl: { rejectUnauthorized: false }    // SSL configuration
});
```

## 設定オプション
<a name="configuration-options"></a>


|  オプション  |  タイプ  |  必須  |  説明  | 
| --- | --- | --- | --- | 
|  host  |  string  |  はい  |  DSQL クラスターホスト名またはクラスター ID  | 
|  database  |  string?  |  いいえ  |  データベース名  | 
|  username  |  string?  |  いいえ  |  データベースユーザー名 (指定されていない場合は admin を使用)  | 
|  region  |  string?  |  いいえ  |  AWS リージョン (指定されていない場合はホスト名から自動検出)  | 
|  customCredentialsProvider  |  AwsCredentialIdentityProvider?  |  いいえ  |  カスタム AWS 認証情報プロバイダー  | 
|  tokenDurationSecs  |  number?  |  いいえ  |  トークンの有効期限の秒数  | 

 標準の [Postgres.js オプション](https://github.com/porsager/postgres?tab=readme-ov-file#connection-details)もすべてサポートされています。

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

## 使用例
<a name="sample-usage"></a>

 Postgres.js 用 Aurora DSQL コネクタを使用した JavaScript の例は、GitHub で入手できます。例を実行する手順については、[例のディレクトリ](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js/example)を参照してください。


|  説明  |  例  | 
| --- | --- | 
|  複数のワーカー間でのテーブルの作成、挿入、読み取りなど、同時クエリによる接続プーリング  |  [接続プーリングの例 (推奨)](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/example_preferred.js)  | 
|  接続プーリングなしの CRUD オペレーション (テーブルの作成、挿入、選択、削除)  |  [接続プーリングなしの例](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/postgres-js/example/src/alternatives/no_connection_pool/example_with_no_connection_pool.js)  |