dsql

Amazon Aurora DSQL スキル

Aurora DSQL は、サーバーレスで PostgreSQL と互換性のある分散 SQL データベースです。このスキルでは、MCP ツールによる直接クエリの実行、スキーマ管理、マイグレーション、マルチテナント分離、IAM 認証、aurora-dsql-loader による一括データ読み込みについて説明します。

---

リファレンスファイル

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

コア：

リファレンス	読み込むタイミング	内容
development-guide.md	スキーマ変更や DB 操作の前に必ず読み込む	ベストプラクティス、DDL のルール、トランザクションの制限、外部キー制約
foreign-keys.md	外部キーの操作やマイグレーション時に必ず読み込む	FK 構文、アクション、検証、テナントキー
language.md	言語固有の選択を行う際に必ず読み込む	ドライバーの選択、DSQL コネクター、接続コード
access-control.md	ロール、権限付与、機密データを扱う際に必ず読み込む	スコープ付きロールの設定、IAM からデータベースロールへのマッピング
troubleshooting.md	エラーや予期しない動作が発生した場合に読み込む	OCC と 23503、FK、接続、クラスターの状態
limits-and-error-codes.md	バッチ、キー、インデックスのサイズを決める前、または 54000／0A000／54011 の発生時に読み込む	SQLSTATE と正確なメッセージを含むすべての制限、拒否、クォータ
dsql-examples.md	実装例が必要な場合に読み込む	マルチテナントアクセス、バッチ操作、ID とシーケンス、コネクションプーリング
onboarding.md	ユーザーが「DSQL を始める」と依頼した場合	対話形式のステップバイステップガイド
occ-retry-patterns.md	OCC のリトライコードや競合の緩和策を扱う際に必ず読み込む	コネクター、40001 のリトライ、リトライ不可の 23503、FK 読み取り競合、冪等性のある設計

MCP：

リファレンス	読み込むタイミング	内容
mcp-setup.md	MCP サーバーのガイダンスを行う際に必ず読み込む	セットアップ手順、2 つの設定オプション
mcp-tools.md	MCP ツールの構文や例を確認する際に読み込む	ツールのパラメーター、入力の検証
dsql-lint.md	dsql_lint の実行前、または外部 SQL の処理前に必ず読み込む	ツールのリファレンス、修正ステータス、修正不可能なエラーの解決方法

DDL の移行：

参照	読み込むタイミング	含まれる内容
ddl-migrations/overview.md	ALTER TYPE、SET NOT NULL、主キーの変更では必ず読み込みます	直接 ALTER の対応範囲と最終手段としてのテーブル再作成
ddl-migrations/column-operations.md	DROP COLUMN、ALTER TYPE、SET/DROP NOT NULL/DEFAULT	列レベルの移行パターン
ddl-migrations/constraint-operations.md	ADD/DROP CONSTRAINT、VALIDATE CONSTRAINT、主キーの変更	制約と構造の変更
ddl-migrations/batched-migration.md	3,000 行を超えるテーブル	バッチ処理パターン、進捗状況の追跡

MySQL の移行：

参照	読み込むタイミング	含まれる内容
mysql-migrations/type-mapping.md	MySQL → DSQL の移行では必ず読み込みます	データ型のマッピング、機能の代替手段
mysql-migrations/ddl-operations.md	MySQL DDL を DSQL に変換する場合	AUTO_INCREMENT、ENUM、SET、FK のパターン
mysql-migrations/full-example.md	MySQL テーブルを完全に移行する場合	判断の概要を含むエンドツーエンドの例

PostgreSQL の移行：

参照	読み込むタイミング	含まれる内容
pg-migrations/type-mapping.md	DSQL NUMERIC または PG の型に関する質問では必ず読み込みます	C 照合順序のルール、NUMERIC(p,s)、JSON/JSONB
pg-migrations/index-conversion.md	インデックス変換またはインデックスのサポートに関する質問では必ず読み込みます	GIN/GiST/BRIN → btree、演算子クラスの削除、部分インデックスと式インデックス、ソート順
pg-migrations/schema-objects.md	ENUM、マテリアライズドビュー、拡張機能、複数スキーマ、CREATE FUNCTION では必ず読み込みます	ENUM → CHECK、ビュー、ロール/IAM のマッピング、LANGUAGE sql 関数
pg-migrations/multi-region.md	マルチリージョン、アクティブ-アクティブ、または HA に関する質問	アーキテクチャ、地理的なパーティショニング

ORM ガイド:

リファレンス	読み込むタイミング	内容
orm-guides/overview.md	ORM の移行、または DSQL での ORM ロックの使用時	Django/EF Core/Hibernate/Rails/SQLAlchemy のアダプター名、ロック、および主な注意点

データロード:

リファレンス	読み込むタイミング	内容
data-loading.md	aurora-dsql-loader を使用した一括ロードの計画または実行時	新規パーティションとウォームパーティション、再開/再試行、--on-conflict のセマンティクス、スループット診断

システム診断:

リファレンス	読み込むタイミング	内容
system-diagnostics/workflow.md	ワークフロー 12 の開始時に必ず読み込む — クラスターパフォーマンス診断	前提条件、5 つの診断フェーズ、時系列比較、引き継ぎ
system-diagnostics/wait-events.md	AAS の結果を解釈する際は常に読み込む	標準的な DSQL 待機イベントの説明と調査ガイダンス
system-diagnostics/promql-patterns.md	PromQL クエリを構築する際に読み込む	AAS の内訳、トップ SQL、時系列比較のための再利用可能なクエリテンプレート

クエリプランの説明可能性：

参照	読み込むタイミング	内容
query-plan/workflow.md	ワークフロー 9 の開始時に必ず読み込む — 他のすべてのファイルの読み込みを制御します	トリガー条件、コンテキストの曖昧さの解消、ルーティング、段階的なワークフロー
query-plan/plan-interpretation.md	ワークフロー 9 のフェーズ 0 で必ず読み込む	DSQL ノードタイプ、ノードの実行時間の計算、推定誤差の範囲
query-plan/catalog-queries.md	ワークフロー 9 のフェーズ 0 で必ず読み込む	pg_class/pg_stats/pg_indexes の SQL、相関述語の検証
query-plan/guc-experiments.md	ワークフロー 9 のフェーズ 0 で必ず読み込む	GUC 実験の手順、30 秒のスキップ手順
query-plan/report-format.md	ワークフロー 9 のフェーズ 0 で必ず読み込む	必須のレポート構成、要素チェックリスト、サポート依頼テンプレート
query-plan/query-rewrites-generic.md	フェーズ 0 で読み込むことが推奨されます。サブファイルは必要に応じて読み込みます	汎用的な書き換えパターン 10 種類の一覧
query-plan/query-rewrites-dsql-specific.md	フェーズ 0 で読み込むことが推奨されます。サブファイルは必要に応じて読み込みます	DSQL 固有の書き換えパターンの一覧

---

接続方法の選択：MCP と CLI/psql

aurora-dsql MCP サーバーは、起動時に単一のクラスターにバインドされます（--cluster_endpoint）。そのため、別のクラスターで使用するには .mcp.json を編集してセッションを再起動する必要があります。

• 必要なクラスターをすでに対象にしている場合に限り、aurora-dsql MCP ツール（readonly_query、transact、get_schema）を使用してください。
• それ以外の場合（未設定、無効、または別のクラスターにバインドされている場合）は、再設定しないでください。 代わりに、CLI + psql の方法を使用します：scripts/psql-connect.sh <cluster-id> --region <region> --command "SELECT ..."（IAM トークンを発行し、psql 経由で実行します）。
• MCP の対象クラスターを確認できない場合は、まず確認するか、CLI/psql の方法を使用してください — 間違ったクラスターに対して実行するより、確認するほうが重要です。

ドキュメント専用の MCP ツール（dsql_lint、dsql_*_documentation、dsql_recommend）にはクラスターは不要です。 CloudWatch MCP（ワークフロー 12）は呼び出しごとに region/cluster_id を受け取るため、実行中の 1 つのサーバーで、PromQL が有効な任意のリージョンにあるクラスターをクエリできます（呼び出し時に各クラスターのリージョンを指定してください）。詳細： connectivity-tools.md。

利用可能な MCP ツール

aurora-dsql MCP サーバーでは、次のツールを利用できます。

データベース操作：

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

SQL 検証：

1. dsql_lint - DSQL との互換性を検証し、必要に応じて問題を自動修正します。外部から取得した SQL を実行する前に使用してください。

ドキュメントとナレッジ：

1. dsql_search_documentation - Aurora DSQL のドキュメントを検索します
2. dsql_read_documentation - 指定したドキュメントページを読み込みます
3. dsql_recommend - DSQL のベストプラクティスに関する推奨事項を取得します

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

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

AWS Knowledge MCP（awsknowledge）

ユーザーに助言する前に、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
認証トークンの有効期限	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
サポートされる列データ型	ドキュメントを参照	aurora dsql supported data types

確認が必要な場合： 制限に達すると失敗する可能性があるバッチサイズ、接続プールの設定、スキーマ設計を推奨する前や、正確な数値がユーザーの判断に影響する場合は、必ず確認してください。各 SQLSTATE と正確なエラーメッセージを含むすべての制限については、limits-and-error-codes.md を参照してください。観測値として記載されている値とドキュメントの値が異なる場合は、観測値を使用してください。

フォールバック： awsknowledge を利用できない場合は、上記のデフォルト値を使用し、制限値は DSQL のドキュメントで確認する必要があることを明記してください。

利用可能な CLI スクリプト

クラスター管理（作成、削除、一覧表示、クラスター情報）、psql 接続、ローカルまたは s3 の csv/tsv/parquet ファイルからの一括データ読み込みに使用できる Bash スクリプトは、scripts/ にあります。 使い方とフックの設定については、scripts/README.md を参照してください。

---

クイックスタート

0. 接続方法を選択します： aurora-dsql MCP がご利用のクラスターを対象にしていることを確認します。対象でない場合は、代わりに CLI／psql を使用してください。詳しくは接続方法の選択（MCP と CLI／psql）をご覧ください。以下の手順では MCP ツールを使用します。同等の SQL は psql-connect.sh --command "..." でも同じように実行できます。
1. 確認します： information_schema に対して readonly_query を使用し、テーブルを一覧表示します。テーブル構造の確認には get_schema を使用します。
2. クエリを実行します： SELECT クエリには readonly_query を使用します。マルチテナントアプリでは、WHERE に tenant_id を必ず含めてください。SQL は safe_query.build() を使用して必ず構築してください。
3. スキーマを変更します： 1 回のトランザクションにつき 1 つの DDL を指定して transact を使用します。DML は 3,000 行未満で必ずバッチ処理してください。CREATE INDEX ASYNC は別の呼び出しで必ず実行してください。まず dsql_lint を使用して検証します。
4. データを一括ロードします： CSV／TSV／Parquet には aurora-dsql-loader を使用します。詳細は data-loading.md を読み込んでください。まず --dry-run を使用します。

---

パフォーマンスに応じたルーティング

ユーザーからパフォーマンスの問題が報告された場合は、この表を使用して適切なワークフローを選択します。

ユーザーの兆候	案内先
一般的なパフォーマンスの不満、「クラスターが遅い」、「何かが変わった」、レイテンシの悪化、特定のクエリが特定されていない	ワークフロー 12（システム診断）— まず CloudWatch で状況を確認します
調査対象の特定のクエリまたは query_id、「このプランを説明して」、「このクエリが遅い理由は」	ワークフロー 9（クエリプランの説明可能性）— EXPLAIN を直接分析します
OCC の競合、コミットエラー、リトライの集中	ワークフロー 12（システム診断）— 調査の前に CW メトリクスで確認します
コスト最適化、「コンピューティング時間はどこで消費されているか」	ワークフロー 12（システム診断）— まず主な要因を特定します

ルール： 迷った場合は、ワークフロー 12 から開始します。調査対象となる特定のクエリを特定し、状況を添えてワークフロー 9 に案内します。

---

よくあるワークフロー

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

1. tenant_id を持つテナント所有テーブルを作成します。transact は呼び出しを分けて使用します
2. テナント所有の親テーブルには複合テナント FK を、共有の親テーブルには通常の FK を使用します
3. テナントおよびクエリパターンのインデックスを、個別の CREATE INDEX ASYNC 呼び出しで作成します
4. get_schema で検証します

• 各 DDL はそれぞれ別の transact 呼び出しで必ず実行してください：transact(["CREATE TABLE ..."])
• 配列は単一列の表現に必ずシリアライズしてください。DSQL には配列型の列がありません。JSONB を優先してください（演算子を直接使用できます）。列がデータベースにとって不透明な場合は TEXT を使用してもかまいません。ユーザーに確認してください。JSONB 配列は、クエリ時に jsonb_array_elements_text(data) で展開します

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

実行前に必ずすべての DDL を dsql_lint(fix=true) で検証してください。DML にはリンティングは不要です。

1. dsql_lint(sql=..., fix=true) で DDL を検証します — 診断結果は dsql-lint.md に従って処理します
2. レビュー済みの fixed_sql が存在する場合はそれを実行し、そうでなければレビュー済みの元のステートメントを実行します
3. カラムの追加は専用の transact 呼び出しで行います
4. 既存の行は UPDATE で埋めます（3,000 行未満のバッチで）
5. readonly_query の COUNT で検証します
6. 必要に応じてインデックスを作成します: レビュー済みの DDL を検証してから、専用の transact 呼び出しで実行します

• 各 ALTER TABLE は必ず専用の transact 呼び出しで発行してください — DSQL は複数 DDL のトランザクションを multiple ddl statements not supported in a transaction で拒否します
• カラムの追加は必ず名前と型のみで行ってください。DEFAULT は別の UPDATE で適用します
• 更新は必ず 3,000 行未満のバッチで、別々の transact 呼び出しに分けてください

リカバリ: 失敗したバッチは WHERE new_column IS NULL でフィルタリングして再開します。

ワークフロー 3: 一括データロード

CSV、TSV、または Parquet のロードには aurora-dsql-loader を使用します。スループットについて助言したり、遅いロードを診断したりする前に、必ず data-loading.md をロードしてください。

1. まず --dry-run で検証します
2. 永続ストレージ上で --manifest-dir を指定して実行します（/tmp は不可 — AL2023 では tmpfs であり、クラッシュ時に失われます）。ファイルにヘッダー行がある場合は --header を指定します
3. 失敗時: --resume-job-id で再開します。重複には --on-conflict do-nothing を使用します
4. 大きなテーブルの場合: ロード後に CREATE INDEX ASYNC を使用してセカンダリインデックスを作成します

ワークフロー 4: 外部キー制約

外部キーを作成、変更、削除、または移行する前に、必ず foreign-keys.md をロードして従ってください。

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

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

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

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

ワークフロー 7: テーブル再作成による DDL 移行

ALTER COLUMN TYPE、SET NOT NULL、または MODIFY PRIMARY KEY の場合、必ず ddl-migrations/overview.md をロードしてください。サポートされている場合は 直接 ALTER 形式を使用します。そうでない場合は、ユーザーが承認したテーブル再作成プランを提示します。

ワークフロー 8: 検証と DSQL への移行

dsql_lint を実行する前に、必ず dsql-lint.md をロードしてください。dsql_lint(sql=source_sql, fix=true) を実行して検証と自動変換を行います。MySQL 由来の SQL の場合、リントがクリーンであっても必ず mysql-migrations/type-mapping.md と照合してください。parse_error の場合は、手動変換にフォールバックしてから再リントします。

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

DSQL オプティマイザが特定のプランを選択した理由を説明します。遅いクエリ、高い DPU、予期しない Full Scan、またはユーザーが理解できないプランによってトリガーされます。成果物として構造化された Markdown 診断レポートが必要です。

開始時に必ず query-plan/workflow.md をロードしてください — これにはトリガー基準、コンテキストの曖昧性解消、ルーティング、および完全な段階的ワークフロー（フェーズ 0〜4）が定義されています。workflow.md は各フェーズでロードすべき参照ファイルを指定しています。

安全性。 プランのキャプチャには readonly_query のみを使用します。プランキャプチャのために DML を SELECT に書き換えます。プランキャプチャに transact --allow-writes を使用してはなりません。

ワークフロー 10：PostgreSQL → DSQL の完全なスキーマ移行

pg-migrations/type-mapping.md、pg-migrations/index-conversion.md、pg-migrations/schema-objects.md、および foreign-keys.md を必ず読み込んでください。まず dsql_lint(fix=true) を実行して機械的な修正を行い、外部キーの関係を維持し、サポートされていないソース構文やオプションを変換してから、修正できない診断結果やリンターで処理できないパターンに対し、pg-migrations のリファレンスに記載されたセマンティック変換を適用します。デプロイする前に、最終出力を再度リンティングしてください。

ワークフロー 11：ORM の移行とロック（Django/EF Core/Hibernate/Rails/SQLAlchemy）

アダプター名、ロックに関するガイダンス、フレームワーク固有の注意点について、orm-guides/overview.md を読み込んでください。

ワークフロー 12：システム診断（CloudWatch AAS）

PromQL を使用して db.active_sessions.avg をクエリし、クラスターのパフォーマンスを診断します。待機イベントの分布における時間的な異常を検出し、性能が低下したクエリを特定して、クエリごとの調査を行うワークフロー 9 に引き継ぎます。

必要条件： CloudWatch MCP サーバー（awslabs.cloudwatch-mcp-server）が有効になっており、クラスターと同じリージョンで PromQL にアクセスできるよう設定されている必要があります。有効化の方法、リージョン要件、ツールを登録するために必要なセッションの再起動については、mcp/mcp-setup.md を参照してください。

開始時に必ず system-diagnostics/workflow.md を読み込んでください。このファイルには、前提条件、5 つの診断フェーズ、時間的なベースライン、および特定したクエリをワークフロー 9 に引き継ぐ方法が定義されています。

エラー発生時の対応

• awsknowledge が結果を返さない場合： 上の表に記載されたデフォルトの上限を使用し、上限は DSQL のドキュメントで確認する必要があることを記載してください。
• dsql_lint が利用できない、またはタイムアウトする場合： dsql-lint.md の「エラー処理」セクションを参照してください。検証を黙って省略してはいけません。ユーザーにその旨を伝え、development-guide.md の手動ルールを使って先に進む前に、明示的な承認を得てください。
• OCC シリアライズエラー（40001）： バックオフを行って再試行し、ループには (OC001) も含めてください。詳しくは occ-retry-patterns.md を参照してください。
• 外部キー違反（23503）： 関係または参照アクションを修正してください。40001 の再試行ループに含めてはいけません。troubleshooting.md を参照してください。
• トランザクションが上限を超える場合： 1 バッチあたり 3,000 行未満かつ 10 MiB 未満に分割してください。サイズは COMMIT 時に確認されます。サイズの調整については limits-and-error-codes.md、パターンについては batched-migration.md を参照してください。
• 操作の途中でトークンの有効期限が切れた場合： 新しい IAM トークンを生成してください。authentication-guide.md を参照してください。その他の問題については troubleshooting.md を参照してください。

追加リソース

• Aurora DSQL のドキュメント
• コードサンプルリポジトリ