aurora-dsql

Amazon Aurora DSQL

概要

Aurora DSQL は、サーバーレスで PostgreSQL 互換の分散 SQL データベースです。このスキルでは、psql スクリプトや PostgreSQL ドライバーによるデータベースへの直接アクセス、スキーマ管理、マイグレーションのサポート、マルチテナントのパターン、クエリプランの説明可能性を提供します。

主な機能：

• 生成された IAM 認証トークンを使った psql による直接クエリ実行（scripts/psql-connect.sh を参照）
• DSQL の制約に準拠したスキーマ管理（トランザクションごとに DDL は 1 つ、インデックスは非同期）
• 安全なデータマイグレーション（カラム単位、制約単位、MySQL→DSQL）
• tenant_id とパラメーター化 SQL によるマルチテナント分離
• 15 分で有効期限が切れる、IAM ベースの認証
• 遅いクエリのクエリプラン診断（EXPLAIN ANALYZE と GUC の実験）

推奨ランタイムは、IAM 認証セッション用の aws dsql generate-db-connect-auth-token と psql の組み合わせです。アプリケーションコードでは、言語固有の DSQL Connectors and SDKs を使用してください。AWS のナレッジを参照する場合（サービスドキュメント、AWS API 呼び出し）は、AWS MCP Server が推奨される MCP 統合です。

---

参照ファイル

詳細なガイダンスが必要な場合は、次のファイルを読み込んでください。

development-guide.md

読み込むタイミング： スキーマの変更またはデータベース操作を実装する前に、必ず読み込んでください
内容： ベストプラクティス、DDL のルール、接続パターン、トランザクションの制限、データ型のシリアライズパターン、アプリケーション層での参照整合性に関する指示、セキュリティのベストプラクティス

クエリ実行：

database-tools.md

読み込むタイミング： DSQL に対するアドホッククエリ実行の詳しい構文や例が必要な場合に読み込んでください。アドホッククエリでは psql（scripts/psql-connect.sh 経由）を優先してください。一時的なスクリプトを作成するのではなく、クエリを直接実行してください。
内容： psql ベースの読み取り専用および書き込みパターン、トランザクションのセマンティクス、入力検証

MCP（AWS のナレッジ／API）：

mcp-setup.md

読み込むタイミング： AWS のナレッジ参照、AWS API へのアクセス、またはアシスタントごとのインストールに AWS MCP Server を設定または推奨する場合に読み込んでください。
内容： psql と AWS MCP Server の使い分け、正式な AWS セットアップドキュメントへのリンク、認証情報に関する注意事項

mcp-tools.md

読み込むタイミング： DSQL サービスの制限を確認するドキュメントを取得する、または AWS API 呼び出しを実行するために、AWS MCP Server のツールを呼び出す場合に読み込んでください。
内容： ツールの一覧 — ナレッジ（aws___search_documentation、aws___read_documentation、aws___recommend、aws___retrieve_skill、aws___list_regions、aws___get_regional_availability）と API（aws___call_aws、aws___run_script、aws___get_tasks、aws___get_presigned_url）。documentation-tools.md へのリンクも含みます。

documentation-tools.md

読み込むタイミング： DSQL サービスの制限を調べる、特定の AWS ドキュメントページを取得する、または AWS MCP Server 経由で開始した長時間実行の AWS API 呼び出しをポーリングする場合に読み込んでください。
内容： AWS ナレッジツールの詳細なパラメーターと呼び出し例

platforms/ — アシスタントごとのインストール方法

読み込むタイミング： 特定のコーディングアシスタント内に AWS MCP Server をインストールする場合に読み込んでください。
内容： アシスタントごとのエントリーポイントの詳細 — claude-code.md、codex.md、gemini.md、kiro.md。

language.md

使用する場面: DSQL 接続コードを書く前に必ずロードしてください。選択したドライバーに対応するリンク先の example_preferred.<ext> をそのまま踏襲してください。記憶を頼りに書いた接続は、正規の IAM トークン更新パターンから乖離してしまいます。正規のエントリーポイントの例（ドライバーの完全なリストとプール/TLS/トークン更新の詳細については language.md をロードしてください）:

• Python: import aurora_dsql_psycopg as dsql → dsql.connect(host, region, user)
• JS (node-postgres): import { AuroraDSQLPool } from "@aws/aurora-dsql-node-postgres-connector" → new AuroraDSQLPool({ host, user })
• JS (postgres.js): import { auroraDSQLPostgres } from "@aws/aurora-dsql-postgresjs-connector" → auroraDSQLPostgres({ host, user })
• Go (pgx): import "github.com/awslabs/aurora-dsql-connectors/go/pgx/dsql"
• Java (JDBC): software.amazon.dsql:aurora-dsql-jdbc-connector:1.4.0 → jdbc:aws-dsql:postgresql://...

内容: 言語ごとの正規の DSQL コネクタパッケージ、ドライバーの選択、フレームワークのパターン、IAM 認証トークンのローテーションと TLS 設定、および Python / JavaScript / TypeScript / Go / Java / Rust の接続コード例。

troubleshooting.md

使用する場面: エラーのデバッグや予期しない動作の際にロードしてください。OCC エラー、接続の失敗、または予期しないクエリ結果については、常に参照することを推奨します（SHOULD）。 内容: よくある落とし穴、エラーメッセージ、解決策

onboarding.md

使用する場面: ユーザーが「DSQL を始めたい」などと明示的にリクエストしたとき 内容: 新規ユーザー向けのインタラクティブなステップバイステップガイド

access-control.md

使用する場面: データベースロールの作成、権限の付与、アプリケーション用のスキーマ設定、または機密データの取り扱いを行うときに必ずロードしてください。アプリケーションには常にスコープ付きロールを使用してください — dsql:DbConnect を持つデータベースロールを作成します。 内容: スコープ付きロールの設定、IAM からデータベースロールへのマッピング、機密データのためのスキーマ分離、ロールの設計パターン

認証と運用:

auth/authentication-guide.md

使用する場面: IAM 認証トークン、シークレット、SSL/TLS、接続プーリング、または監査ログを扱うときに必ずロードしてください。 内容: トークンのライフサイクル、シークレットの保存パターン、SSL/TLS 設定、接続プールのガイダンス、監査ログの統合。

auth/connectivity-tools.md

使用する場面: ドライバー/ORM/アダプターの選定や、一括データロードを計画するときにロードしてください。 内容: 正規の AWS DSQL 接続ツールのページ（ドライバー、ORM、アダプター）および一括ロードのドキュメントページへのポインター。

auth/scaling-guide.md

使用する場面: スケールを考慮した設計を行うときにロードしてください — 接続プーリング、バッチ最適化、ホットキーの回避、識別子の選択。 内容: 水平スケーリング戦略、プールサイズの設定、バッチサイズのガイダンス、IDENTITY/UUID のトレードオフ、シーケンスキャッシュのルール。

実装例:

workflow-patterns.md

使用する場面: 一般的な複数ステップの DSQL ワークフロー（スキーマの探索、CREATE+INDEX、安全なマイグレーション、バッチ挿入、アプリケーション層での FK チェック）の実例を探すときにロードしてください。 内容: psql / ドライバーコードを用いた 5 つの正規パターン。

dsql-examples.md

使用する場面: 具体的な実装例を探すときにロードしてください。 内容: examples/*.md のインデックス（接続、スキーマ、データ操作、マイグレーション、パターン）。

DDL マイグレーション（モジュール式）:

ddl-migrations/overview.md

使用する場面: DROP COLUMN、RENAME COLUMN、ALTER COLUMN TYPE、または DROP CONSTRAINT を実行するときに必ずロードしてください 内容: テーブル再作成パターンの概要、トランザクションのルール、一般的な検証とスワップのパターン

ddl-migrations/column-operations.md

対象： DROP COLUMN、ALTER COLUMN TYPE、SET/DROP NOT NULL、SET/DROP DEFAULT のマイグレーション時に読み込みます
内容： カラムレベルの変更に関する、手順ごとのマイグレーションパターン

ddl-migrations/constraint-operations.md

対象： ADD/DROP CONSTRAINT、主キーの変更、カラムの分割／統合マイグレーション時に読み込みます
内容： 制約および構造の変更に関する、手順ごとのマイグレーションパターン

ddl-migrations/batched-migration.md

対象： 3,000 行を超えるテーブルをマイグレーションする場合に読み込みます
内容： OFFSET ベースおよびカーソルベースのバッチ処理パターン、進捗の追跡、エラー処理

MySQL マイグレーション（モジュール別）：

mysql-migrations/type-mapping.md

対象： MySQL スキーマを DSQL にマイグレーションする際に必ず読み込みます
内容： MySQL のデータ型マッピング、機能の代替手段、DDL オペレーションのマッピング

mysql-migrations/ddl-operations.md

対象： MySQL の DDL オペレーションを DSQL 相当の操作に変換する際に読み込みます
内容： ALTER COLUMN、DROP COLUMN、AUTO_INCREMENT、ENUM、SET、FOREIGN KEY のマイグレーションパターン

mysql-migrations/full-example.md

対象： MySQL のテーブル全体を DSQL にマイグレーションする際に読み込みます
内容： 判断の要約を含む、MySQL の CREATE TABLE をマイグレーションする一連の例

クエリプランの説明可能性（モジュール別）：

対象： ワークフロー 8 のフェーズ 0 で、次の 4 つすべてを必ず読み込みます：query-plan/plan-interpretation.md、query-plan/catalog-queries.md、query-plan/guc-experiments.md、query-plan/report-format.md
内容： DSQL のノードタイプと Node Duration の計算、推定誤差の範囲、pg_class／pg_stats／pg_indexes の SQL と相関述語の検証、GUC 実験の手順と 30 秒のスキッププロトコル、必須レポートの構成と要素のチェックリスト、サポート依頼のテンプレート

---

クエリの実行

psql と新しく生成した IAM 認証トークンを使用して、アドホックな DSQL クエリを実行します。同梱の scripts/psql-connect.sh はトークン生成、TLS 設定、 単一ステートメントのガードをまとめて処理します。手作業で構成した psql の呼び出しよりも、こちらを優先してください。

読み取り専用：

./scripts/psql-connect.sh --cluster <cluster-id> --command "SELECT * FROM entities LIMIT 10"

書き込み／DDL（IAM 管理者認証トークンが必要）：

./scripts/psql-connect.sh --cluster <cluster-id> --admin --command "CREATE INDEX ASYNC ..."

スキーマの確認： 特別な list_tables ヘルパーはありません。information_schema を使用してください。

SELECT table_name FROM information_schema.tables WHERE table_schema = 'public';

詳しい使い方と例については、database-tools.md を参照してください。

AWS MCP サーバー経由の AWS ナレッジ（任意）

AWS MCP サーバーに接続すると、 aws___search_documentation と aws___read_documentation のツールを使って、ユーザーに助言する前に DSQL サービスの 制限を確認できます。以下の数値はデフォルト値であり、変更される可能性があります。ユーザーの判断が正確な制限値に左右される場合は、事前に確認してください。

制限	デフォルト値	確認用クエリ
トランザクションあたりの最大変更行数	3,000	aurora dsql transaction limits
書き込みトランザクションあたりの最大変更データ量	10 MiB	aurora dsql transaction limits
トランザクションの最大継続時間	5 minutes	aurora dsql transaction limits
クラスターあたりの最大接続数	10,000	aurora dsql connection limits
IAM 認証トークンの有効期限	15 minutes	aurora dsql authentication token
接続の最大継続時間	60 minutes	aurora dsql connection limits
テーブルあたりの最大インデックス数	24	aurora dsql index limits
インデックスあたりの最大列数	8	aurora dsql index limits
IDENTITY/SEQUENCE CACHE の値	1 または >= 65536	aurora dsql sequence cache

確認が必要なタイミング： 制限に達すると失敗する可能性のあるバッチサイズ、接続プールの設定、またはスキーマ設計を推奨する前に確認してください。一般的なガイダンスや、正確な数値がユーザーの判断に影響しない場合は、確認する必要はありません。

代替策： AWS MCP サーバーを利用できない場合は、上記のデフォルト値を使用し、制限についてはDSQL のドキュメントで確認するようユーザーに伝えてください。

利用可能な CLI スクリプト

クラスター管理（作成、削除、一覧表示、クラスター情報の取得）と psql 接続には、scripts/ の Bash スクリプトを使用できます。使い方については、references/scripts-guide.md を参照してください。一括データロードについては、Aurora DSQL へのデータのロードを参照してください。

必ず scripts/create-cluster.sh を優先して使用してください。このスクリプトはタグを含めた単一のアトミックな CreateCluster 呼び出しを実行し、AWS DSQL API の形式に沿った解釈可能な出力を返します。

タスク	スクリプト	例
タグ付きクラスターの作成	scripts/create-cluster.sh	./scripts/create-cluster.sh --created-by <model-id> --tags Environment=eval,Project=dsql-skill-eval
クラスターの一覧表示	scripts/list-clusters.sh	./scripts/list-clusters.sh --region us-east-1
クラスターの確認	scripts/cluster-info.sh	./scripts/cluster-info.sh <cluster-id>
psql 経由で接続	scripts/psql-connect.sh	./scripts/psql-connect.sh --cluster <id> --command "SELECT 1"

---

クイックスタート

1. テーブルの一覧表示とスキーマの確認

./scripts/psql-connect.sh --cluster <id> --command "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"
./scripts/psql-connect.sh --cluster <id> --command "SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_schema = 'public' AND table_name = '<table>' ORDER BY ordinal_position"

2. データのクエリ

Use psql-connect.sh (or the language connector in app code) for SELECT queries
Always include tenant_id in WHERE clause for multi-tenant apps
MUST build SQL with safe_query.build() — see references/input-validation.md

3. スキーマの変更を実行

Use ./scripts/psql-connect.sh --admin (or the language connector with the IAM admin auth token) for DDL
Follow one-DDL-per-transaction rule
Always use CREATE INDEX ASYNC in a separate statement
ALTER COLUMN TYPE, DROP COLUMN, DROP CONSTRAINT → Table Recreation Pattern (Workflow 6)

---

よくあるタスク

ワークフロー 0: 依存関係の確認

必要なツールを確認し、不足しているものがあればユーザーに警告します。

制約事項:

• 続行する前に、以下のツールが利用可能であることを検証する必要があります（MUST）: psql（SNI サポートには 14 以上）および aws dsql generate-db-connect-auth-token を備えた AWS CLI v2（DDL/ロール設定には generate-db-connect-admin-auth-token も）
• ユーザーの判断が正確なサービスの制限に依存する場合は、AWS MCP サーバーが利用可能であることも確認することを推奨します（SHOULD）。存在しない場合は、上記の表のデフォルト値を使用し、制限は DSQL のドキュメントに対して検証すべきであることに言及してください
• 不足しているツールについて、明確なメッセージでユーザーに通知する必要があります（MUST）
• ツールが不足していても続行するかどうかをユーザーに尋ねる必要があります（MUST）
• ユーザーがスコープ付きロールを設定している場合は常に、読み取り専用の診断にはスコープ付き（非管理者）の IAM 認証トークンを使用する必要があります（MUST）。IAM 管理者認証トークンは、クラスターのセットアップ、ロールの付与、DDL のために取っておいてください
• クラスターのライフサイクル（作成 / 検査 / 削除）については、ワークフロー 0a を参照してください
• アプリケーションコードを書く前に、ワークフロー 0b に従って言語固有の DSQL コネクタも検証してください

ワークフロー 0a: クラスターのライフサイクル

クラスターの作成と削除には、同梱のスクリプトを使用することを推奨します（SHOULD） — これらはアトミックな aws dsql CLI 呼び出しを発行し、出力を処理します。

タグと削除保護を付けてクラスターを作成する:

./scripts/create-cluster.sh --created-by <model-id> --tags Environment=eval,Project=dsql-skill-eval

クラスターを検査する（ステータス、タグ、エンドポイント、削除保護）:

./scripts/cluster-info.sh <cluster-id>

クラスターを削除する:

./scripts/delete-cluster.sh <cluster-id> [--force]   # --force skips the confirmation prompt in non-TTY

MCP のみの環境（シェルアクセスなし）では、同等の呼び出しは AWS MCP サーバーの aws___call_aws ツールを経由します。このツールは JSON ペイロードを受け取ります — AWS API オペレーションに対応する引数を指定して呼び出してください:

{"service": "dsql", "operation": "CreateCluster",
 "parameters": {"tags": {"created_by": "<model-id>", "Environment": "eval", "Project": "dsql-skill-eval"}, "deletionProtectionEnabled": true}}

{"service": "dsql", "operation": "GetCluster", "parameters": {"identifier": "<cluster-id>"}}

{"service": "dsql", "operation": "DeleteCluster", "parameters": {"identifier": "<cluster-id>"}}

CreateCluster と DeleteCluster は DSQL 側では非同期です — API はクラスターの現在の status（CREATING / DELETING）とともに即座に返ります。.status == "ACTIVE" になるまで（作成）、または呼び出しが 404 を返すまで（削除）、dsql:GetCluster を指定して aws___call_aws を再呼び出しして準備完了をポーリングしてください。aws___get_tasks は MCP 側の長時間実行ツール呼び出しをポーリングするためのものであり、DSQL API 用ではありません。

完全なパラメータの詳細と呼び出しコンテキストについては、AWS CLI aws dsql リファレンス を参照してください。

ワークフロー 0b: 言語コネクタの確認

アプリケーションコードを書く前に、language.md に従って言語固有の DSQL コネクタがインストールされていることを検証する必要があります（MUST）。コネクタは IAM トークン更新の正規の経路です。素のドライバー（pg、psycopg、pgx、tokio-postgres）は最初の 15 分のトークン有効期限までは動作しますが、その後は新しい接続ごとに認証エラーを返すようになります — 素の形式を試した DSQL ユーザーはこれを DSQL のバグとして報告しています。以下をインストールする必要があります（MUST）:

• Python: aurora-dsql-python-connector + 選択したドライバーのホイール
• Node.js: @aws/aurora-dsql-node-postgres-connector または @aws/aurora-dsql-postgresjs-connector
• Go: github.com/awslabs/aurora-dsql-connectors/go/pgx
• Java: software.amazon.dsql:aurora-dsql-jdbc-connector
• Rust: aurora-dsql-sqlx-connector

選択したランタイム用のコネクタが利用できない場合は、手動のトークン更新戦略を文書化し、コードを書く前にユーザーとスケジュールを調整してください。

---

ワークフロー 1: マルチテナントスキーマの作成

ステップバイステップの DDL の順序付け、非同期インデックス作成、スキーマ検証の例については、workflow-patterns.md（パターン 2: インデックス付きテーブルの作成）をロードする必要があります（MUST）。主なルール: すべてのテーブルに tenant_id、CREATE INDEX ASYNC のみ、1 トランザクションにつき 1 つの DDL、配列/JSON は TEXT として保存。

ワークフロー 2：安全なデータ移行

列の追加 → バッチでの値設定 → 検証 → インデックス作成の順序について、workflow-patterns.md（パターン 3：安全なデータ移行）を必ず読み込んでください。3,000 行を超えるテーブルでは、ddl-migrations/batched-migration.md も読み込んでください。主なルール：最初に列を追加し、別の UPDATE で DEFAULT を適用し、1 トランザクションあたり 3,000 行未満でバッチ処理します。

ワークフロー 3：アプリケーション層での参照整合性

親レコードの存在を確認する SELECT → INSERT と、依存レコード数を確認する SELECT → DELETE のパターンについて、workflow-patterns.md（パターン 5：アプリケーション層での外部キー確認）を必ず読み込んでください。すべての SQL は safe_query.build() で構築してください。ワークフロー 4a を参照してください。

ワークフロー 4：テナント分離を伴うクエリ

1. 必ず、テナントに対する呼び出し元の認可を行ってください。形式検証によって認可が成立するわけではありません
2. 必ず、safe_query.build() で SQL を構築してください。値には allow()／regex()（'v' を出力）、テーブル名／列名には ident()（"v" を出力）を使用します。 input-validation.md を参照してください
3. 必ず WHERE 句に tenant_id を含め、アプリケーション層でテナントをまたぐアクセスを拒否してください

ワークフロー 4a：ルーブリック上の重要事項 — ユーザー入力を使った SQL の構築

psql -c "..."（または同等のアドホックなクエリ経路）用の SQL を構築する際、開発者が制御するリテラルではない値（テナント ID、エンティティ ID、ソート列、方向、ステータス列挙値、自由記述、リクエストパラメーターなど、信頼できないソースからの値すべて）を使う場合は、safe_query.build() を必ず使用してください。psql -c フラグは生の SQL 文字列を受け取り、バインドパラメーターには対応していません。アプリケーションコードで Postgres ドライバー（psycopg、pgx など）を使用する場合は、ドライバーのネイティブなパラメーターバインディングを優先してください。生の SQL 文字列を構築しなければならない場合の標準的なフォールバックは safe_query です。safe_query による検証は、生 SQL を使う経路における主要な防御策です。

バリデーター選択表（標準 — input-validation.md と同じ内容です）：

値の種類	バリデーター	出力
既知の集合（テナント ID、ステータス列挙値）	allow(v, SET)	'value'
SQL キーワードとして使う既知の集合（ASC/DESC）	keyword(v, SET)	value（引用符なし）
厳密な形式（UUID、スラッグ、ISO 日付）	regex(v, PATTERN)	'value'
テーブル名または列名	ident(name)	"value"
整数	integer(v)	value
自由記述（説明、コメント、ユーザー名）	literal(v)	$dq_xxx$value$dq_xxx$

safe_query.py の組み込みパターン：TENANT_SLUG（[a-z0-9-]{1,64}）、UUID、INT、ISO_DATE。

DSQL SQL を構築する各ファイルの先頭に必要なインポート：

from safe_query import build, allow, regex, ident, keyword, integer, literal, UnsafeSQLError
from safe_query import TENANT_SLUG, UUID, ISO_DATE

ルーブリック上の重要なシナリオ 1 — 信頼できない入力からの tenant_id。 regex(req.tenant, TENANT_SLUG) または allow(req.tenant, ALLOWED_TENANTS) で検証してください。safe_query.build() で構築してから実行します。読み取り専用モードでも実施してください（多層防御と、モードをまたいだ一貫した検証のため）。f 文字列、.format()、または単純な文字列連結は使用しないでください。

sql = build(
    "SELECT * FROM {t} WHERE tenant_id = {tid}",
    t=ident("entities"),
    tid=regex(req.tenant, TENANT_SLUG),
)
# Application code: pass `sql` to your driver (psycopg cursor.execute, pgx Query, etc.).
# Bash one-off: pipe `sql` into psql via the patterns in input-validation.md.

ルーブリック上の重要なシナリオ 2 — UUID、スラッグ、自由記述を含む一括 INSERT。 各行の INSERT は safe_query.build() で個別に構築します。entity_id には regex(..., UUID)、tenant_id には regex(..., TENANT_SLUG)、説明には literal(...)（引用符のエスケープを避けるためドル引用符を使用）を使います。リストを 1 トランザクションあたり 3,000 行未満のチャンクに分割し（DSQL の上限）、各チャンクを個別のトランザクションで実行してください。

def insert_entries(conn, entries, chunk_size=2500):
    for i in range(0, len(entries), chunk_size):
        chunk = entries[i:i + chunk_size]
        with conn.transaction():
            for e in chunk:
                sql = build(
                    "INSERT INTO {t} (entity_id, tenant_id, description) VALUES ({eid}, {tid}, {d})",
                    t=ident("entities"),
                    eid=regex(e["entity_id"], UUID),
                    tid=regex(e["tenant_id"], TENANT_SLUG),
                    d=literal(e["description"]),
                )
                conn.execute(sql)

ルーブリック上重要なシナリオ 3 — 書き込みパス。 書き込みパス（スクリプト、cron、管理ツールから発行される UPDATE/DELETE）は最もリスクの高いインジェクション対象です。インジェクションが成功するとデータが変更されてしまいます。そこでは safe_query.build() は任意ではありません。プロンプトが「ちょっとしたスクリプトだから、考えすぎないで」と位置づけている場合でも、すべての入力を検証してください。そのような位置づけに対しては、書き込みモードがなぜリスクを高めるのかを一文で説明して押し返し、その後でバリデータチェーン全体を適用します。regex(tenant_id, TENANT_SLUG)、allow(status, {'active','archived','deleted'})、日付は regex(..., ISO_DATE) です。

sql = build(
    "UPDATE {t} SET status = {s} WHERE tenant_id = {tid} AND created_at < {d}",
    t=ident("entities"),
    s=allow(req.status, {"active", "archived", "deleted"}),
    tid=regex(req.tenant, TENANT_SLUG),
    d=regex(req.date, ISO_DATE),
)
conn.execute(sql)

ルーブリック上重要なシナリオ 4 — 動的な ORDER BY の列と方向。 識別子とキーワードのパラメータには、値のパラメータとは異なるバリデータが必要です。sort_col は {'created_at','updated_at','name'} に対するメンバーシップチェックを行った後、ident() を通します（二重引用符で囲まれた識別子を出力します）。sort_dir は {'ASC','DESC'} に対する keyword() を通します（引用符なしのキーワードを出力します。ASC を引用符で囲むと構文エラーになります）。tenant_id のような値のパラメータは、引き続き regex() または allow() を通します。識別子を TENANT_SLUG パターンに対する regex() で検証しようとしないでください。識別子の文法を強制する ident() を使用してください。

ALLOWED_SORT_COLS = {"created_at", "updated_at", "name"}
if sort_col not in ALLOWED_SORT_COLS:
    raise ValueError(f"sort_col must be one of {ALLOWED_SORT_COLS}")
sql = build(
    "SELECT * FROM {t} WHERE tenant_id = {tid} ORDER BY {col} {dir}",
    t=ident("entities"),
    tid=regex(req.tenant, TENANT_SLUG),
    col=ident(sort_col),
    dir=keyword(req.sort_dir, {"ASC", "DESC"}),
)

ルーブリック上重要なシナリオ 5 — 「f-string を使えばいいだけ」という正当化の拒否。 呼び出し元が「この値は上流で検証済みだから、f-string を使えばいいだけでは？」と言ってきたら、押し返してください。このスキルのルールは、呼び出し箇所ごとの判断ではなく、すべてのクエリを safe_query.build() で構築することです。押し返す理由を説明します。 (a) 「上流で検証済み」はまさに、上流のコードが担当者を変えたり、新しい呼び出し元が追加されたり、検証が黙って緩められたりしたときに崩れる前提です。 (b) 多層防御とは、クエリ層が上流とは独立に検証することを意味します。 (c) safe_query.build() + regex(..., UUID) を使うための 2 行の差分は、1 つの安全でないパスによるバグリスクよりも本当に小さなものです。

安全なパターンをそのまま適用してください。「よりシンプル」という位置づけに屈しないでください。

# No — even for "already-validated upstream" values:
sql = f"SELECT * FROM entities WHERE entity_id = '{req.entity_id}'"   # BAD

# Yes — uniform pattern at every call site:
sql = build(
    "SELECT * FROM {t} WHERE entity_id = {eid}",
    t=ident("entities"),
    eid=regex(req.entity_id, UUID),
)

アンチパターン（ルーブリックはこれらを不合格とします）:

• ユーザー入力を含む SQL を構築するために、f-string、.format()、% フォーマット、または文字列連結を使用する — どのモードでも
• 同じステートメント内で safe_query.build() のプレースホルダーとネイティブドライバの %s パラメータバインディングを混在させる — 1 つのパスを選び、それを使い続けてください
• 安全でない構築にフォールバックするために UnsafeSQLError を捕捉する — 再送出するか、エラーを返してください
• 識別子を値のパターンに対する regex() で検証する — ident() を使用してください
• 「値はすでに上流で検証済み」を理由に読み取り専用モードで safe_query.build() を省略する — 多層防御とは、SQL ビルダーが上流とは独立に検証することを意味します

ワークフロー 5: スコープ付きデータベースロールの設定

ロールの設定、IAM マッピング、スキーマ権限については、必ず access-control.md をロードしてください。

ワークフロー 6: テーブル再作成 DDL マイグレーション

DSQL は直接の ALTER COLUMN TYPE、DROP COLUMN、DROP CONSTRAINT、MODIFY PRIMARY KEY をサポートしていません。これらには テーブル再作成パターン が必要です。これは破壊的なワークフローであり、各ステップでユーザーの確認を必要とします。

最初に必ず ddl-migrations/overview.md をロードし、その後で該当するサブファイルをロードしてください。

• 列の変更（型、NULL 許容性、デフォルト）: ddl-migrations/column-operations.md
• 制約/PK の変更、列の分割/マージ: ddl-migrations/constraint-operations.md
• 3,000 行を超えるテーブル: さらに ddl-migrations/batched-migration.md もロードしてください

ワークフロー 7：MySQL から DSQL へのスキーマ移行

型マッピングと機能の代替案については、必ず mysql-migrations/type-mapping.md を読み込んでください。DDL の変換に関する詳細については、mysql-migrations/ddl-operations.md を読み込んでください。エンドツーエンドの例については、mysql-migrations/full-example.md を読み込んでください。

ワークフロー 8：クエリプランの説明可能性

遅いクエリ、DPU の高さ、予期しない全件スキャン、またはユーザーが理解できないプランが発生した場合に実行します。必須の成果物は構造化された Markdown 診断レポートです。回答する前に、ワークフローをエンドツーエンドで実行してください。

開始前に、必ず次の 4 つの参照ファイルをすべて読み込んでください。

1. query-plan/plan-interpretation.md — ノードの種類、実行時間の計算、異常値
2. query-plan/catalog-queries.md — pg_class / pg_stats / pg_indexes の SQL
3. query-plan/guc-experiments.md — GUC の手順と >30s のスキップ手順
4. query-plan/report-format.md — 必須のレポート構成と要素のチェックリスト

フェーズ 1 — プランの取得。 ユーザーがプランを説明または貼り付けている場合でも、ユーザーのクエリをそのまま使用して、必ず psql 経由で EXPLAIN ANALYZE VERBOSE を実行してください。SELECT はそのまま実行します。UPDATE/DELETE は、同等の SELECT に書き換えてから実行します。INSERT、pl/pgsql、DO ブロック、関数は必ず拒否してください。プランの取得中に、データを変更する DML を実行してはいけません。EXPLAIN でエラーが発生した場合は、その内容をそのまま報告し、DSQL 固有のセマンティクスを作り上げないでください。Query ID、Planning Time、Execution Time、DPU Estimate を抽出してください。

フェーズ 2 — 根拠の収集。 catalog-queries.md に従って、pg_class、pg_stats、pg_indexes、COUNT(*)、COUNT(DISTINCT) をクエリしてください。plan-interpretation.md に従って、推定誤差を分類してください。

フェーズ 3 — 実験（条件付き）。 ≤30s の場合は、冗長な述語のテストとあわせて、guc-experiments.md に従って GUC 実験を実行してください。>30s の場合はスキップし、手動で実行する GUC の SQL をレポートにそのまま記載してください。行数に異常がある場合は、結果が正しいことを確認し、DSQL の潜在的なバグとして指摘したうえで、Support Request Template を作成してください。

フェーズ 4 — レポートの作成と再評価の案内。 report-format.md の Required Elements Checklist に従って、診断レポートを完全な形で作成してください。「Next Steps」ブロックで締めくくってください。ユーザーが「reassess」と言った場合は、フェーズ 1〜2 を再実行し、元のレポートに「Addendum: After-Change Performance」を追記してください。

psql の呼び出し方法：

./scripts/psql-connect.sh --cluster <id> --command "EXPLAIN ANALYZE VERBOSE <sql>"
./scripts/psql-connect.sh --cluster <id> --script ./experiment-2.sql   # GUC multi-statement

---

セキュリティに関する考慮事項

このセクションでは、主要なセキュリティ制御をまとめています。詳しいガイダンスについては、リンク先のリファレンスファイルを参照してください。

1. IAM 認証トークンの有効期限： IAM 認証トークンの有効期限は 15 分です。接続ごとに必ず新しいトークンを生成するか、定期的に更新する仕組みを実装してください。トークンをディスクに保存してはなりません — メモリ内だけで保持し、使用後は破棄してください。authentication-guide.mdを参照してください。

2. 管理者よりもスコープ付きロールを優先： すべてのアプリケーション接続には、dsql:DbConnect を持つスコープ付きデータベースロールを使用してください。admin ロールは、初期クラスター設定（ロールの作成、権限の付与）に限って使用してください。スコープ付きロールを確立したら、セットアップ用の IAM ロールから dsql:DbConnectAdmin を取り消してください。access-control.mdを参照してください。

3. 転送中の暗号化： SSL/TLS はサーバー側で強制されます。sslmode=verify-full（DSQL コネクターおよび psql-connect.sh のデフォルト）を使用して、サーバー証明書を DSQL の CA に照らして検証し、MITM 攻撃を防いでください。信頼できる CA バンドルにクライアントがアクセスできない場合に限り、require にダウングレードしてください。

4. 保管時の暗号化： Aurora DSQL は、デフォルトで AWS 管理キーを使用して、保管時のすべてのデータを暗号化します。追加の設定は不要です。コンプライアンスフレームワークで証明が必要な場合は、クラスターのプロパティで暗号化の状態を確認してください。

5. CloudTrail による監査ログ： DSQL API 呼び出しの CloudTrail ログを有効にし、トークン生成パターン、クラスター設定の変更、認証失敗を監視してください。不審なアクティビティに対する CloudWatch アラームを設定してください。DSQL の監視に使用する CloudWatch Log Groups の暗号化を有効にし、KMS キーを使用して、機密情報を含む可能性があるクエリのメタデータを保護してください。authentication-guide.mdを参照してください。

6. 書き込み処理には厳格な検証が必要： スクリプト、cron ジョブ、管理ツールから実行する変更を伴う SQL（UPDATE、DELETE、DDL）は、インジェクションの影響が最も重大な箇所です。すべての書き込み処理は、safe_query.build()（または、アプリケーションコードで Postgres ドライバーを使用する場合は、ドライバー標準のパラメーターバインド）を必ず経由させてください。

7. 入力検証が主要な防御策： safe_query.build() は、未加工の SQL を使う処理における SQL インジェクションに対する主要な防御策です。信頼できない入力から取得したすべての値 — テナント ID、エンティティ ID、並べ替え列、自由記述テキスト — は、バリデーター（allow、regex、ident、keyword、integer、literal）を必ず通してください。f 文字列、.format()、文字列の連結は使用しないでください。input-validation.mdを参照してください。

8. マルチテナントの分離を厳格な契約として扱う： ワークロードでテナントスコープを使用する場合（ワークフロー 4）、テナント所有のテーブルに対するすべての読み取りと書き込みの WHERE 句に tenant_id を必ず含め、クエリを発行する前に、アプリケーションで呼び出し元がその tenant_id にアクセスする権限を持つことを認可しなければなりません — 書式の検証だけでは認可を確立できません。WHERE 句から tenant_id を省略すること、または呼び出し元が認可されていないテナント値をスコープとして指定することは、テナント間のデータ漏えいにつながります。この境界は DSQL ではなくスキルによって適用されます — デプロイ前に、すべてのデータアクセス経路で認証済みテナントにスコープが設定されていることを確認してください。access-control.mdおよびワークフロー 4 を参照してください。

---

トラブルシューティング

• AWS MCP Server が結果を返さない場合： 上の表にあるデフォルトの制限を使用し、制限が DSQL documentation に照らして確認されていることに注意してください。
• OCC のシリアライズエラー： トランザクションを再試行してください。解消しない場合は、ホットキーの競合を確認してください。troubleshooting.md を参照してください。
• トランザクションが制限を超える場合： 3,000 行未満のバッチに分割してください。batched-migration.md を参照してください。
• 操作中に IAM 認証トークンが期限切れになる場合： 新しい IAM 認証トークンを生成してください。authentication-guide.md を参照してください。その他の問題については、troubleshooting.md を参照してください。

---

追加リソース

• Aurora DSQL ドキュメント
• DSQL コネクター、ドライバー、ORM サンプル（公式）
• PostgreSQL 互換性
• CloudFormation リソース

aws-database-selection からの引き継ぎ

このスキルは直接呼び出すことも、親スキルである aws-database-selection が要件のヒアリングを実施し、requirements.json アーティファクトを作成した後に、そのスキルから引き継いで実行することもできます。最近の会話に aws_dbs_requirements/*/requirements.json に一致するバッククォートで囲まれたパスがある場合は、aws-database-selection/references/handoff-contract.md のエントリープロトコルに従ってください。

1. file_read を使用してアーティファクトを読み取ります。
2. aws-database-selection/references/workload-primary-artifact.schema.json に照らして検証します。形式が不正、または読み取れない場合は、その旨をユーザーに伝え、アーティファクトなしで進めてください。
3. アーティファクトにある概要レベルの情報（主要な形状、厳しい制約、移行の状況）を挙げ、関連する内容を太字の文を1つか2つで伝えます。アーティファクト全体をそのまま繰り返さないでください。
4. スコープを確認します。このスキルの対象は Aurora DSQL のスキーマ、クエリプラン、IAM 認証、マルチテナントパターン、MySQL から DSQL への移行です。アーティファクトの workload_primaries.dominant_shapes または migration_context がこのスコープに合わない場合は、引き継ぎ契約に従って控えめに差し戻してください。Aurora PostgreSQL または MySQL には amazon-aurora、RDS エンジンには rds-oss を提案してください。あるいは、マルチリージョンで強い SQL 整合性が必要でない場合は aws-database-selection に戻ることを提案し、戻るかこのまま進めるかユーザーに尋ねてください。アーティファクトを黙って不適切に使用しないでください。
5. このスキル固有のワークフローに進み、推奨事項の根拠が要件にある場合は、証拠としてアーティファクトのパスを引用してください。

このスキルからユーザーに提示する出力はすべて、引き継ぎ契約に定められた Markdown プリミティブのみの書式規約に従います。太字のラベル、パスと列挙値を囲むバッククォート、選択肢の箇条書きを使用し、ASCII アートや罫線文字は使用しないでください。