# Conector do Aurora DSQL para PHP `PDO_PGSQL`
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql"></a>

O [Conector do Aurora DSQL para PHP](https://github.com/awslabs/aurora-dsql-connectors/tree/main/php/pdo_pgsql) é um conector PHP baseado em [https://www.php.net/manual/en/ref.pdo-pgsql.php](https://www.php.net/manual/en/ref.pdo-pgsql.php) que integra a autenticação do IAM para conectar aplicações PHP a clusters do Amazon Aurora DSQL.

O conector gerencia a geração de tokens, a configuração SSL e o gerenciamento de conexões para que você se concentre na lógica da aplicação.

## Sobre o conector
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-about"></a>

O Conector do Aurora DSQL para PHP adiciona uma camada de autenticação sobre `PDO_PGSQL` que gerencia a geração de tokens do IAM, permitindo conectar ao Aurora DSQL usando fluxos de trabalho existentes do PDO. O Amazon Aurora DSQL exige a autenticação do IAM com tokens de duração limitada, e o conector gerencia automaticamente a geração desses tokens.

### O que é a autenticação do Aurora DSQL?
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-authentication"></a>

Na autenticação do Aurora DSQL, a **autenticação** envolve:
+ **Autenticação do IAM**: todas as conexões usam autenticação baseada no IAM com tokens de tempo limitado.
+ **Geração de token**: o conector gera tokens de autenticação usando credenciais da AWS, e esses tokens têm vida útil configurável

O conector do Aurora DSQL para PHP entende esses requisitos e gera tokens de autenticação do IAM automaticamente ao estabelecer conexões.

### Recursos
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-features"></a>
+ **Autenticação automática do IAM:** lida com a geração e atualização de tokens do Aurora DSQL
+ **Baseado em `PDO_PGSQL`:** encapsula a extensão padrão do PostgreSQL para PHP
+ **Integração perfeita:** funciona com fluxos de trabalho existentes do PDO
+ **Aplicação de SSL:** sempre usa SSL com o modo `verify-full` e negociação direta de TLS
+ **Detecção automática de região:** extrai a região da AWS do nome de host do cluster do Aurora DSQL
+ **Suporte a credenciais da AWS:** aceita perfis e provedores de credenciais personalizados da AWS
+ **Nova tentativa de OCC:** permite optar por uma nova tentativa de controle de simultaneidade otimista com recuo exponencial e variação aleatória
+ **Log PSR-3:** log compatível para diagnósticos de nova tentativa

## Aplicativo de exemplo
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-example-application"></a>

Para ver um exemplo completo, consulte a [aplicação de exemplo](https://github.com/awslabs/aurora-dsql-connectors/tree/main/php/pdo_pgsql/example) no GitHub.

## Guia de início rápido
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-quick-start"></a>

### Requisitos
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-requirements"></a>
+ PHP 8.2 ou posterior
+ `ext-pdo_pgsql`Extensão para 
+ [Acesso a um cluster do Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Credenciais da AWS configuradas (por meio da CLI da AWS, de variáveis de ambiente ou perfis do IAM)

## Instalação
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-installation"></a>

Adicione o pacote ao seu projeto:

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

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

### Conexão baseada em configuração
<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();
});
```

### Formato de string da conexão
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-connection-string"></a>

Para scripts simples ou quando houver preferência por sintaxe de string de conexão, o conector é compatível com strings de conexão `postgres://` e `postgresql://` com parâmetros de consulta específicos do Aurora DSQL:

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

Parâmetros de consulta compatíveis: `region`, `profile`, `tokenDurationSecs`, `ormPrefix`.

### Nova tentativa de OCC
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-occ-retry"></a>

O Aurora DSQL usa o controle de simultaneidade otimista (OCC). Quando duas transações modificam os mesmos dados, a primeira a confirmar vence e a segunda recebe um erro de OCC.

A nova tentativa do OCC é opcional. Defina `occMaxRetries` na configuração para ativar a nova tentativa automática com recuo exponencial e variação aleatória:

```
$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");
});
```

**Importante**  
`transaction()` gerencia `beginTransaction()`/`commit()`/`rollBack()` internamente. Seu retorno de chamada deve conter somente operações de banco de dados e ser seguro tentar novamente.

## Opções de configuração
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-configuration"></a>

O conector também aceita strings de conexão `postgres://` e `postgresql://` com parâmetros de consulta para configuração. Parâmetros de consulta compatíveis: `region`, `profile`, `tokenDurationSecs` e `ormPrefix`.


| Campo | Tipo | Padrão | Descrição | 
| --- | --- | --- | --- | 
| host | string | (obrigatório) | Endpoint do cluster ou ID do cluster de 26 caracteres | 
| region | ?string | null (detectado automaticamente) | Região da AWS; obrigatória se o host for um ID de cluster | 
| user | string | "admin" | Usuário do banco de dados | 
| database | string | "postgres" | Nome do banco de dados | 
| port | int | 5432 | Porta do banco de dados | 
| profile | ?string | null | Nome do perfil da AWS para credenciais | 
| credentialsProvider | ?\\Closure | null | Provedor de credenciais da AWS personalizadas | 
| tokenDurationSecs | int | 900 (15 min) | Duração da validade do token em segundos | 
| occMaxRetries | ?int | null (desabilitado) | Número máximo padrão de novas tentativas de OCC para exec() e transaction() | 
| ormPrefix | ?string | null | Prefixo ORM prefixado a application\_name | 
| logger | ?LoggerInterface | null | Logger PSR-3 para diagnósticos e avisos de nova tentativa | 

## Autenticação
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-auth"></a>

O conector gerencia automaticamente a autenticação do Aurora DSQL gerando tokens com o uso de credenciais da AWS. Se você não fornecer a região da AWS, o conector a analisará a partir do nome do host.

Para obter mais informações sobre autenticação no Aurora DSQL, consulte [Autenticação e autorização para o Aurora DSQL](authentication-authorization.md).

### Admin versus usuários regulares
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-admin-vs-regular"></a>
+ Usuários chamados “admin” utilizam automaticamente tokens de autenticação de admin.
+ Todos os outros usuários utilizam tokens de autenticação regulares.
+ O conector gera tokens dinamicamente para cada conexão