# 适用于 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)是一款基于 [https://www.php.net/manual/en/ref.pdo-pgsql.php](https://www.php.net/manual/en/ref.pdo-pgsql.php) 构建的 PHP 连接器，它集成了 IAM 身份验证功能，用于将 PHP 应用程序连接到 Amazon Aurora DSQL 集群。

此连接器处理令牌生成、SSL 配置和连接管理，因此您可以专注于应用程序逻辑。

## 关于连接器
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-about"></a>

适用于 PHP 的 Aurora DSQL 连接器在 `PDO_PGSQL` 之上添加一个身份验证层来处理 IAM 令牌生成，使您无需更改现有 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`extension
+ [有权访问 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
```

## 用法
<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）。当两个事务修改相同的数据时，提交的第一个事务获胜，第二个事务收到 OCC 错误。

OCC 重试为选择加入的。在配置中设置 `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”的用户会自动使用管理员身份验证令牌
+ 所有其他用户都使用普通身份验证令牌
+ 该连接器为每个连接动态生成令牌