# Go コネクタを使用した Aurora DSQL クラスターへの接続
<a name="SECTION_program-with-go-pgx-connector"></a>

[Go 用 Aurora DSQL コネクタ](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 ベースの認証が必要です。Go 用 Aurora DSQL コネクタは、IAM トークン生成を処理する pgx ドライバーの上に認証レイヤーを追加し、既存の 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 コネクタを使用すると、以下の方法で IAM 認証を有効にしながら、既存の pgx ワークフローを引き続き使用できます。
+ **自動トークン生成**: コネクタは、接続ごとに IAM トークンを自動的に生成します。
+ **接続プーリング**: 接続ごとにトークンを自動生成する `pgxpool` の組み込みサポート
+ **柔軟な設定**: リージョンの自動検出による完全なエンドポイントまたはクラスター ID のサポート
+ **AWS 認証情報のサポート**: AWS プロファイルとカスタム認証情報プロバイダーをサポート

## 主な特徴
<a name="SECTION_program-with-go-pgx-connector-features"></a>

自動トークン管理  
コネクタは、事前に解決された認証情報を使用して、新しい接続ごとに IAM トークンを自動生成します。

接続プーリング  
接続ごとにトークンを自動生成する `pgxpool` を利用した接続プーリング。

柔軟なホスト設定  
自動リージョン検出を備えた完全なクラスターエンドポイントとクラスター ID の両方をサポートします。

SSL セキュリティ  
SSL は verify-full モードと直接 TLS ネゴシエーションで常に有効になります。

## 前提条件
<a name="SECTION_program-with-go-pgx-connector-prerequisites"></a>
+ Go 1.24 以降
+ AWS 認証情報が設定されている
+ Aurora DSQL クラスター

コネクタは [AWS SDK for Go 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>

このコネクタでは以下の設定オプションがサポートされています。


| フィールド | タイプ | デフォルト  | 説明  | 
| --- | --- | --- | --- | 
| ホスト | string | (必須) | クラスターエンドポイントまたはクラスター ID | 
| リージョン | string | (自動検出) | AWS リージョン (Host がクラスター ID の場合は必須) | 
| ユーザー | string | 「admin」 | データベースユーザー | 
| データベース | string | 「postgres」 | データベース名 | 
| ポート | int | 5432 | データベースポート | 
| プロファイル | 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>

コネクタは次の 2 つのホスト形式をサポートしています。

**フルエンドポイント** (リージョンの自動検出)。

```
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) を使用します。2 つのトランザクションが同じデータを変更する場合、最初のトランザクションはコミットに成功し、2 番目のトランザクションは 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)  | 設定に接続文字列を使用する |