# .NET コネクタを使用した Aurora DSQL クラスターへの接続
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql"></a>

[.NET 用 Amazon Aurora DSQL コネクタ](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql)は、.NET アプリケーションを Amazon Aurora DSQL クラスターに接続するための IAM 認証を統合した [Npgsql](https://www.npgsql.org/) 上に構築された .NET コネクタです。

このコネクタは、トークン生成、SSL 設定、接続プーリングを処理し、ユーザーがアプリケーションロジックに集中できるようにします。

## コネクタについて
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-about"></a>

Amazon Aurora DSQL には、既存の .NET PostgreSQL ドライバーがネイティブにサポートしていない時限トークンを使用した IAM 認証が必要です。.NET 用 Aurora DSQL コネクタは、IAM トークン生成を処理する Npgsql 上に認証レイヤーを追加し、既存の Npgsql ワークフローを変更せずに Aurora DSQL に接続できるようにします。

### Aurora DSQL 認証とは
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-authentication"></a>

Aurora DSQL では、**認証**に以下が含まれます。
+ **IAM 認証**: すべての接続で、時間制限付きトークンによる IAM ベースの認証が使用されます
+ **トークン生成**: コネクタは AWS 認証情報を使用して認証トークンを生成します。これらのトークンの有効期間は設定可能です。

.NET 用 Aurora DSQL コネクタは、これらの要件を理解し、接続の確立時に IAM 認証トークンを自動的に生成します。

### 機能
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-features"></a>
+ **自動 IAM 認証** - Aurora DSQL トークンの生成と更新を処理
+ **Npgsql 上に構築** - .NET 用の一般的な PostgreSQL ドライバーをラップ
+ **シームレスな統合** - 既存の Npgsql ワークフローと連携
+ **接続プーリング** - 最大有効期間を強制する `NpgsqlDataSource` を利用した組み込みサポート
+ **リージョンの自動検出** - Aurora DSQL クラスターホスト名から AWS リージョンを抽出
+ **AWS 認証情報のサポート**: AWS プロファイルとカスタム認証情報プロバイダーをサポート
+ **OCC 再試行** - エクスポネンシャルバックオフを使用したオプトインのオプティミスティック同時実行制御の再試行
+ **SSL 適用** - 常に `verify-full` モードと直接 TLS ネゴシエーションで SSL を使用

## サンプルアプリケーション
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-example-application"></a>

詳細な例については、GitHub の[サンプルアプリケーション](https://github.com/awslabs/aurora-dsql-connectors/tree/main/dotnet/npgsql/example)を参照してください。

## クイックスタートガイド
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-quick-start"></a>

### 要件
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-requirements"></a>
+ .NET 8.0 以降
+ [Aurora DSQL クラスターへのアクセス](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ AWS 認証情報の設定 (AWS CLI、環境変数、または IAM ロール経由)。

## インストール
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-installation"></a>

パッケージをプロジェクトに追加します。

```
dotnet add package Amazon.AuroraDsql.Npgsql
```

## Usage
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-usage"></a>

### プール接続
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-pool-connection"></a>

```
using Amazon.AuroraDsql.Npgsql;

// Create a connection pool
await using var ds = await AuroraDsql.CreateDataSourceAsync(new DsqlConfig
{
    Host = "your-cluster.dsql.us-east-1.on.aws",
    OccMaxRetries = 3
});

// Read
await using (var conn = await ds.OpenConnectionAsync())
{
    await using var cmd = conn.CreateCommand();
    cmd.CommandText = "SELECT 'Hello, DSQL!'";
    var greeting = await cmd.ExecuteScalarAsync();
    Console.WriteLine(greeting);
}

// Transactional write with OCC retry
await ds.WithTransactionRetryAsync(async conn =>
{
    await using var cmd = conn.CreateCommand();
    cmd.CommandText = "INSERT INTO users (id, name) VALUES (gen_random_uuid(), @name)";
    cmd.Parameters.AddWithValue("name", "Alice");
    await cmd.ExecuteNonQueryAsync();
});
```

### シングル接続
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-single-connection"></a>

シンプルなスクリプトの場合、または接続プーリングが必要ない場合。

```
await using var conn = await AuroraDsql.ConnectAsync(new DsqlConfig
{
    Host = "your-cluster.dsql.us-east-1.on.aws"
});

await using var cmd = conn.CreateCommand("SELECT 1");
await cmd.ExecuteScalarAsync();
```

### OCC 再試行
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-occ-retry"></a>

Aurora DSQL は、オプティミスティック同時実行制御 (OCC) を使用します。2 つのトランザクションが同じデータを変更する場合、最初のトランザクションはコミットに成功し、2 番目のトランザクションは OCC エラーを受け取ります。

OCC 再試行はオプトインです。エクスポネンシャルバックオフとジッターによる自動再試行を有効にするには、config で `OccMaxRetries` を設定します。トランザクション書き込みには、`WithTransactionRetryAsync` を使用します。

```
await ds.WithTransactionRetryAsync(async conn =>
{
    await using var cmd = conn.CreateCommand();

    cmd.CommandText = "UPDATE accounts SET balance = balance - 100 WHERE id = @from";
    cmd.Parameters.AddWithValue("from", fromId);
    await cmd.ExecuteNonQueryAsync();

    cmd.CommandText = "UPDATE accounts SET balance = balance + 100 WHERE id = @to";
    cmd.Parameters.Clear();
    cmd.Parameters.AddWithValue("to", toId);
    await cmd.ExecuteNonQueryAsync();
});
```

DDL または単一ステートメントには、`ExecWithRetryAsync` を使用します。

```
await ds.ExecWithRetryAsync("CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)");
```

**重要**  
`WithTransactionRetryAsync` は `BEGIN`/`COMMIT`/`ROLLBACK` を内部的に管理し、試行ごとに新しい接続を開きます。コールバックは、データベースオペレーションのみを含むものとし、再試行しても安全であることが必要です。

## 設定オプション
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-configuration"></a>

コネクタは、`region` および `profile` クエリパラメータを持つ `postgres://` および `postgresql://` 接続文字列も受け入れます。


| フィールド | タイプ | デフォルト  | 説明  | 
| --- | --- | --- | --- | 
| Host | string | (必須) | クラスターエンドポイントまたは 26 文字のクラスター ID | 
| Region | string? | (自動検出) | AWS リージョン (Host がクラスター ID の場合は必須) | 
| User | string | "admin" | データベースユーザー | 
| Database | string | "postgres" | データベース名 | 
| Port | int | 5432 | データベースポート | 
| Profile | string? | null | 認証情報の AWS プロファイル名 | 
| CustomCredentialsProvider | AWSCredentials? | null | カスタム AWS 認証情報プロバイダー | 
| TokenDurationSecs | int? | null (SDK デフォルト、900 秒) | トークンの有効期間 (秒) | 
| OccMaxRetries | int? | null (無効) | データソースに対する再試行メソッドのデフォルトの最大 OCC 再試行回数 | 
| OrmPrefix | string? | null | application\$1name の先頭に付加される ORM プレフィックス | 
| LoggerFactory | ILoggerFactory? | null | 再試行の警告と診断のためのロガーファクトリー | 
| ConfigureConnectionString | Action<NpgsqlConnectionStringBuilder>? | null | プール設定を上書きしたり、追加の Npgsql 接続文字列プロパティを設定したりするためのコールバック。SSL と Enlist は必須のセキュリティ要件であり、上書きすることはできません。 | 

## 認証
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-auth"></a>

コネクタは、AWS 認証情報を使用してトークンを生成することで、Aurora DSQL 認証を自動的に処理します。AWS リージョンを指定しない場合、コネクタはホスト名からリージョンを解析します。

Aurora DSQL の認証の詳細については、「[Aurora DSQL の認証および認可](authentication-authorization.md)」を参照してください。

### 管理者ユーザーと通常のユーザー
<a name="SECTION_program-with-dsql-connector-for-dotnet-npgsql-admin-vs-regular"></a>
+ 「admin」という名前のユーザーは、管理者認証トークンを自動的に使用します。
+ 他のすべてのユーザーは通常の認証トークンを使用します。
+ コネクタは、接続ごとにトークンを動的に生成します。