本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 適用於 Node.js 的 Aurora DSQL 連接器
Aurora DSQL Connector for node-postgres 和 Aurora DSQL Connector for Postgres.js 是身分驗證外掛程式，可延伸 node-postgres 和 Postgres.js 用戶端的功能，讓應用程式使用 IAM 登入資料向 Aurora DSQL 進行身分驗證。
# 適用於節點後置的 Aurora DSQL 連接器
[Aurora DSQL Connector for node-postgres](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres) 是建置在[節點-postgres](https://node-postgres.com/) 上的 Node.js 連接器，整合 IAM 身分驗證，以將 JavaScript/TypeScript 應用程式連線至 Amazon Aurora DSQL 叢集。
Aurora DSQL Connector 設計為身分驗證外掛程式，可延伸節點後綴的用戶端和集區功能，讓應用程式使用 IAM 憑證向 Amazon Aurora DSQL 進行身分驗證。
## 關於 連接器
Amazon Aurora DSQL 是與 PostgreSQL 相容的雲端原生分散式資料庫。雖然它需要 IAM 身分驗證和時間限制權杖，但傳統 Node.js 資料庫驅動程式缺少此內建支援。
Aurora DSQL Connector for node-postgres 透過實作與節點-postgres 無縫搭配的身分驗證中介軟體來彌補此差距。此方法可讓開發人員維護現有的節點後置程式碼，同時透過自動化權杖管理取得 Aurora DSQL 叢集的安全 IAM 型存取。
### 什麼是 Aurora DSQL 身分驗證？
在 Aurora DSQL 中，身分驗證涉及：
+ **IAM 身分驗證**：所有連線都使用具有時間限制權杖的 IAM 型身分驗證
+ **權杖產生：**使用 AWS 登入資料產生身分驗證權杖，並具有可設定的生命週期
Aurora DSQL Connector for node-postgres 旨在了解這些要求，並在建立連線時自動產生 IAM 身分驗證字符。
### 功能
+ **自動 IAM 身分驗證** - 處理 DSQL 字符產生和重新整理
+ **建置在 Node-postgres** 上 - 利用 Node.js 的熱門 PostgreSQL 用戶端
+ **無縫整合** - 適用於現有的節點後置連線模式
+ **區域自動探索 -** 從 DSQL 叢集主機名稱擷取 AWS 區域
+ **完整 TypeScript 支援** - 提供完整類型安全
+ **AWS 登入資料支援** - 支援各種 AWS 登入資料提供者 （預設、設定檔型、自訂）
+ **連線集區相容性** - 可與內建連線集區無縫搭配使用
## 範例應用程式
[範例中](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/node-postgres/example)包含一個範例應用程式，示範如何使用 Aurora DSQL Connector for node-postgres。若要執行包含的範例，請參閱範例 [README](https://github.com/awslabs/aurora-dsql-connectors/blob/main/node/node-postgres/example/README.md)。
## 快速入門指南
### 要求
+ Node.js 20\$1
+ [存取 Aurora DSQL 叢集](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ 設定適當的 IAM 權限，以允許應用程式連線到 Aurora DSQL。
+ 已設定的 AWS 登入資料 （透過 AWS CLI、環境變數或 IAM 角色）
## 安裝
```
npm install @aws/aurora-dsql-node-postgres-connector
```
## 對等相依性
```
npm install @aws-sdk/credential-providers @aws-sdk/dsql-signer pg tsx
npm install --save-dev @types/pg
```
## Usage
### 用戶端連線
```
import { AuroraDSQLClient } from "@aws/aurora-dsql-node-postgres-connector";
const client = new AuroraDSQLClient({
host: "",
user: "admin",
});
await client.connect();
const result = await client.query("SELECT NOW()");
await client.end();
```
### 集區連線
```
import { AuroraDSQLPool } from "@aws/aurora-dsql-node-postgres-connector";
const pool = new AuroraDSQLPool({
host: "",
user: "admin",
max: 3,
idleTimeoutMillis: 60000,
});
const result = await pool.query("SELECT NOW()");
```
### 進階使用方式
```
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();
```
## 組態選項
| 選項 | Type | 必要 | 描述 |
| --- | --- | --- | --- |
| host | string | 是 | DSQL 叢集主機名稱 |
| username | string | 是 | DSQL 使用者名稱 |
| database | string | 否 | 資料庫名稱 |
| region | string | 否 | AWS 區域 （若未提供，則從主機名稱自動偵測） |
| port | number | 否 | 預設為 5432 |
| customCredentialsProvider | AwsCredentialIdentity / AwsCredentialIdentityProvider | 否 | 自訂 AWS 登入資料提供者 |
| profile | string | 否 | IAM 設定檔名稱。預設為「預設」 |
| tokenDurationSecs | number | 否 | 字符過期時間，以秒為單位 |
[用戶端](https://node-postgres.com/apis/client)/[集區的](https://node-postgres.com/apis/pool)所有其他參數都受到支援。
## 身分驗證
連接器會使用 DSQL 用戶端字符產生器產生字符，以自動處理 DSQL 身分驗證。如果未提供 AWS 區域，則會自動從提供的主機名稱剖析。
如需 Aurora DSQL 中身分驗證的詳細資訊，請參閱 [使用者指南](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html)。
### 管理員與一般使用者
+ 名為「admin」的使用者會自動使用管理員身分驗證字符
+ 所有其他使用者都使用一般身分驗證字符
+ 權杖會為每個連線動態產生
# 適用於 Postgres.js 的 Aurora DSQL 連接器
[Aurora DSQL Connector for Postgres.js](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js) 是建置在 [Postgres.js 上的 Node.js](https://github.com/porsager/postgres) 連接器，整合 IAM 身分驗證，以將 JavaScript 應用程式連線至 Amazon Aurora DSQL 叢集。
Aurora DSQL Connector for Postgres.js 設計為身分驗證外掛程式，可延伸 Postgres.js 用戶端的功能，讓應用程式使用 IAM 憑證向 Amazon Aurora DSQL 進行身分驗證。連接器不會直接連線至資料庫，而是在基礎 Postgres.js 驅動程式上提供無縫的 IAM 身分驗證。
## 關於 連接器
Amazon Aurora DSQL 是一種分散式 SQL 資料庫服務，可為 PostgreSQL 相容應用程式提供高可用性和可擴展性。Aurora DSQL 需要具有現有 Node.js 驅動程式原生不支援的時間限制權杖的 IAM 型身分驗證。
Aurora DSQL Connector for Postgres.js 背後的概念是在處理產生 IAM 字符的 Postgres.js 用戶端上新增身分驗證層，允許使用者連線到 Aurora DSQL，而無需變更現有的 Postgres.js 工作流程。
Aurora DSQL Connector for Postgres.js 適用於大多數版本的 Postgres.js。使用者透過直接安裝 Postgres.js 來提供自己的版本。
### 什麼是 Aurora DSQL 身分驗證？
在 Aurora DSQL 中，身分驗證涉及：
+ **IAM 身分驗證**：所有連線都使用具有時間限制權杖的 IAM 型身分驗證
+ **權杖產生：**使用 AWS 登入資料產生身分驗證權杖，並具有可設定的生命週期
Aurora DSQL Connector for Postgres.js 旨在了解這些要求，並在建立連線時自動產生 IAM 身分驗證字符。
### 功能
+ **自動 IAM 身分驗證** - 處理 DSQL 字符產生和重新整理
+ 在 **Postgres.js 上建置** - 利用 Node.js 的快速 PostgreSQL 用戶端
+ **無縫整合** - 適用於現有的 Postgres.js 連線模式
+ **Region Auto-Discovery** - 從 DSQL 叢集主機名稱擷取 AWS 區域
+ **完整 TypeScript 支援** - 提供完整類型安全
+ **AWS 登入資料支援** - 支援各種 AWS 登入資料提供者 （預設、設定檔型、自訂）
+ **連線集區相容性** - 可與 Postgres.js 的內建連線集區無縫搭配使用
## 快速入門指南
### 要求
+ Node.js 20\$1
+ [存取 Aurora DSQL 叢集](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ 設定適當的 IAM 權限，以允許應用程式連線到 Aurora DSQL。
+ 已設定的 AWS 登入資料 （透過 AWS CLI、環境變數或 IAM 角色）
### 安裝
```
npm install @aws/aurora-dsql-postgresjs-connector
# Postgres.js is a peer-dependency, so users must install it themselves
npm install postgres
```
### 基本使用
```
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 而非主機
```
const sql = auroraDSQLPostgres({
host: 'your-cluster-id',
region: 'us-east-1',
username: 'admin',
});
```
### 連線字串
```
const sql = AuroraDSQLPostgres(
'postgres://admin@your-cluster.dsql.us-east-1.on.aws'
);
const result = await sql`SELECT current_timestamp`;
```
### 進階組態
```
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
});
```
## 組態選項
| 選項 | Type | 必要 | 描述 |
| --- | --- | --- | --- |
| 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)。
## 身分驗證
連接器會自動處理 DSQL 身分驗證，方法是使用 DSQL 用戶端字符產生器產生字符。如果未提供 AWS 區域，則會自動從提供的主機名稱剖析。
如需 Aurora DSQL 中身分驗證的詳細資訊，請參閱 [使用者指南](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html)。
### 管理員與一般使用者
+ 名為「admin」的使用者會自動使用管理員身分驗證字符
+ 所有其他使用者都使用一般身分驗證字符
+ 權杖會為每個連線動態產生
## 範例用量
使用 Aurora DSQL Connector for Postgres.js 的 JavaScript 範例可在 GitHub 上取得。如需如何執行範例的說明，請參閱[範例目錄](https://github.com/awslabs/aurora-dsql-connectors/tree/main/node/postgres-js/example)。
| Description | 範例 |
| --- | --- |
| 具有並行查詢的連線集區，包括跨多個工作者建立、插入和讀取資料表 | [連線集區範例 （偏好）](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) |