alibabacloud-analyticdb-postgresql-supabase-ops

ADBPG Supabase プロジェクト管理

AnalyticDB PostgreSQL（ADBPG）に基づく Supabase プロジェクトのライフサイクル全体を管理します。

アーキテクチャ：ADBPG (AnalyticDB PostgreSQL) + Supabase + VPC + VSwitch

対象範囲 — Alibaba Cloud ADBPG のみ（Supabase CLI は対象外）

• このスキルは、GPDB / aliyun gpdb API を通じてAlibaba Cloud 上にプロビジョニングされたプロジェクトを管理します。
• ここでの作成／一覧表示／一時停止／再開に、スタンドアロンの supabase CLI（supabase login、supabase projects list など）を使用しないでください。これは Supabase Cloud またはセルフホストスタックを対象としており、ADBPG が管理する Supabase インスタンスは対象外です。
• このスキルでのライフサイクル操作およびクエリ操作には、すべて --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops を指定した aliyun gpdb … を使用します。

ProjectId の形式（spb-）

• 作成／一覧／取得 API の ProjectId は、接頭辞 spb- とそれに続く英数字の文字列で構成されます（例：spb-2zen7c8752x12328）。--project-id にはこの値をそのまま指定してください。
• ユーザーが指定した文字列がどのインスタンスにも一致しない場合は、適切な --biz-region-id で list-supabase-projects を実行し、ProjectName または返された ProjectId で照合してください。

前提条件

事前確認：Aliyun CLI >= 3.3.3 が必要です aliyun version を実行して、バージョンが 3.3.3 以上であることを確認します。インストールされていない場合、またはバージョンが古い場合は、 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash を実行してインストール／更新するか、 インストール手順については references/cli-installation-guide.md を参照してください。 続いて、自動プラグインインストールを有効にするため、[必須] aliyun configure set --auto-plugin-install true を実行します。 続いて、ローカルマシンに既存のプラグインがあれば常に最新の状態にするため、[必須] aliyun plugin update を実行します。

[必須] CLI User-Agent — aliyun CLI を呼び出すすべてのコマンドに、次を含める必要があります。 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

Core Workflow の開始時（CLI を呼び出す前）に： [必須] AI-Mode を有効化 — Agent Skill の実行には AI-mode が必要です。 CLI を呼び出す前に、次のコマンドを実行してください。

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops"

[必須] あらゆる終了時に AI-Mode を無効化 — 理由を問わず、最終応答を返す前に必ず AI-mode を無効にしてください。これは、ワークフローの成功、ワークフローの失敗、エラー／例外、ユーザーによるキャンセル、セッション終了、または以降 CLI コマンドが実行されないその他すべての状況など、すべての終了経路に適用されます。 AI-mode は Agent Skill の呼び出し時にのみ使用し、スキルの実行停止後も有効のままにしてはなりません。

aliyun configure ai-mode disable

認証情報の確認

事前確認：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 に有効なプロファイルが表示された後、戻って再実行します

RAM の権限

操作を実行する前に、現在のアカウントに必要な権限があることを確認します。詳細は references/ram-policies.md を参照してください。

権限の事前確認：ram-permission-diagnose スキルを使用して現在のユーザー権限を確認し、references/ram-policies.md と照合してください。権限が不足している場合は、プロンプトを表示して中止します。

パラメーターの確認

重要：パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、 ユーザーがカスタマイズ可能なすべてのパラメーター（例：RegionId、ProjectId、インスタンス名、CIDR ブロック、 パスワード、VPC/VSwitch ID など）をユーザーに確認する必要があります。 create の場合、スキルは推奨デフォルト値（および任意の自動検出）を提示します。create-supabase-project を実行する前に、この計画全体を提示し、ユーザーの明示的な承認（または置き換える値の提示）を得る必要があります。

最終実行確認（読み取り専用と変更を伴う操作）

• 個別の最終「実行」ステップは不要 — 読み取り専用の情報取得の場合に限ります：aliyun gpdb list-supabase-projects、aliyun gpdb get-supabase-project、get-supabase-project-api-keys、get-supabase-project-dashboard-account、および aliyun vpc describe-vpcs、aliyun vpc describe-vswitches、aliyun gpdb describe-regions などの検出のみの呼び出し（list / describe と同じ分類で、リソースの状態は変更されません）。
• ユーザーによる最終確認［必須］ — CLI を実行する前に、変更を伴うすべての操作について確認を得る必要があります：作成、一時停止、再開、パスワードのリセット、セキュリティ IP の変更。実行する内容と主要なパラメーター（例：project-id、新しいパスワードのヒント（シークレットをログに記録せずに提示）、新しいホワイトリスト）を示し、明示的な承認を得てください。
• 作成後、get-supabase-project によるプロビジョニングのポーリングには、新たな確認は不要です。ユーザーはすでに作成を承認しており、ポーリングは検証のみを目的としています。

CreateSupabaseProject は、公式 API リファレンスで定義されています。CLI の完全なマッピング、VPC/VSwitch の検出、名前とパスワードのルールについては、references/create-supabase-project-parameters.mdを参照してください。

パラメーター	必須／任意	説明	デフォルト／推奨値
ProjectId	必須（作成以外）	API/list から取得するインスタンス ID（spb- + サフィックス）	—
BizRegionId	任意（作成）	リージョン ID（API の RegionId）	cn-beijing
ProjectName	必須（作成）	プロジェクト名	ユーザーの利用シナリオから決定。ユーザーは置き換え可能
ZoneId	必須（作成）	アベイラビリティゾーン ID	cn-beijing-i
VpcId	必須（作成）	VPC ID	ユーザー入力 または 検出結果（「プロジェクトの作成」を参照）
VSwitchId	必須（作成）	VSwitch ID（ZoneId と一致する必要があります）	ユーザー入力 または ゾーン内で AvailableIpAddressCount が最大のものを推奨
AccountPassword	必須（作成）／リセット	データベースのパスワード	ユーザー入力 または API のルールに沿って生成。ユーザーは置き換え可能
SecurityIPList	必須（作成）／変更	IP ホワイトリスト	127.0.0.1。ユーザーは IP／CIDR を指定可能
ProjectSpec	必須（作成）	インスタンス仕様	2C2G（スキルのデフォルト推奨値。ユーザーは例として 1C1G を選択可能）
StorageSize	任意（作成）	ストレージ（GB）	20（スキルのデフォルト推奨値）
DiskPerformanceLevel	任意（作成）	PL0 / PL1	PL0
PayType / UsedTime / Period	任意（作成）	課金	デフォルトは POSTPAY（後払い）。プリペイド／サブスクリプションの場合のみ --period / --used-time を設定
ClientToken	任意（作成）	冪等性	ユーザーが同じ作成操作を再試行しない限り省略

タイムアウトの設定

タイムアウトの設定

• CLI のデフォルトの読み取りタイムアウトは、HTTP 読み取りごとに通常 約 60 秒です。通常、create-supabase-project には十分です。作成処理は非同期であり、API はリクエストを受け付けるとすぐに ProjectId を返し、インスタンスの準備が完了するまで待機することはありません。
• バックグラウンドでのプロビジョニングが完了するまでには、通常 3～5 分かかります。これは create HTTP 応答にかかる時間ではありません。このフェーズの完了を待つには、成功の確認（get-supabase-project をポーリングし、Status が running になるまで待機）を行います。
• 作成成功の基準：create-supabase-project が ProjectId を返した後も、get-supabase-project が Status = running（API では小文字）を報告するまでは、インスタンスの準備は完了していません。この状態は、プロビジョニングが成功し、プロジェクトを使用できることを意味します。
• 実際にコマンドで読み取りタイムアウトが発生した場合は、その呼び出しの --read-timeout を延長してください（例：--read-timeout 120）。

基本的なワークフロー

すべてのコマンドは aliyun gpdb <command> の形式を使用し、--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops を含める必要があります。

最終実行の確認（読み取り専用と変更を伴う操作） に従い、読み取り専用の list / get / describe は最終実行の確認なしで実行できます。create、pause、resume、パスワードのリセット、IP の変更は、実行前にユーザーの明示的な最終確認が必要です。

プロジェクト一覧の取得

aliyun gpdb list-supabase-projects \
  --biz-region-id cn-beijing \
  --max-results 20 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• リスク：低 | 読み取り専用 — 最終実行の確認は不要

プロジェクト詳細の取得

aliyun gpdb get-supabase-project \
  --project-id spb-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• リスク：低 | 読み取り専用 — 最終実行の確認は不要

API キーの取得

aliyun gpdb get-supabase-project-api-keys \
  --project-id spb-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• リスク：低 | 読み取り専用 — 最終実行の確認は不要
• ポリシー：この公式 Alibaba Cloud API（RAM／アカウントアクセスを使用）を通じてキーを読み取るリクエストに応えることは、無関係なコードベースからシークレットをスクレイピングすることとは異なります。リポジトリやサードパーティーのシステムからの明らかな持ち出しである場合にのみ拒否してください。それ以外の場合は get-supabase-project-api-keys を実行し、キーは最小限の形で返し（シークレット全体をログに記録しない）、露出した場合はローテーションするようユーザーに注意してください。

ダッシュボードアカウントの取得

aliyun gpdb get-supabase-project-dashboard-account \
  --project-id spb-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• リスク：低 | 読み取り専用 — 最終実行の確認は不要

プロジェクトの作成

自動ワークフロー — ユーザーが「帮我在北京 i 创建 ADBPG Supabase 项目」のような意図を示した場合は、次の手順を実行します。

ステップ 1：必要な情報をすべて自動検出する（この時点ではユーザー入力は不要）

1. リージョンとゾーン — ユーザー指定の値、またはデフォルト値（cn-beijing、cn-beijing-i）を使用します。
2. ProjectName — scripts/generate-project-name.sh を実行して、候補を 1～3 件取得します（タイムスタンプベース）。
3. パスワード — scripts/generate-password.py を実行して、要件を満たすパスワードを生成します。
4. VPC／VSwitch の検出 — scripts/discover-vswitch.sh --biz-region-id <region> --zone-id <zone> を実行して、利用可能な IP アドレスが最も多い VSwitch を取得します。
5. SecurityIPList — デフォルトは 127.0.0.1 です。
6. 任意のフラグ — デフォルト値として 2C2G、20 GB、POSTPAY、PL0 を使用します。
7. ClientToken — UUID を 1 つ生成します。

ステップ 2：作成プランを提示する（確認は 1 回）

パラメーターの表全体をオプションとともにユーザーに表示します。

=== Create Supabase Project Plan ===
Project Name:   <generated-or-user-confirmed>
Region:         <biz-region-id>
Zone:           <zone-id>
VPC:            <vpc-id from discovery>
VSwitch:        <vswitch-id from discovery> (Available IPs: <count>)
Instance Spec:  2C2G
Storage:        20 GB
Pay Type:       POSTPAY
Security IP:    127.0.0.1
Password:       <generated, shown once or masked>
=================================

Select an option:
1. Confirm and create (default)
2. Modify parameters
3. Cancel

Press Enter for [1], or type option number:

ステップ 3：確認後に実行

ユーザーが「1」を選択するか、Enter キーを押して確認した場合は、次を実行します。

aliyun gpdb create-supabase-project \
  --biz-region-id <BizRegionId> \
  --zone-id <ZoneId> \
  --project-name <ProjectName> \
  --account-password ‘<Password>’ \
  --security-ip-list "127.0.0.1" \
  --vpc-id <VpcId> \
  --vswitch-id <VSwitchId> \
  --project-spec 2C2G \
  --storage-size 20 \
  --disk-performance-level PL0 \
  --pay-type POSTPAY \
  --client-token "<ClientToken>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

その後、以下で説明する 成功の確認（ポーリング）に進みます。

非同期作成 — HTTP の再試行（ProjectId を取得する前）

• 目的：一時的な CLI／ネットワーク／API エラーを吸収し、別のリソースを重複して作成しないようにします。
• このセッションで対象のプロジェクトを作成する際は、すべての作成試行で同じ --client-token を再利用します。
• 作成を再試行するのは、応答に ProjectId がなく、エラーが一時的なものと思われる場合に限ります（合計最大 3 回。初回を含む）。例：スロットリング、接続リセット、読み取りタイムアウト、ServiceUnavailable。試行間の待機時間：5s → 15s → 45s。
• 業務上のエラー（例：VSwitchIp.NotEnough、無効なパラメーター）では、やみくもに作成を再試行しないでください。停止してユーザーに説明し、一緒に修正します。
• いずれかの試行で ProjectId が返された場合は、作成の呼び出しを停止し、プロビジョニングのポーリング（成功の確認）に切り替えます。
• 作成がタイムアウトしてもサーバー側では成功している可能性がある場合は、同じトークン／名前で再度作成する前に、名前／リージョンで get-supabase-project をポーリングします（例：ProjectName でフィルターした list-supabase-projects）。

# CLIENT_TOKEN: generate once (e.g. uuidgen) before first attempt; reuse on safe create retries.
aliyun gpdb create-supabase-project \
  --biz-region-id cn-beijing \
  --zone-id cn-beijing-i \
  --project-name my_supabase \
  --account-password '<user-or-generated>' \
  --security-ip-list "127.0.0.1" \
  --vpc-id vpc-xxxxx \
  --vswitch-id vsw-xxxxx \
  --project-spec 2C2G \
  --storage-size 20 \
  --disk-performance-level PL0 \
  --pay-type POSTPAY \
  --client-token "$CLIENT_TOKEN" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• リスク：高 | ユーザーによる最終確認 — 実行前にすべてのパラメーター計画を承認
• パスワード：大文字、小文字、数字、記号（!@#$%^&*()_+-=）のうち少なくとも 3 種類を含める必要があります。長さは 8～32 文字です（API の仕様）。
• プロジェクト名：英字／数字／ハイフン／アンダースコアを使用できます。英字または _ で始める必要があります。長さは 1～128 文字です。

プロジェクトの一時停止

aliyun gpdb pause-supabase-project \
  --project-id spb-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• リスク：中 | 実行前にユーザーによる最終確認が必要です
• 一時停止後はサービスを利用できませんが、データは保持されます

プロジェクトの再開

aliyun gpdb resume-supabase-project \
  --project-id spb-xxxxx \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• リスク：中 | 実行前にユーザーによる最終確認が必要です（変更を伴います）

データベースのパスワードをリセット

aliyun gpdb reset-supabase-project-password \
  --project-id spb-xxxxx \
  --account-password 'NewPass456!' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• リスク：中 | 実行前にユーザーによる最終確認が必要です
• 古いパスワードを使用している既存の接続は切断されます

セキュリティ IP の変更

aliyun gpdb modify-supabase-project-security-ips \
  --project-id spb-xxxxx \
  --security-ip-list "10.0.0.1,10.0.0.2/24" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops

• リスク：中 | 実行前にユーザーによる最終確認が必要です
• 複数の IP はコンマで区切ります。CIDR 形式をサポートしています

成功の確認

まず以下の手順を使用してください。拡張テーブルとエッジケースについては、references/verification-method.md を参照してください。

作成後（create-supabase-project）

1. 作成応答から ProjectId（形式は spb- + suffix）を取得します。作成呼び出しは、プロビジョニングの完了時ではなく、リクエストが受け付けられた時点で返されます。作成に失敗した場合やタイムアウトした場合は、別の作成を試みる前に、プロジェクトがすでに存在するかを一覧表示または取得**して確認します（プロジェクトの作成に従って作成を再試行する場合は、同じ --client-token を使用します）。

2. running または終端失敗状態になるまで、プロビジョニングをポーリングします。非同期処理は通常 3～5 分で完了しますが、負荷が高い場合はさらに時間がかかることがあります。2 段階で待機します。

   • 段階 A — 基本：30 秒ごとに get-supabase-project を呼び出し、最大 20 回（約 10 分）試行します。
   • 段階 B — 延長（任意）：Status がまだ終端ではないプロビジョニング状態（例：creating／pending。正確な文字列は API によって異なります）の場合は、ユーザーに伝えたうえで、諦める前に最大 10 回（約 5 分）追加で試行します。

3. 各ポーリングの再試行（一時的なエラー）：予定された各ポーリングで、ネットワーク／読み取りタイムアウトまたはスロットリングにより get が失敗した場合は、同じ get を 5 秒間隔で最大 3 回再試行してから、外側のループを続行します（ポーリングサイクルは 1 回として数えます）。

4. Status を解釈します：

   • running → 作成／プロビジョニング成功です。インスタンスの準備ができていることをユーザーに報告します。
   • 終端失敗（API が明示的な失敗／キャンセル状態を返した場合）→ ポーリングを停止し、エラーコード／メッセージを報告します。成功とみなさないでください。
   • 空／不明／進行中 → 段階 A／B の上限内でポーリングを続けます。

PROJECT_ID="spb-xxxxx"
STATUS=""
MAX_PRIMARY=20
SLEEP=30
for attempt in $(seq 1 "$MAX_PRIMARY"); do
  RAW=""
  for inner in 1 2 3; do
    RAW=$(aliyun gpdb get-supabase-project \
      --project-id "$PROJECT_ID" \
      --read-timeout 90 \
      --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops \
      2>/dev/null) && break
    sleep 5
  done
  STATUS=$(echo "$RAW" | jq -r '.Status // empty')
  [ "$STATUS" = "running" ] && break
  sleep "$SLEEP"
done
# Optional: extend with user consent +10 polls if still provisioning
[ "$STATUS" = "running" ] || exit 1

jq が利用できない場合は、毎回 get の出力を確認して Status を調べます。同じ再試行ルールと段階のルールが適用されます。

その他の操作後

操作	確認方法	成功のヒント
一覧表示	list-supabase-projects	JSON に Projects と RequestId が含まれている
取得／API キー／ダッシュボード	対応する get-* コマンド	JSON に想定されるフィールドがあり、エラーコードがない
一時停止／再開	get-supabase-project	API に応じて Status が一時停止中／実行中と一致している
パスワードのリセット／IP の変更	get-supabase-project	該当する場合、ホワイトリストまたは成功レスポンスを確認します。パスワードの変更は再接続でも検証します（リファレンスドキュメントを参照）。

ベストプラクティス

1. 読み取り専用の一覧表示／取得／説明（最終実行確認を参照）は最終実行のプロンプトなしで実行できますが、明示的な最終ユーザー確認なしに作成／一時停止／再開／パスワードのリセット／IP の変更を決して実行しないでください。
2. ユーザーが VPC/VSwitch ID を持っていない場合は、作成前に vpc describe-vswitches（必要に応じて vpc describe-vpcs）で確認します。
3. プロジェクトを一時停止する前に、必ず警告してください（サービスが利用できなくなります）。
4. セキュリティリスクがあるため、ホワイトリストを 0.0.0.0/0 に設定することを推奨しないでください。
5. ProjectId は常に spb-… です。ユーザーの ID が間違っているか不明な場合は、list-supabase-projects を使用して名前または ID から特定します。
6. この製品で supabase CLI を aliyun gpdb の代わりに使用しないでください。
7. プロジェクトを一時停止すると、データを保持したままコストを削減できます。
8. すべてのコマンドに --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops を含める必要があります。
9. 作成後は、必ずプロビジョニングのポーリングを実行するか、処理が最終的に失敗したことを確認してください。「作成から ProjectId が返された」ことを「インスタンスの準備が完了した」ことと見なさないでください。

リファレンスドキュメント

ドキュメント	説明
references/cli-installation-guide.md	CLI のインストールガイド
references/ram-policies.md	RAM の権限要件
references/related-apis.md	関連 API の一覧
references/verification-method.md	操作の検証方法
references/acceptance-criteria.md	受け入れ基準
references/create-supabase-project-parameters.md	作成 API のパラメーター、デフォルト値、VPC/VSwitch の確認方法