Aurora DSQL Connector for PHP PDO_PGSQL

The Aurora DSQL Connector for PHP is a PHP connector built on PDO_PGSQL that integrates IAM authentication for connecting PHP applications to Amazon Aurora DSQL clusters.

The connector handles token generation, SSL configuration, and connection management so you can focus on your application logic.

About the connector

The Aurora DSQL Connector for PHP adds an authentication layer on top of PDO_PGSQL that handles IAM token generation, allowing you to connect to Aurora DSQL using your existing PDO workflows. Amazon Aurora DSQL requires IAM authentication with time-limited tokens, and the connector automatically manages token generation for you.

What is Aurora DSQL authentication?

In Aurora DSQL, authentication involves:

The Aurora DSQL Connector for PHP understands these requirements and automatically generates IAM authentication tokens when establishing connections.

Features

Example application

For a complete example, see the example application on GitHub.

Quick start guide

Requirements

Installation

Add the package to your project:

composer require awslabs/aurora-dsql-pdo-pgsql

Usage

Configuration-based connection

<?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();
});

Connection string format

For simple scripts or when you prefer connection string syntax, the connector supports postgres:// and postgresql:// connection strings with Aurora DSQL-specific query parameters:

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

Supported query parameters: region, profile, tokenDurationSecs, ormPrefix.

OCC retry

Aurora DSQL uses optimistic concurrency control (OCC). When two transactions modify the same data, the first to commit wins and the second receives an OCC error.

OCC retry is opt-in. Set occMaxRetries in the config to enable automatic retry with exponential backoff and jitter:

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

Configuration options

The connector also accepts postgres:// and postgresql:// connection strings with query parameters for configuration. Supported query parameters: region, profile, tokenDurationSecs, and ormPrefix.

Authentication

The connector automatically handles Aurora DSQL authentication by generating tokens using AWS credentials. If you don't provide the AWS region, the connector parses it from the hostname.

For more information on authentication in Aurora DSQL, see Authentication and authorization for Aurora DSQL.

Admin vs regular users