Amazon Aurora DSQL スキル

Aurora DSQL はサーバーレス、PostgreSQL互換の分散SQLデータベースです。このスキルは MCP ツールを介した直接的なデータベース操作、スキーマ管理、マイグレーションサポート、マルチテナントパターンを提供します。

主な機能:

• MCP ツールを介した直接的なクエリ実行
• DSQL 制約を伴うスキーマ管理
• マイグレーションサポートと安全なスキーマ進化
• マルチテナント分離パターン
• IAMベースの認証

---

参考ファイル

必要に応じてこれらのファイルを読み込んで詳細なガイダンスを取得します:

development-guide.md

タイミング: スキーマ変更またはデータベース操作を実装する前に常に読み込む 含まれる内容: ベストプラクティス、DDL ルール、接続パターン、トランザクション制限、データ型シリアライゼーションパターン、アプリケーション層参照整合性の指示、セキュリティベストプラクティス

MCP:

mcp-setup.md

タイミング: DSQL MCP サーバーの使用または更新のためのガイダンスについて常に読み込む 含まれる内容: DSQL MCP サーバーのセットアップ手順（2つの設定オプション付き、mcp/.mcp.json でサンプル表示）

1. Documentation-Tools のみ
2. Database Operations（クラスタエンドポイント必須）

mcp-tools.md

タイミング: MCP ツールの詳細構文と例が必要な場合に読み込む。アドホッククエリについては MCP ツールを優先 — スクリプトを記述するのではなく直接実行する 含まれる内容: ツールパラメータ、詳細な例、使用パターン、入力検証

language.md

タイミング: 言語固有の実装の選択を行うときは必ず読み込む。常に利用可能な場合は DSQL Connector を優先する 含まれる内容: ドライバ選択、フレームワークパターン、Python/JS/Go/Java/Rust の接続コード

dsql-examples.md

タイミング: 特定の実装例を探しているときに読み込む 含まれる内容: コード例、リポジトリパターン、マルチテナント実装

troubleshooting.md

タイミング: エラーのデバッグや予期しない動作時に読み込む。OCC エラー、接続障害、または予期しないクエリ結果については常に参照すること 含まれる内容: 一般的な落とし穴、エラーメッセージ、ソリューション

onboarding.md

タイミング: ユーザーが明示的に「DSQL を始める」のような言葉をリクエストした場合 含まれる内容: 新規ユーザーの対話的なステップバイステップガイド

access-control.md

タイミング: データベースロールを作成、権限を付与、アプリケーション用スキーマをセットアップ、または機密データを処理するときは必ず読み込む。常に dsql:DbConnect を持つスコープ付きロールをアプリケーション用に使用 — データベースロールを作成する 含まれる内容: スコープ付きロールのセットアップ、IAM からデータベースロールへのマッピング、機密データのスキーマ分離、ロール設計パターン

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、MODIFY PRIMARY KEY、カラム分割/マージマイグレーションのときに読み込む 含まれる内容: 制約および構造変更のステップバイステップマイグレーションパターン

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 マイグレーション例と決定サマリー

クエリプランの解釈可能性（モジュール式）:

タイミング: Workflow 8 Phase 0 で全4つを読み込む — query-plan/plan-interpretation.md、query-plan/catalog-queries.md、query-plan/guc-experiments.md、query-plan/report-format.md 含まれる内容: DSQL ノードタイプ + ノード期間計算 + 推定誤差帯、pg_class/pg_stats/pg_indexes SQL + 相関述語検証、GUC 実験手順 + 30秒スキッププロトコル、必須レポート構造 + 要素チェックリスト + サポートリクエストテンプレート

SQL 互換性検証:

dsql-lint.md

タイミング: dsql_lint を実行する前、外部ソース SQL（pg_dump、ORM マイグレーション、ユーザー貼り付け DDL）を処理する前、または fixed_with_warning / 修正不可の診断を解決するときは必ず読み込む 含まれる内容: dsql_lint MCP ツールリファレンス、修正ステータス、ORM 統合、修正不可エラーの解決

---

利用可能な MCP ツール

aurora-dsql MCP サーバーは以下のツールを提供します:

データベース操作:

1. readonly_query - SELECT クエリを実行（辞書のリストを返す）
2. transact - トランザクション内で DDL/DML ステートメントを実行（SQL ステートメントのリストを取得）
3. get_schema - 特定のテーブルのテーブル構造を取得

SQL 検証:

1. dsql_lint - SQL の DSQL 互換性を検証し、オプションで問題を自動修正。外部ソース SQL 実行前に使用。

ドキュメント＆ナレッジ:

1. dsql_search_documentation - Aurora DSQL ドキュメントを検索
2. dsql_read_documentation - 特定のドキュメントページを読む
3. dsql_recommend - DSQL ベストプラクティスの推奨を取得

注: list_tables ツールはありません。information_schema で readonly_query を使用してください。

詳細なセットアップ手順については mcp-setup.md を参照してください。 詳細な使用方法と例については mcp-tools.md を参照してください。

AWS Knowledge MCP (awsknowledge)

DSQL サービス制限を検証してユーザーにアドバイスする前に参照してください。以下の数値制限はデフォルト値であり変更される可能性があります — ユーザーの決定が正確な制限に依存する場合は、最初に検証してください:

制限	デフォルト	検証クエリ
トランザクションあたりの最大行数	3,000	aurora dsql transaction limits
トランザクションあたりの最大データサイズ	10 MiB	aurora dsql transaction limits
最大トランザクション期間	5 分	aurora dsql transaction limits
クラスターあたりの最大接続数	10,000	aurora dsql connection limits
認証トークン有効期限	15 分	aurora dsql authentication token
最大接続期間	60 分	aurora dsql connection limits
テーブルあたりの最大インデックス数	24	aurora dsql index limits
インデックスあたりの最大カラム数	8	aurora dsql index limits
IDENTITY/SEQUENCE CACHE 値	1 または >= 65536	aurora dsql sequence cache
サポート対象カラムデータ型	ドキュメント参照	aurora dsql supported data types

検証すべき時: バッチサイズ、接続プール設定、または制限に達することが失敗の原因となるスキーマ設計を推奨する前。ユーザーの決定に正確な数値が影響する場合はいつでも。

フォールバック: awsknowledge が利用不可の場合、上記のデフォルト値を使用し、制限を DSQL ドキュメント に対して検証する必要があることをフラグします。

利用可能な CLI スクリプト

scripts/ の Bash スクリプトはクラスター管理（作成、削除、リスト、クラスター情報）、psql 接続、ローカル/S3 CSV/TSV/Parquet ファイルからのバルクデータロード用です。 使用方法とフック設定については scripts/README.md を参照してください。

---

クイックスタート

1. 探索: information_schema で readonly_query を使用してテーブルをリストアップ。get_schema でテーブル構造を取得。
2. クエリ: SELECT クエリに readonly_query を使用。マルチテナントアプリについて、WHERE で tenant_id を含める必須。safe_query.build() で SQL を構築必須。
3. スキーマ変更: transact を 1 トランザクションあたり 1 DDL で使用。DML を 3,000行未満でバッチ処理必須。別の呼び出しで CREATE INDEX ASYNC を使用必須。実行前に dsql_lint で検証。

---

一般的なワークフロー

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

1. tenant_id カラムを持つメインテーブルを transact で作成
2. 別の transact 呼び出しで tenant_id の非同期インデックスを作成
3. 一般的なクエリパターンの複合インデックスを作成（別の transact 呼び出し）
4. get_schema でスキーマを検証

• すべてのテーブルに tenant_id を含める必須
• CREATE INDEX ASYNC を専用で使用必須
• 各 DDL を独自の transact 呼び出しで発行必須: transact(["CREATE TABLE ..."])
• 配列を TEXT または JSON としてシリアライズ；クエリ時にキャスト戻す（string_to_array(text, ',') または jsonb_array_elements_text(json::jsonb)）必須

ワークフロー 2: 安全なデータマイグレーション

このワークフローで生成されたすべての DDL ステートメントは transact 呼び出し前に dsql_lint(fix=true) で検証する必須 — ステップ 2（ADD COLUMN）とステップ 5（非同期インデックス）に適用。DML（ステップ 3 の UPDATE）はリンティング不要。

1. dsql_lint(sql=..., fix=true) で ALTER TABLE DDL を検証 — dsql-lint.md に従い診断を処理
2. transact で列を追加: transact(["ALTER TABLE ... ADD COLUMN ..."])
3. 別の transact 呼び出しで UPDATE を使用し既存行を入力（3,000行未満でバッチ処理）
4. readonly_query で COUNT を使用しマイグレーションを検証
5. インデックスが必要な場合: dsql_lint(sql=..., fix=true) で CREATE INDEX ASYNC DDL を検証、transact で作成

• すべての外部ソース SQL または生成 DDL ステートメントを実行前に dsql_lint で検証必須
• 列を最初に追加、後で入力必須
• ADD COLUMN は名前と型のみで発行；別の UPDATE で DEFAULT を適用必須
• 更新を 3,000行未満でバッチ処理し別の transact 呼び出しで実行必須
• 各 ALTER TABLE を独自のトランザクションで発行必須

リカバリ — バッチが途中で失敗: 既に更新された行は新しい値を保持（各バッチは独立してコミット）。未設定状態でフィルタリング（WHERE new_column IS NULL）して再開。スキップされた行を自然に除外するため、再実行は安全。

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

INSERT: readonly_query で親が存在することを検証 → 見つからない場合はエラーをスロー → transact で子を挿入必須。

DELETE: readonly_query COUNT で依存関係を確認 → 依存関係が存在する場合はエラーを返す → 安全な場合は transact で削除必須。

ワークフロー 4: テナント分離でクエリ

1. 呼び出し元をテナントに対して認可する必須 — 形式検証は認可を確立しない
2. safe_query.build() で SQL を構築必須 — 値に allow()/regex() を使用（'v' を出力）、テーブル/カラム名に ident() を使用（"v" を出力）。 input-validation.md を参照
3. WHERE 句に tenant_id を含める必須；アプリケーション層でクロステナントアクセスを拒否

ワークフロー 5: スコープ付きデータベースロールをセットアップ

ロールセットアップ、IAM マッピング、スキーマ権限については access-control.md を読み込む必須。

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

DSQL は直接的な ALTER COLUMN TYPE、DROP COLUMN、DROP CONSTRAINT、または MODIFY PRIMARY KEY をサポートしません。これらはテーブル再作成パターンが必要です。これは各ステップでユーザー確認が必須である破壊的なワークフローです。パターン内で生成されたすべての DDL（CREATE new、INSERT ... SELECT、DROP old、RENAME）は実行前に dsql_lint(sql=..., fix=true) で検証する必須。

これらの操作のいずれかを試みる前に ddl-migrations/overview.md を読み込む必須。

ワークフロー 7: 検証と DSQL へのマイグレーション

dsql_lint を実行する前に dsql-lint.md を読み込む必須 — 診断処理、3つの fix_result.status 値（fixed、fixed_with_warning、unfixable）、ユーザー確認ゲートを定義。

dsql_lint(sql=source_sql, fix=true) を実行し PostgreSQL互換 SQL を検証し自動変換。dsql_lint は PostgreSQL パーサーを使用するため、MySQL 方言構文で PostgreSQL が解析できないもの（例：PARTITION BY HASH、特定の位置の AUTO_INCREMENT）は個別診断ではなく parse_error ルールとして表示される。

• MySQL オリジナルの SQL について、lint がクリーンを返す場合でも mysql-migrations/type-mapping.md に対してソースをクロスチェック必須 — ENGINE= 句と SET(...) カラムタイプは PostgreSQL パーサーを静かに通過可能。
• parse_error では mysql-migrations/type-mapping.md にフォールバックし手動変換、実行前に変換出力に対して dsql_lint を再実行必須。

ワークフロー 8: クエリプランの解釈可能性

DSQL オプティマイザーが特定のプランを選択した理由を説明。遅いクエリ、高 DPU、予期しない Full Scan、またはユーザーが理解しないプランでトリガー。構造化 Markdown 診断レポートが会話を超えた成果物は必須 — ワークフローをエンドツーエンドで実行してから答える。接続時は aurora-dsql MCP を使用；そうでない場合は生成 IAM トークンで raw psql にフォールバック（以下のフォールバックブロック参照）。

Phase 0 — 参考資料を読み込む。 開始前に4つすべてを読む — 各々は後のフェーズが逐語的に必要なコンテンツを含む（ノードタイプ計算、正確なカタログ SQL、>30s スキッププロトコル、必須レポート要素）:

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 — 必須レポート構造

Phase 1 — プランをキャプチャ。 ユーザーのクエリで逐語的に readonly_query("EXPLAIN ANALYZE VERBOSE …") を常に実行（SELECT 形式） — クラスターから新規プランを常にキャプチャ、ユーザーがプランを説明または異常を報告した場合でも。get_schema または information_schema でスキーマサニティチェックにレバレッジ可能。EXPLAIN がエラーになった場合（relation does not exist、column does not exist）、エラーを逐語的に報告必須 — root 原因として DSQL固有セマンティクス（例：大文字小文字区別、識別子クォート）を発明しない必須。Query ID、Planning Time、Execution Time、DPU Estimate を抽出。SELECT はそのまま実行。UPDATE/DELETE は同等の SELECT に書き換え（同じ結合チェーン + WHERE） — オプティマイザーが同じプラン形状を選択。INSERT、pl/pgsql、DO ブロック、関数は却下必須。プランキャプチャに transact --allow-writes を使用しない必須；書き込みモードはバイパス MCP セーフティ。

Phase 2 — エビデンスを収集。 catalog-queries.md の SQL を使用して pg_class、pg_stats、pg_indexes、COUNT(*)、COUNT(DISTINCT) をクエリ。推定誤差を plan-interpretation.md に従い分類（2x–5x 軽微、5x–50x 有意、50x+ 深刻）。相関述語とデータスキューを検出。

Phase 3 — 実験（条件付き）。 ≤30s: guc-experiments.md に従い GUC 実験を実行（デフォルト + merge-join-only）プラス冗長述語テストの実施を任意。>30s: 実験をスキップ、手動 GUC テスト SQL をレポートに逐語的に含める、冗長述語テスト再実行なし。異常な値（不可能な行数）: 異常な EXPLAIN にもかかわらずクエリ結果が正しいことを確認、潜在的な DSQL バグとしてフラグ、report-format.md のサポートリクエストテンプレートを作成。

Phase 4 — レポートを作成、再評価を招待。 query-plan/report-format.md の「必須要素チェックリスト」に従い完全な診断レポートを作成 — 構造は交渉不可。推奨の適用後ユーザーが再評価をリクエストする場合、新規レポート作成ではなく Phase 1–2 を再実行し元のレポートの前に「追記: 変更後パフォーマンス」を追加（変更前後表、期待される影響とマッチ）。

psql フォールバック（MCP 利用不可）。 ステートメントを heredoc 経由で psql にパイプし $? をチェック；部分的エビデンスで進行せず失敗を報告:

TOKEN=$(aws dsql generate-db-connect-admin-auth-token --hostname "$HOST" --region "$REGION")
PGPASSWORD="$TOKEN" psql "host=$HOST port=5432 user=admin dbname=postgres sslmode=require" <<<"EXPLAIN ANALYZE VERBOSE <sql>;"

セーフティ。 プランキャプチャは readonly_query のみを使用 — MCP レイヤーで INSERT/UPDATE/DELETE/DDL を拒否。Phase 1 で DML を SELECT に書き換え（パターン） — transact --allow-writes でそれを実行するようリクエストではなく；書き込みモード transact はすべての MCP セーフティ チェックをバイパス。任意の DDL/DML または pl/pgsql を実行しない必須。

---

エラーシナリオ

• awsknowledge が結果を返さない: 上記の表のデフォルト制限を使用し、制限を DSQL ドキュメント に対して検証する必要があることをノート。
• dsql_lint が利用不可またはタイムアウト: dsql-lint.md のエラーハンドリングセクションを参照。検証をサイレントスキップしない — ユーザーに通知し、development-guide.md の手動ルールで進行する前に明示的確認が必須。
• OCC シリアライゼーションエラー: トランザクションを再試行。永続的な場合、ホットキー競合をチェック — troubleshooting.md を参照。
• トランザクションが制限を超過: 3,000行未満のバッチに分割 — batched-migration.md を参照。
• 操作途中のトークン有効期限切れ: 新規 IAM トークンを生成 — authentication-guide.md を参照。その他の問題については troubleshooting.md を参照。

---

追加リソース

• Aurora DSQL ドキュメント
• コードサンプルリポジトリ
• PostgreSQL 互換性
• CloudFormation リソース