# PHP `PDO_PGSQL` 用 Aurora DSQL コネクタ
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql"></a>

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

コネクタはトークン生成、SSL 設定、および接続管理を処理するため、ユーザーはアプリケーションロジックに集中できます。

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

PHP 用 Aurora DSQL コネクタは、IAM トークン生成を処理する `PDO_PGSQL` 上に認証レイヤーを追加し、既存の PDO ワークフローを使用して Aurora DSQL に接続できるようにします。Amazon Aurora DSQL には、時間制限付きトークンによる IAM 認証が必要であり、コネクタは自動的にトークン生成を管理します。

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

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

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

### 機能
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-features"></a>
+ **自動 IAM 認証** - Aurora DSQL トークンの生成と更新を処理
+ **`PDO_PGSQL` 上に構築** - PHP 用の標準の PostgreSQL 拡張機能をラップ
+ **シームレスな統合** - 既存の PDO ワークフローと連携
+ **SSL 適用** - 常に `verify-full` モードと直接 TLS ネゴシエーションで SSL を使用
+ **リージョンの自動検出** - Aurora DSQL クラスターホスト名から AWS リージョンを抽出
+ **AWS 認証情報のサポート**: AWS プロファイルとカスタム認証情報プロバイダーをサポート
+ **OCC 再試行** - エクスポネンシャルバックオフとジッターを使用したオプトインのオプティミスティック同時実行制御の再試行
+ **PSR-3 ログ記録** - 再試行診断用の互換性のあるログ記録

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

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

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

### 要件
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-requirements"></a>
+ PHP 8.2 以降
+ `ext-pdo_pgsql` エクステンション
+ [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-php-pdo-pgsql-installation"></a>

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

```
composer require awslabs/aurora-dsql-pdo-pgsql
```

## Usage
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-usage"></a>

### 設定ベースの接続
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-config-connection"></a>

```
<?php

require_once 'vendor/autoload.php';

use Aws\AuroraDsql\PdoPgsql\AuroraDsql;
use Aws\AuroraDsql\PdoPgsql\DsqlConfig;

$config = new DsqlConfig(
    host: 'your-cluster.dsql.us-east-1.on.aws',
    occMaxRetries: 3
);
$pdo = AuroraDsql::connect($config);

// Read
$stmt = $pdo->query('SELECT 1 AS result');
$row = $stmt->fetch(PDO::FETCH_ASSOC);
echo "Connected: {$row['result']}\n";

// Transactional write with automatic OCC retry
$id = $pdo->transaction(function (PDO $conn): string {
    $stmt = $conn->prepare('INSERT INTO users (name) VALUES (?) RETURNING id');
    $stmt->execute(['Alice']);
    return $stmt->fetchColumn();
});
```

### 接続文字列形式
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-connection-string"></a>

シンプルなスクリプトの場合、または接続文字列構文を使用する場合、コネクタは Aurora DSQL 固有のクエリパラメータを使用して `postgres://` および `postgresql://` 接続文字列をサポートします。

```
$pdo = AuroraDsql::connectFromDsn(
    'postgres://admin@your-cluster.dsql.us-east-1.on.aws/postgres?region=us-east-1'
);
```

サポートされているクエリパラメータ: `region`、`profile`、`tokenDurationSecs`、`ormPrefix`。

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

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

OCC 再試行はオプトインです。エクスポネンシャルバックオフとジッターによる自動再試行を有効にするには、config で `occMaxRetries` を設定します。

```
$config = new DsqlConfig(
    host: 'your-cluster.dsql.us-east-1.on.aws',
    occMaxRetries: 3
);
$pdo = AuroraDsql::connect($config);

// Single statements are automatically retried via exec()
$pdo->exec("CREATE INDEX ASYNC ON users (email)");

// Multi-statement transactions are retried via transaction()
$pdo->transaction(function (PDO $conn) {
    $conn->exec("UPDATE accounts SET balance = balance - 100 WHERE id = 1");
    $conn->exec("UPDATE accounts SET balance = balance + 100 WHERE id = 2");
});
```

**重要**  
`transaction()` は `beginTransaction()`/`commit()`/`rollBack()` を内部的に管理します。コールバックは、データベースオペレーションのみを含むものとし、再試行しても安全であることが必要です。

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

コネクタは、設定用のクエリパラメータを持つ `postgres://` および `postgresql://` 接続文字列も受け入れます。サポートされているクエリパラメータ: `region`、`profile`、`tokenDurationSecs`、`ormPrefix`。


| フィールド | タイプ | デフォルト  | 説明  | 
| --- | --- | --- | --- | 
| host | string | (必須) | クラスターエンドポイントまたは 26 文字のクラスター ID | 
| region | ?string | null (自動検出) | AWS リージョン (host がクラスター ID の場合は必須) | 
| user | string | "admin" | データベースユーザー | 
| database | string | "postgres" | データベース名 | 
| port | int | 5432 | データベースポート | 
| profile | ?string | null | 認証情報の AWS プロファイル名 | 
| credentialsProvider | ?\\Closure | null | カスタム AWS 認証情報プロバイダー | 
| tokenDurationSecs | int | 900 (15 分) | トークンの有効期間 (秒) | 
| occMaxRetries | ?int | null (無効) | exec() および transaction() のデフォルトの最大 OCC 再試行回数 | 
| ormPrefix | ?string | null | application\_name の先頭に付加される ORM プレフィックス | 
| logger | ?LoggerInterface | null | 再試行の警告と診断のための PSR-3 ロガー | 

## 認証
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-auth"></a>

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

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

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