dsql

Amazon Aurora DSQL スキル

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

---

リファレンスファイル

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

コア：

リファレンス	読み込むタイミング	内容
development-guide.md	スキーマ変更または DB 操作の前に必ず読み込んでください	ベストプラクティス、DDL ルール、トランザクションの制限、アプリケーション層での参照整合性
language.md	言語固有の選択を行う際に必ず読み込んでください	ドライバーの選択、DSQL Connectors、接続コード
access-control.md	ロール、権限付与、または機密データを扱う際に必ず読み込んでください	スコープを限定したロールの設定、IAM とデータベースのロールマッピング
troubleshooting.md	エラーや予期しない動作が発生した場合に読み込むことを推奨します	OCC エラー、接続失敗、クラスター状態のエラー、トークンの有効期限切れ、DDL が拒否される原因
dsql-examples.md	実装例が必要な場合に読み込んでください	マルチテナントのスキーマ例、バッチ処理、FK 検証パターン、接続プーリング
onboarding.md	ユーザーが「DSQL を始める」ことを求めた場合	対話形式のステップバイステップガイド
occ-retry-patterns.md	OCC の再試行コードや競合の軽減策を扱う際に必ず読み込んでください	DSQL Connectors、手動再試行パターン、冪等性を考慮した設計

MCP：

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

DDL のマイグレーション：

参照	読み込むタイミング	内容
ddl-migrations/overview.md	DROP COLUMN、ALTER TYPE、DROP CONSTRAINT の場合は必ず読み込む	テーブル再作成パターン、検証と切り替え
ddl-migrations/column-operations.md	DROP COLUMN、ALTER TYPE、SET/DROP NOT NULL/DEFAULT	カラム単位のマイグレーションパターン
ddl-migrations/constraint-operations.md	ADD/DROP CONSTRAINT、PRIMARY KEY の変更	制約と構造の変更
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	PG → DSQL の型に関する質問では必ず読み込む	C 照合順序のルール、NUMERIC の精度、JSON/JSONB
pg-migrations/fk-replacement.md	FK 検証コードの生成では必ず読み込む	テナントスコープの validate_fk_*() テンプレート、カスケード
pg-migrations/index-conversion.md	修正不可能なインデックスの診断では必ず読み込む	GIN/GiST/BRIN → btree、部分インデックス、式インデックス
pg-migrations/schema-objects.md	ENUM、マテリアライズドビュー、拡張機能、複数スキーマでは必ず読み込む	ENUM → CHECK、ビュー、ロール/IAM のマッピング
pg-migrations/multi-region.md	マルチリージョン、アクティブ-アクティブ、または HA に関する質問	アーキテクチャ、地理的パーティショニング

ORM ガイド：

リファレンス	読み込むタイミング	内容
orm-guides/overview.md	任意の ORM を DSQL に移行するとき	アダプター名、Django／Hibernate／Rails／SQLAlchemy の重要な注意点

データの読み込み：

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

クエリプランの説明：

リファレンス	読み込むタイミング	内容
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 で必ず読み込む	必須のレポート構成、要素チェックリスト、サポート依頼テンプレート

---

利用可能な 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 ツールはありません。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 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 or >= 65536	aurora dsql sequence cache
サポートされるカラムのデータ型	ドキュメントを参照	aurora dsql supported data types

確認するタイミング： 制限に達すると失敗につながるバッチサイズ、接続プールの設定、スキーマ設計を推奨する前や、正確な数値がユーザーの判断に影響する場合は、必ず確認してください。

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

CLI ツール

クラスター管理、SQL 接続、ローカルまたは S3 の CSV/TSV/Parquet ファイルからの一括データ読み込みには、AWS CLI、psql、aurora-dsql-loader を直接使用してください。ローダーのガイダンスについては、data-loading.md を読み込んでください。

---

クイックスタート

1. 調査： information_schema を使って readonly_query でテーブルを一覧表示します。テーブル構造には get_schema を使用します。
2. クエリ： SELECT クエリには readonly_query を使用します。マルチテナントアプリでは、WHERE に tenant_id を含める必要があります。SQL は必ず safe_query.build() で構築してください。
3. スキーマの変更： トランザクションごとに DDL を 1 つだけ指定して transact を使用します。DML は必ず 3,000 行未満の単位でバッチ処理してください。CREATE INDEX ASYNC は必ず別の呼び出しで使用してください。まず dsql_lint で検証してください。
4. データの一括読み込み： CSV/TSV/Parquet には aurora-dsql-loader を使用します。詳細については data-loading.md を読み込んでください。まず --dry-run を使用してください。

---

一般的なワークフロー

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

1. transact を使用して、tenant_id カラムを含むメインテーブルを作成します
2. 別の transact 呼び出しで、tenant_id に非同期インデックスを作成します
3. よく使われるクエリパターン向けに複合インデックスを作成します（それぞれ別の transact 呼び出しを使用）
4. get_schema でスキーマを確認します

• すべてのテーブルに tenant_id を必ず含めてください
• CREATE INDEX ASYNC のみを必ず使用してください
• 各 DDL は必ず個別の transact 呼び出しで実行してください：transact(["CREATE TABLE ..."])
• 配列は必ず JSONB としてシリアライズしてください。クエリ時に jsonb_array_elements_text(data) で展開します

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

実行前に、すべての DDL を dsql_lint(fix=true) で検証する必要があります。DML のリンティングは不要です。

1. dsql_lint(sql=..., fix=true) で DDL を検証します — 診断への対処方法は dsql-lint.md を参照してください
2. カラムを追加します：transact(["ALTER TABLE ... ADD COLUMN ..."])
3. UPDATE で既存の行に値を設定します（3,000 行未満のバッチに分けます）
4. readonly_query COUNT で検証します
5. 必要に応じてインデックスを作成します：検証後に transact(["CREATE INDEX ASYNC ..."]) を実行します

• 各 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：アプリケーション層での参照整合性

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

DELETE： readonly_query COUNT で依存レコードを確認する必要があります → 依存レコードが存在する場合はエラーを返します → 安全な場合は transact で削除します。

ワークフロー 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、DROP COLUMN、DROP CONSTRAINT、または MODIFY PRIMARY KEY には、テーブル再作成パターンを使用します。これは各ステップでユーザーの確認が必要な破壊的なワークフローです。このパターンで生成されるすべての DDL（CREATE new、INSERT ... SELECT、DROP old、RENAME）は、実行前に dsql_lint(sql=..., fix=true) で検証する必要があります。

これらの操作を試みる前に、ddl-migrations/overview.md を読み込む必要があります。

ワークフロー 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 が高い場合、予期しないフルスキャンが発生した場合、またはユーザーが理解できないプランがある場合に実行します。成果物として、構造化された Markdown 診断レポートが必須です。

フェーズ 0 で、次の 4 つの参照ファイルをすべて読み込む必要があります：query-plan/plan-interpretation.md、query-plan/catalog-queries.md、query-plan/guc-experiments.md、query-plan/report-format.md。フェーズの手順（プランの取得、証拠の収集、実験、レポートの作成）は、これらのファイルで定義されています。

安全性。 プランの取得には readonly_query のみを使用します。プラン取得時には DML を SELECT に書き換えてください。プランの取得に transact --allow-writes を使用してはなりません。

ワークフロー 10：PostgreSQL から DSQL へのスキーマ全体の移行

pg-migrations/type-mapping.md と pg-migrations/schema-objects.md を読み込む必要があります。まず dsql_lint(fix=true) を実行して機械的に修正し、その後、修正できない診断結果やリンターで処理できないパターンに対して、pg-migrations の参照ファイルに記載されたセマンティックな変換を適用します。デプロイ前に、最終的な出力を再度 lint してください。

ワークフロー 11：ORM の移行（Django/Hibernate/Rails）

アダプター名とフレームワーク固有の注意点については、orm-guides/overview.md を読み込んでください。

エラーが発生した場合

• awsknowledge が結果を返さない場合： 上の表にある既定の制限を使用し、制限を DSQL documentation で確認する必要があることを明記してください。
• dsql_lint が利用できない、またはタイムアウトする場合： dsql-lint.md の「エラー処理」セクションを参照してください。検証を黙って省略してはなりません。ユーザーにその旨を伝え、development-guide.md に記載された手動ルールで続行する前に、明示的な確認を得てください。
• OCC のシリアライズエラー： トランザクションを再試行してください。解消しない場合は、ホットキーの競合を確認してください。troubleshooting.md を参照してください。
• トランザクションが制限を超える場合： batched-migration.md を参照し、3,000 行未満のバッチに分割してください。
• 操作中にトークンの有効期限が切れた場合： authentication-guide.md を参照し、新しい IAM トークンを生成してください。その他の問題については、troubleshooting.md を参照してください。

追加リソース

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