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

El [conector de Aurora DSQL para PHP](https://github.com/awslabs/aurora-dsql-connectors/tree/main/php/pdo_pgsql) es un conector de PHP basado en [https://www.php.net/manual/en/ref.pdo-pgsql.php](https://www.php.net/manual/en/ref.pdo-pgsql.php) que integra la autenticación de IAM para conectar aplicaciones PHP a clústeres de Amazon Aurora DSQL.

El conector se encarga de la generación de tokens, la configuración SSL y la gestión de conexiones para que usted pueda centrarse en la lógica de su aplicación.

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

El conector de Aurora DSQL para PHP agrega una capa de autenticación sobre `PDO_PGSQL` que gestiona la generación de tókenes de IAM, lo que permite conectarse a Aurora DSQL con los flujos de trabajo de PDO existentes. Amazon Aurora DSQL requiere una autenticación de IAM con tókenes de duración limitada y el conector administra automáticamente la generación de tókenes.

### ¿Qué es la autenticación de Aurora DSQL?
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-authentication"></a>

En Aurora DSQL, la **autenticación** implica:
+ **Autenticación de IAM**: todas las conexiones utilizan la autenticación basada en IAM con tokens de tiempo limitado
+ **Generación de tokens**: el conector genera tokens de autenticación utilizando credenciales de AWS, y estos tokens tienen una duración configurable.

El conector de Aurora DSQL para PHP comprende estos requisitos y genera automáticamente los tókenes de autenticación de IAM al establecer las conexiones.

### Características
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-features"></a>
+ **Autenticación automática de IAM**: gestiona la generación y la actualización de token de Aurora DSQL.
+ **Basado en `PDO_PGSQL`**: incluye la extensión estándar de PostgreSQL para PHP.
+ **Integración perfecta**: funciona con los flujos de trabajo de PDO existentes.
+ **Aplicación de SSL**: siempre utiliza SSL con el modo `verify-full` y negociación de TLS directa.
+ **Detección automática de regiones**: extrae la región de AWS del nombre de host del clúster de DSQL.
+ **Compatibilidad con credenciales de AWS**: admite perfiles de AWS y proveedores de credenciales personalizadas.
+ **Reintento de OCC**: reintento opcional del control de simultaneidad optimista con retroceso exponencial y fluctuación.
+ **Registro PSR-3**: registro compatible para reintentar el diagnóstico

## Aplicación de ejemplo
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-example-application"></a>

Para ver un ejemplo completo, consulte la [aplicación de ejemplo](https://github.com/awslabs/aurora-dsql-connectors/tree/main/php/pdo_pgsql/example) en GitHub.

## Guía de inicio 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 o posterior
+ `ext-pdo_pgsql`Extensión 
+ [Acceso a un clúster de Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)
+ Credenciales de AWS configuradas (mediante AWS CLI, variables de entorno o roles de IAM).

## Instalación
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-installation"></a>

Añada el paquete a su proyecto:

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

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

### Conexión basada en la configuración
<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 la cadena de conexión
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-connection-string"></a>

Para scripts simples o cuando prefiera la sintaxis de cadenas de conexión, el conector admite cadenas de conexión `postgres://` y `postgresql://` con parámetros de consulta específicos de Aurora DSQL:

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

Parámetros de consulta compatibles: `region`, `profile`, `tokenDurationSecs`, `ormPrefix`.

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

Aurora DSQL utiliza control de simultaneidad optimista (OCC). Cuando dos transacciones modifican los mismos datos, la primera en confirmarse tiene prioridad y la segunda recibe un error de OCC.

El reintento de OCC es opcional. Establezca `occMaxRetries` en la configuración para habilitar el reintento automático con retroceso exponencial y fluctuación:

```
$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()` administra `beginTransaction()`/`commit()`/`rollBack()` internamente. Su devolución de llamada debe contener solo operaciones de base de datos, además de ser segura para reintentarlo.

## Opciones de configuración
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-configuration"></a>

El conector también admite las cadenas de conexión `postgres://` y `postgresql://` con los parámetros de consulta para configuración. Parámetros de consulta compatibles: `region`, `profile`, `tokenDurationSecs` y `ormPrefix`.


| Campo | Tipo | Predeterminado | Descripción | 
| --- | --- | --- | --- | 
| host | string | (obligatorio) | Punto de conexión de clúster o ID de clúster de 26 caracteres | 
| region | ?string | null (detectado automáticamente) | Región de AWS; obligatorio si el host es un ID de clúster | 
| user | string | "admin" | Usuario de base de datos | 
| database | string | "postgres" | Nombre de base de datos | 
| port | int | 5432 | Database port (Puerto de base de datos) | 
| profile | ?string | null | Nombre de perfil de AWS para las credenciales | 
| credentialsProvider | ?\\Closure | null | Proveedor de credenciales de AWS personalizadas | 
| tokenDurationSecs | int | 900 (15 min) | Duración de la validez del token en segundos | 
| occMaxRetries | ?int | null (deshabilitado) | El número máximo predeterminado de reintentos de OCC exec() y transaction() | 
| ormPrefix | ?string | null | Prefijo ORM precedido de application\_name | 
| logger | ?LoggerInterface | null | Registradores PSR-3 para advertencias y diagnósticos de reintentos | 

## Autenticación
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-auth"></a>

El conector gestiona automáticamente la autenticación de Aurora DSQL generando tokens usando las credenciales de AWS. Si no proporciona la región de AWS, el conector la analiza a partir del nombre de host.

Para obtener más información sobre la autenticación en Aurora DSQL, consulte [Autenticación y autorización para Aurora DSQL](authentication-authorization.md).

### Administrador frente a usuarios habituales
<a name="SECTION_program-with-dsql-connector-for-php-pdo-pgsql-admin-vs-regular"></a>
+ Los usuarios denominados “admin” utilizan automáticamente los tókenes de autenticación de administrador
+ Todos los demás usuarios utilizan tókenes de autenticación habituales
+ El conector genera tokens de forma dinámica para cada conexión