# 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 사용
+ **리전 자동 감지** - 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 CLI, 환경 변수 또는 IAM 역할을 통해 AWS 자격 증명 구성

## 설치
<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`입니다.


| Field | Type | 기본값 | 설명 | 
| --- | --- | --- | --- | 
| 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 로거 | 

## Authentication
<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"이라는 사용자는 관리자 인증 토큰을 자동으로 사용
+ 다른 모든 사용자는 일반 인증 토큰을 사용합니다.
+ 커넥터는 각 연결에 대해 동적으로 토큰을 생성합니다.