Conector do Aurora DSQL para PHP PDO_PGSQL

O Conector do Aurora DSQL para PHP é um conector PHP baseado em PDO_PGSQL 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

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?

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

• 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

Para ver um exemplo completo, consulte a aplicação de exemplo no GitHub.

Guia de início rápido

Requisitos

• PHP 8.2 ou posterior

• ext-pdo_pgsqlExtensão para

• Acesso a um cluster do Aurora DSQL

• Credenciais da AWS configuradas (por meio da CLI da AWS, de variáveis de ambiente ou perfis do IAM)

Instalação

Adicione o pacote ao seu projeto:

composer require awslabs/aurora-dsql-pdo-pgsql

Usage

Conexão baseada em configuração

<?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

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://[e-mail]/postgres?region=us-east-1'
);

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

Nova tentativa de OCC

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

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

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.

Admin versus usuários regulares

• 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