alibabacloud-dms-skill

Alibaba Cloud DMS データベースの読み取り／書き込み

Alibaba Cloud DMS OpenAPI を使用して対象データベースを検索し、SQL クエリとデータ変更を実行します。

シナリオの説明

このスキルでは、次のワークフローを実行します。

1. 対象データベースを検索 — キーワードでデータベースを検索し、データベース ID を取得します
2. SQL クエリを実行 — 対象データベースで SQL 文を実行します

アーキテクチャ

User Request → Search Database → Get Database ID → Execute SQL → Return Results

前提条件

AI-Mode のライフサイクル（必ず順番に実行）

このスキルは AI-Mode セッション内で実行する必要があります。次の 5 つのステップを厳格なライフサイクルとして扱い、スキップや順序の入れ替えをせず、セットアップ手順とコマンド実行を混在させないでください。

1. aliyun configure ai-mode enable                                              # Enable AI-Mode
2. aliyun configure ai-mode set-user-agent AlibabaCloud-Agent-Skills/alibabacloud-dms-skill   # Register skill User-Agent
3. aliyun configure set --auto-plugin-install true && aliyun plugin update      # Plugin update
4. <execute DMS commands via ./scripts/*.sh>                                    # Execute commands
5. aliyun configure ai-mode disable                                             # Disable AI-Mode (Cleanup)

ステップ 1～3 はセットアップ（このセクション）に属します。ステップ 4 はコアワークフローで説明します。ステップ 5 はクリーンアップで説明します。

事前確認

事前確認 0：Aliyun CLI 3.3.3 以降が必要です aliyun version を実行して、バージョンが 3.3.3 以降であることを確認します。インストールされていない場合、またはバージョンが古い場合は、 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash を実行してインストールまたは更新するか、 インストール手順については references/cli-installation-guide.md を参照してください。

事前確認 1：AI-Mode を有効化 ［必須］他の設定やコマンドを実行する前に、aliyun configure ai-mode enable を実行して AI-Mode を有効化します。 これにより、後続の OpenAPI サービスがエージェントからのトラフィックを認識するための AI-Mode セッションが有効になります。

事前確認 2：AI-Mode でスキルの User-Agent を登録 ［必須］aliyun configure ai-mode set-user-agent AlibabaCloud-Agent-Skills/alibabacloud-dms-skill を実行し、このスキルの識別子を現在のセッションの AI-Mode User-Agent として登録します。 ai-mode enable の直後、プラグインの更新や DMS コマンドの実行前に、ただちに実行してください。

事前確認 3：Aliyun CLI プラグインの更新が必要です ［必須］aliyun configure set --auto-plugin-install true を実行して、プラグインの自動インストールを有効化します。 ［必須］aliyun plugin update を実行して、既存のプラグインを常に最新の状態にします。 プラグインマネージャー自体が正しい識別子を報告できるように、プラグインの更新は AI-Mode の有効化と User-Agent の登録の後に行う必要があります。

• Aliyun CLI 3.3.3 以降
• jq（JSON の解析用）：brew install jq
• aliyun configure を使用して認証情報を設定

事前確認 4：Alibaba Cloud の認証情報が必要です

セキュリティルール：

• 絶対に AK／SK の値を読み取ったり、エコーしたり、出力したりしないでください（例：echo $ALIBABA_CLOUD_ACCESS_KEY_ID は禁止です）
• 絶対に会話やコマンドラインで AK／SK を直接入力するようユーザーに求めないでください
• 絶対に認証情報の値を直接指定して aliyun configure set を使用しないでください
• 認証情報の状態確認には aliyun configure list のみを使用してください

aliyun configure list

有効なプロファイル（AK、STS、または OAuth ID）があるか、出力を確認してください。

有効なプロファイルがない場合は、ここで停止してください。

1. Alibaba Cloud Console から認証情報を取得します
2. このセッションの外部で認証情報を設定します（ターミナルで aliyun configure を実行するか、シェルプロファイルで環境変数を設定します）
3. aliyun configure list に有効なプロファイルが表示されたら、戻って再実行します

［必須］コマンドごとの CLI User-Agent — 事前確認 2 で登録する AI-Mode User-Agent に加えて、ステップ 4 のすべての aliyun CLI コマンドの実行時に、次のオプションを含める必要があります。 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-dms-skill コマンドごとのオプションと AI-Mode セッションレベルの設定は相互に補完するものです。AI-Mode セッションの有効期限が切れても、すべてのリクエストで識別子が送信されるよう、両方を設定する必要があります。

RAM 権限

［必須］RAM 権限の事前確認： 実行前に、現在のユーザーが次の RAM 権限を持っていることを確認してください。 権限の一覧については、references/ram-policies.md を参照してください。

パラメーターの確認

重要：パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、 ユーザーがカスタマイズ可能なすべてのパラメーター（データベースのキーワード、SQL 文、db-id など）を 必ずユーザーに確認してください。明示的な承認なしに、値を推測したりデフォルト値を使用したりしないでください。

パラメーター	必須／任意	説明	デフォルト
keyword	必須	データベース検索キーワード（1～128 文字、英数字）	-
db-id	必須	データベース ID（正の整数。検索で取得）	-
sql	必須	実行する SQL 文（1～10000 文字）	-
logic	任意	ロジックデータベースモードを使用するかどうか	false
force	任意	書き込み操作（INSERT/UPDATE/DELETE）を確認	false
dry-run	任意	実行せずに書き込み操作をプレビュー	false

基本的なワークフロー

タスク 1：対象データベースの検索

キーワードでデータベースを検索し、Database ID を取得します。

./scripts/search_database.sh <keyword> --json

例：

# Search for databases containing "mydb"
./scripts/search_database.sh mydb --json

出力には、database_id、schema_name、db_type、host、port などが含まれます。

タスク 2：SQL クエリの実行

前の手順で取得した Database ID を使用して SQL を実行します。

./scripts/execute_query.sh --db-id <database_id> --sql "<SQL_statement>"

書き込み操作の保護

書き込み操作（INSERT/UPDATE/DELETE）では、スクリプトが保護のための事前チェックを実行します。

パラメーター	説明
--force	書き込み操作の確認と実行に必須です
--dry-run	実行せずに書き込み操作をプレビューします

DDL 操作（DROP/TRUNCATE/ALTER/RENAME）は完全にブロックされます — DMS Console から実行してください。

例：

# Read operations (no confirmation needed)
./scripts/execute_query.sh --db-id 78059000 --sql "SHOW TABLES"
./scripts/execute_query.sh --db-id 78059000 --sql "SELECT * FROM users LIMIT 10" --json

# Write operations - preview first (recommended)
./scripts/execute_query.sh --db-id 78059000 --sql "INSERT INTO users (name) VALUES ('test')" --dry-run

# Write operations - execute with confirmation
./scripts/execute_query.sh --db-id 78059000 --sql "INSERT INTO users (name) VALUES ('test')" --force
./scripts/execute_query.sh --db-id 78059000 --sql "UPDATE users SET name='test' WHERE id=1" --force
./scripts/execute_query.sh --db-id 78059000 --sql "DELETE FROM users WHERE id=1" --force

# Logic database mode
./scripts/execute_query.sh --db-id 78059000 --sql "SELECT 1" --logic

完全な例

# 1. Search database (assuming searching for "order")
./scripts/search_database.sh order --json
# Example output:
# [{"DatabaseId": "78059000", "SchemaName": "order_db", ...}]

# 2. Execute query
./scripts/execute_query.sh --db-id 78059000 --sql "SELECT COUNT(*) FROM orders"

成功の確認

SQL の実行後、返された結果を確認します。

1. スクリプトの戻りコードが 0 であること
2. 出力にクエリ結果（列名と行データ）が含まれていること
3. エラーメッセージがないこと

# Verify query success
./scripts/execute_query.sh --db-id <db-id> --sql "SELECT 1" --json
# Expected output: [{"Success": true, "RowCount": 1, ...}]

クリーンアップ

このスキルは読み取り操作と書き込み操作を実行しますが、永続的なリソースは作成しないため、解放が必要なデータベースリソースはありません。

ただし、AI-Mode のライフサイクルでは、明示的な終了処理が必要です。

［必須］すべてのタスク完了後に AI-Mode を無効化してください このスキルのセッションですべての DMS コマンドの実行が完了したら（成功・失敗を問わず）、aliyun configure ai-mode disable を実行してください。 これにより AI-Mode セッションが終了し、登録された AlibabaCloud-Agent-Skills/alibabacloud-dms-skill User-Agent が後続の無関係な CLI の使用に漏れ出すのを防ぎます。

aliyun configure ai-mode disable

書き込み操作の安全性

操作の種類	動作
SELECT / SHOW / DESC	直接実行します
INSERT / UPDATE / DELETE	--force または --dry-run が必要です
DROP / TRUNCATE / ALTER / RENAME	ブロックされます — DMS Console を使用してください

利用可能なスクリプト

スクリプト	説明
scripts/search_database.sh	キーワードでデータベースを検索します
scripts/execute_query.sh	SQL クエリを実行します

注： スクリプトは aliyun configure で設定された aliyun-cli の認証情報を使用します。

ベストプラクティス

1. データベースを確認する — SQL を実行する前に、対象のデータベースを確認してください
2. --json パラメーターを使用する — 出力のプログラムによる処理が容易になります
3. 書き込み操作をプレビューする — INSERT/UPDATE/DELETE では、必ず最初に --dry-run を使用してください
4. 明示的に確認する — プレビューを確認した後にのみ --force を使用してください
5. DDL 操作を避ける — DROP/TRUNCATE/ALTER/RENAME はブロックされます。代わりに DMS Console を使用してください

参考リンク

ドキュメント	説明
references/cli-installation-guide.md	CLI のインストールガイド
references/ram-policies.md	RAM 権限ポリシー
references/related-apis.md	関連 API の一覧
references/acceptance-criteria.md	受け入れ基準