# 使用 Go 连接器连接到 Aurora DSQL 集群
<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 要求使用基于 IAM 的身份验证以及限时令牌，而现有 Go PostgreSQL 驱动程序并不原生支持这种方法。适用于 Go 的 Aurora DSQL 连接器在 pgx 驱动程序之上添加一个身份验证层来处理 IAM 令牌生成，使您无需更改现有 pgx 工作流程即可连接到 Aurora DSQL。

### 什么是 Aurora DSQL 身份验证？
<a name="SECTION_program-with-go-pgx-connector-authentication"></a>

在 Aurora DSQL 中，**身份验证**包括：
+ **IAM 身份验证**：所有连接都使用基于 IAM 的身份验证和限时令牌
+ **令牌生成**：连接器使用 AWS 凭证生成身份验证令牌，并且这些令牌具有可配置的生命周期

适用于 Go 的 Aurora DSQL 连接器旨在满足这些要求，并在建立连接时自动生成 IAM 身份验证令牌。

### 适用于 Go 的 Aurora DSQL 连接器的优势
<a name="SECTION_program-with-go-pgx-connector-benefits"></a>

通过适用于 Go 的 Aurora DSQL 连接器，您可以继续使用现有的 pgx 工作流程，同时通过以下方式启用 IAM 身份验证：
+ **自动生成令牌**：连接器会自动为每个连接生成 IAM 令牌
+ **连接池**：内置对 `pgxpool` 的支持，对于每个连接自动生成令牌
+ **灵活的配置**：通过区域自动检测功能支持完整端点或集群 ID
+ **AWS 凭证支持**：支持 AWS 配置文件和自定义凭证提供商

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

自动令牌管理  
连接器使用预先解析的凭证为每个新连接自动生成 IAM 令牌。

连接池  
通过 `pgxpool` 实现连接池，对于每个连接自动生成令牌。

灵活的主机配置  
通过自动区域检测功能同时支持完整集群端点或集群 ID。

SSL 安全性  
SSL 始终处于启用状态，具有完整验证模式和直接 TLS 协商。

## 先决条件
<a name="SECTION_program-with-go-pgx-connector-prerequisites"></a>
+ Go 1.24 或更高版本
+ 配置了 AWS 凭证
+ 一个 Aurora DSQL 集群

此连接器使用[适用于 Go 的 AWS SDK v2 默认凭证链](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html#specifying-credentials)，该凭证链按以下顺序解析凭证：

1. 环境变量 (AWS\$1ACCESS\$1KEY\$1ID、AWS\$1SECRET\$1ACCESS\$1KEY)

1. 共享的凭证文件（\$1/.aws/credentials）

1. 共享的配置文件（\$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>

此连接器支持以下配置选项：


| 字段 | 类型 | 默认值 | 说明 | 
| --- | --- | --- | --- | 
| 主机 | 字符串 | （必需） | 集群端点或集群 ID | 
| 区域 | 字符串 | （自动检测） | AWS 区域；如果主机是集群 ID，则为必需 | 
| 用户 | 字符串 | “admin” | 数据库用户 | 
| 数据库 | 字符串 | “postgres” | 数据库名称 | 
| 端口 | int | 5432 | 数据库端口 | 
| 配置文件 | 字符串 | "" | 凭证的 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>

有关更全面的示例和使用案例，请参阅[适用于 Go 的 Aurora DSQL 连接器示例](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example)。


| 示例 | 说明 | 
| --- | --- | 
|  [example\$1preferred](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\$1retry](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/occ_retry)  | 使用指数回退处理 OCC 冲突 | 
|  [connection\$1string](https://github.com/awslabs/aurora-dsql-connectors/tree/main/go/pgx/example/src/connection_string)  | 使用连接字符串进行配置 |