本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 適用於節點後置的 Aurora DSQL 連接器
<a name="SECTION_program-with-dsql-connector-for-node-postgres"></a>

 [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 進行身分驗證。

## 關於 連接器
<a name="about-the-connector"></a>

 Amazon Aurora DSQL 是與 PostgreSQL 相容的雲端原生分散式資料庫。雖然它需要 IAM 身分驗證和時間限制權杖，但傳統 Node.js 資料庫驅動程式缺少此內建支援。

 Aurora DSQL Connector for node-postgres 透過實作與節點-postgres 無縫搭配的身分驗證中介軟體來彌補此差距。此方法可讓開發人員維護現有的節點後置程式碼，同時透過自動化權杖管理取得 Aurora DSQL 叢集的安全 IAM 型存取。

### 什麼是 Aurora DSQL 身分驗證？
<a name="what-is-aurora-dsql-authentication"></a>

 在 Aurora DSQL 中，身分驗證涉及：
+  **IAM 身分驗證**：所有連線都使用具有時間限制權杖的 IAM 型身分驗證 
+  **權杖產生：**使用 AWS 登入資料產生身分驗證權杖，並具有可設定的生命週期 

 Aurora DSQL Connector for node-postgres 旨在了解這些要求，並在建立連線時自動產生 IAM 身分驗證字符。

### 功能
<a name="features"></a>
+  **自動 IAM 身分驗證** - 處理 DSQL 字符產生和重新整理 
+  **建置在 Node-postgres** 上 - 利用 Node.js 的熱門 PostgreSQL 用戶端 
+  **無縫整合** - 適用於現有的節點後置連線模式 
+  **區域自動探索 -** 從 DSQL 叢集主機名稱擷取 AWS 區域 
+  **完整 TypeScript 支援** - 提供完整類型安全 
+  **AWS 登入資料支援** - 支援各種 AWS 登入資料提供者 （預設、設定檔型、自訂） 
+  **連線集區相容性** - 可與內建連線集區無縫搭配使用 

## 範例應用程式
<a name="example-application"></a>

 [範例中](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)。

## 快速入門指南
<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) 
+  設定適當的 IAM 權限，以允許應用程式連線到 Aurora DSQL。
+  已設定的 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>


|  選項  |  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)所有其他參數都受到支援。

## 身分驗證
<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」的使用者會自動使用管理員身分驗證字符 
+  所有其他使用者都使用一般身分驗證字符 
+  權杖會為每個連線動態產生