View a markdown version of this page

PHP PDO_PGSQL 用 Aurora DSQL コネクタ - Amazon Aurora DSQL
コネクタについてサンプルアプリケーションクイックスタートガイドインストールUsage設定オプション認証

PHP PDO_PGSQL 用 Aurora DSQL コネクタ

PHP 用 Aurora DSQL コネクタは、PHP アプリケーションを Amazon Aurora DSQL クラスターに接続するための IAM 認証を統合した PDO_PGSQL 上に構築された PHP コネクタです。

コネクタはトークン生成、SSL 設定、および接続管理を処理するため、ユーザーはアプリケーションロジックに集中できます。

コネクタについて

PHP 用 Aurora DSQL コネクタは、IAM トークン生成を処理する PDO_PGSQL 上に認証レイヤーを追加し、既存の PDO ワークフローを使用して Aurora DSQL に接続できるようにします。Amazon Aurora DSQL には、時間制限付きトークンによる IAM 認証が必要であり、コネクタは自動的にトークン生成を管理します。

Aurora DSQL 認証とは

Aurora DSQL では、認証に以下が含まれます。

  • IAM 認証: すべての接続で、時間制限付きトークンによる IAM ベースの認証が使用されます

  • トークン生成: コネクタは AWS 認証情報を使用して認証トークンを生成します。これらのトークンの有効期間は設定可能です。

PHP 用 Aurora DSQL コネクタは、これらの要件を理解し、接続の確立時に IAM 認証トークンを自動的に生成します。

機能

  • 自動 IAM 認証 - Aurora DSQL トークンの生成と更新を処理

  • PDO_PGSQL 上に構築 - PHP 用の標準の PostgreSQL 拡張機能をラップ

  • シームレスな統合 - 既存の PDO ワークフローと連携

  • SSL 適用 - 常に verify-full モードと直接 TLS ネゴシエーションで SSL を使用

  • リージョンの自動検出 - Aurora DSQL クラスターホスト名から AWS リージョンを抽出

  • AWS 認証情報のサポート: AWS プロファイルとカスタム認証情報プロバイダーをサポート

  • OCC 再試行 - エクスポネンシャルバックオフとジッターを使用したオプトインのオプティミスティック同時実行制御の再試行

  • PSR-3 ログ記録 - 再試行診断用の互換性のあるログ記録

サンプルアプリケーション

詳細な例については、GitHub のサンプルアプリケーションを参照してください。

クイックスタートガイド

要件

インストール

パッケージをプロジェクトに追加します。

composer require awslabs/aurora-dsql-pdo-pgsql

Usage

設定ベースの接続

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

接続文字列形式

シンプルなスクリプトの場合、または接続文字列構文を使用する場合、コネクタは 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 再試行

Aurora DSQL は、オプティミスティック同時実行制御 (OCC) を使用します。2 つのトランザクションが同じデータを変更する場合、最初のトランザクションはコミットに成功し、2 番目のトランザクションは OCC エラーを受け取ります。

OCC 再試行はオプトインです。エクスポネンシャルバックオフとジッターによる自動再試行を有効にするには、config で 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() を内部的に管理します。コールバックは、データベースオペレーションのみを含むものとし、再試行しても安全であることが必要です。

設定オプション

コネクタは、設定用のクエリパラメータを持つ postgres:// および postgresql:// 接続文字列も受け入れます。サポートされているクエリパラメータ: region、profile、tokenDurationSecs、ormPrefix。

フィールド タイプ デフォルト 説明
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 ロガー

認証

コネクタは、AWS 認証情報を使用してトークンを生成することで、Aurora DSQL 認証を自動的に処理します。AWS リージョンを指定しない場合、コネクタはホスト名からリージョンを解析します。

Aurora DSQL の認証の詳細については、「Aurora DSQL の認証および認可」を参照してください。

管理者ユーザーと通常のユーザー

  • 「admin」という名前のユーザーは、管理者認証トークンを自動的に使用します。

  • 他のすべてのユーザーは通常の認証トークンを使用します。

  • コネクタは、接続ごとにトークンを動的に生成します。