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

# Aurora DSQL Connector for Go pgx
<a name="SECTION_program-with-go-pgx-connector"></a>

[Aurora DSQL Connector for Go](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx) 使用自動 IAM 身分驗證包裝 [pgx](https://github.com/jackc/pgx)。連接器會處理字符產生、SSL 組態和連線管理，讓您可以專注於應用程式邏輯。

## 關於連接器
<a name="SECTION_program-with-go-pgx-connector-about"></a>

Aurora DSQL 需要具有現有 Go PostgreSQL 驅動程式原生不支援的時間限制權杖的 IAM 型身分驗證。Aurora DSQL Connector for Go 在處理 IAM 字符產生的 pgx 驅動程式上新增了身分驗證層，可讓您連線到 Aurora DSQL，而無需變更現有的 pgx 工作流程。

### 什麼是 Aurora DSQL 身分驗證？
<a name="SECTION_program-with-go-pgx-connector-authentication"></a>

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

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

### Aurora DSQL Connector for Go 的優點
<a name="SECTION_program-with-go-pgx-connector-benefits"></a>

Aurora DSQL Connector for Go 可讓您繼續使用現有的 pgx 工作流程，同時透過下列方式啟用 IAM 身分驗證：
+ **自動產生權杖**：連接器會為每個連線自動產生 IAM 權杖
+ **連線集區**： 內建支援`pgxpool`，每個連線可自動產生字符
+ **彈性組態**：支援具有區域自動偵測功能的完整端點或叢集 IDs 
+ **AWS 登入資料支援**：支援 AWS 設定檔和自訂登入資料供應商

## 主要功能
<a name="SECTION_program-with-go-pgx-connector-features"></a>

自動字符管理  
連接器會使用預先解析的登入資料，為每個新連線自動產生 IAM 字符。

連線集區  
透過 與每個連線自動產生字符`pgxpool`的連線集區。

彈性主機組態  
支援完整叢集端點和具有自動區域偵測IDs。

SSL 安全性  
SSL 一律會啟用完全驗證模式和直接 TLS 交涉。

## 先決條件
<a name="SECTION_program-with-go-pgx-connector-prerequisites"></a>
+ Go 1.24 或更新版本
+ AWS 已設定的登入資料
+ Aurora DSQL 叢集

連接器使用[AWS 適用於 Go v2 的 SDK 預設登入資料鏈](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html#specifying-credentials)，依下列順序解析登入資料：

1. 環境變數 (AWS\_ACCESS\_KEY\_ID、AWS\_SECRET\_ACCESS\_KEY)

1. 共用登入資料檔案 (\~/.aws/credentials)

1. 共用組態檔案 (\~/.aws/config)

1. Amazon EC2/ECS/Lambda 的 IAM 角色

## 安裝
<a name="SECTION_program-with-go-pgx-connector-installation"></a>

使用 Go 模組安裝連接器：

```
go get github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql
```

## 快速入門
<a name="SECTION_program-with-go-pgx-connector-quick-start"></a>

下列範例示範如何建立連線集區並執行查詢：

```
package main

import (
    "context"
    "log"

    "github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql"
)

func main() {
    ctx := context.Background()

    // Create a connection pool
    pool, err := dsql.NewPool(ctx, dsql.Config{
        Host: "your-cluster.dsql.us-east-1.on.aws",
    })
    if err != nil {
        log.Fatal(err)
    }
    defer pool.Close()

    // Execute a query
    var greeting string
    err = pool.QueryRow(ctx, "SELECT 'Hello, DSQL!'").Scan(&greeting)
    if err != nil {
        log.Fatal(err)
    }
    log.Println(greeting)
}
```

## 組態選項
<a name="SECTION_program-with-go-pgx-connector-configuration"></a>

連接器支援下列組態選項：


| 欄位 | Type | 預設 | 說明 | 
| --- | --- | --- | --- | 
| 主機 | string | （必要） | 叢集端點或叢集 ID | 
| 區域 | string | （自動偵測） | AWS region；如果主機是叢集 ID，則為必要 | 
| 使用者 | string | 「管理員」 | 資料庫使用者 | 
| 資料庫 | string | 「postgres」 | 資料庫名稱 | 
| 站點 | int | 5432 | Database port (資料庫連線埠) | 
| 設定檔 | string | "" | AWS 登入資料的設定檔名稱 | 
| TokenDurationSecs | int | 900 (15 分鐘） | 字符有效性持續時間，以秒為單位 （允許上限：1 週，預設值：15 分鐘） | 
| MaxConns | int32 | 0 | 集區連線上限 (0 = pgxpool 預設） | 
| MinConns | int32 | 0 | 最低集區連線數 (0 = pgxpool 預設） | 
| MaxConnLifetime | time.Duration | 55 分鐘 | 最大連線生命週期 | 

## 連線字串格式
<a name="SECTION_program-with-go-pgx-connector-connection-string"></a>

連接器支援 PostgreSQL 和 DSQL 連線字串格式：

```
postgres://[user@]host[:port]/[database][?param=value&...]
dsql://[user@]host[:port]/[database][?param=value&...]
```

支援的查詢參數：
+ `region` - AWS 區域
+ `profile` - AWS 設定檔名稱
+ `tokenDurationSecs` - 字符有效持續時間，以秒為單位

範例：

```
// Full endpoint (region auto-detected)
pool, _ := dsql.NewPool(ctx, "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres")

// Using dsql:// scheme (also supported)
pool, _ := dsql.NewPool(ctx, "dsql://admin@cluster.dsql.us-east-1.on.aws/postgres")

// With explicit region
pool, _ := dsql.NewPool(ctx, "postgres://admin@cluster.dsql.us-east-1.on.aws/mydb?region=us-east-1")

// With AWS profile
pool, _ := dsql.NewPool(ctx, "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres?profile=dev")
```

## 進階用量
<a name="SECTION_program-with-go-pgx-connector-advanced"></a>

### 主機組態
<a name="SECTION_program-with-go-pgx-connector-host-config"></a>

連接器支援兩種主機格式：

**完整端點** （區域自動偵測）：

```
pool, _ := dsql.NewPool(ctx, dsql.Config{
    Host: "your-cluster.dsql.us-east-1.on.aws",
})
```

**叢集 ID** （需要區域）：

```
pool, _ := dsql.NewPool(ctx, dsql.Config{
    Host:   "your-cluster-id",
    Region: "us-east-1",
})
```

### 集區組態調校
<a name="SECTION_program-with-go-pgx-connector-pool-tuning"></a>

為您的工作負載設定連線集區：

```
pool, err := dsql.NewPool(ctx, dsql.Config{
    Host:              "your-cluster.dsql.us-east-1.on.aws",
    MaxConns:          20,
    MinConns:          5,
    MaxConnLifetime:   time.Hour,
    MaxConnIdleTime:   30 * time.Minute,
    HealthCheckPeriod: time.Minute,
})
```

### 單一連線用量
<a name="SECTION_program-with-go-pgx-connector-single-connection"></a>

對於簡單的指令碼或不需要連線集區時：

```
conn, err := dsql.Connect(ctx, dsql.Config{
    Host: "your-cluster.dsql.us-east-1.on.aws",
})
if err != nil {
    log.Fatal(err)
}
defer conn.Close(ctx)

// Use the connection
rows, err := conn.Query(ctx, "SELECT * FROM users")
```

### 使用 AWS 設定檔
<a name="SECTION_program-with-go-pgx-connector-aws-profiles"></a>

指定登入資料的 AWS 設定檔：

```
pool, err := dsql.NewPool(ctx, dsql.Config{
    Host:    "your-cluster.dsql.us-east-1.on.aws",
    Profile: "production",
})
```

## OCC 重試
<a name="SECTION_program-with-go-pgx-connector-occ-retry"></a>

Aurora DSQL 使用樂觀並行控制 (OCC)。當兩個交易修改相同的資料時，第一個遞交獲勝，第二個收到 OCC 錯誤。

`occretry` 套件為具有指數退避和抖動的自動重試提供了協助程式。搭配 進行安裝：

```
go get github.com/awslabs/aurora-dsql-connectors/go/pgx/occretry
```

`WithRetry` 用於交易寫入：

```
err := occretry.WithRetry(ctx, pool, occretry.DefaultConfig(), func(tx pgx.Tx) error {
    _, err := tx.Exec(ctx, "UPDATE accounts SET balance = balance - $1 WHERE id = $2", 100, fromID)
    if err != nil {
        return err
    }
    _, err = tx.Exec(ctx, "UPDATE accounts SET balance = balance + $1 WHERE id = $2", 100, toID)
    return err
})
```

對於 DDL 或單一陳述式，請使用 `ExecWithRetry`：

```
err := occretry.ExecWithRetry(ctx, pool, occretry.DefaultConfig(),
    "CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)")
```

**重要**  
`WithRetry` 會在內部管理 `BEGIN`/`COMMIT`/`ROLLBACK`。您的回呼會收到交易，並且應該只包含資料庫操作，並且可以安全地重試。

## 範例
<a name="SECTION_program-with-go-pgx-connector-examples"></a>

如需更完整的範例和使用案例，請參閱 [Aurora DSQL Connector for Go 範例](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example)。


| 範例 | 說明 | 
| --- | --- | 
|  [example\_preferred](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/example_preferred.go)  | 建議：具有並行查詢的連線集區 | 
|  [交易](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/transaction)  | 使用 BEGIN/COMMIT/ROLLBACK 處理交易 | 
|  [occ\_retry](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/occ_retry)  | 處理 OCC 與指數退避衝突 | 
|  [connection\_string](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/connection_string)  | 使用連線字串進行組態 |