Alibabacloud Analyticdb Postgresql Supabase Ops
by @sdk-team
Manage the full lifecycle of ADBPG Supabase projects. Use for listing/querying projects, create, pause/resume, reset password, API Keys, and security IP mana...
clawhub install alibabacloud-analyticdb-postgresql-supabase-ops๐ About This Skill
name: alibabacloud-analyticdb-postgresql-supabase-ops description: | Manage the full lifecycle of ADBPG Supabase projects. Use for listing/querying projects, create, pause/resume, reset password, API Keys, and security IP management. Triggers: "Supabase", "supabase project", "spb-xxx", "ADBPG Supabase"
ADBPG Supabase Project Management
Manage the full lifecycle of Supabase projects based on AnalyticDB PostgreSQL (ADBPG).
Architecture: ADBPG (AnalyticDB PostgreSQL) + Supabase + VPC + VSwitch
Scope โ Alibaba Cloud ADBPG only (not Supabase CLI)
aliyun gpdb APIs.supabase CLI (supabase login, supabase projects list, etc.) for create/list/pause/resume here โ that targets Supabase Cloud or self-hosted stacks, not ADBPG-managed Supabase instances.aliyun gpdb โฆ with --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops.ProjectId format (spb-)
ProjectId from create/list/get APIs uses the prefix spb- plus an alphanumeric suffix (e.g. spb-2zen7c8752x12328). Use this exact value in --project-id.list-supabase-projects in the right --biz-region-id and match ProjectName or the returned ProjectId.Prerequisites
> Pre-check: Aliyun CLI >= 3.3.3 required
> Run aliyun version to verify >= 3.3.3. If not installed or version too low,
> run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to install/update,
> or see references/cli-installation-guide.md for installation instructions.
> Then [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.
> Then [MUST] run aliyun plugin update to ensure that any existing plugins on your local machine are always up-to-date.
[MUST] CLI User-Agent โ Every aliyun CLI command invocation must include:
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops
At the start of the Core Workflow (before any CLI invocation): [MUST] Enable AI-Mode โ AI-mode is required for Agent Skill execution. Run the following commands before any CLI invocation:
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops"
[MUST] Disable AI-Mode at EVERY exit point โ Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed.
AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.
aliyun configure ai-mode disable
Credential Verification
> Pre-check: Alibaba Cloud Credentials Required
>
> Security Rules:
> - NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)
> - NEVER ask the user to input AK/SK directly in the conversation or command line
> - NEVER use aliyun configure set with literal credential values
> - ONLY use aliyun configure list to check credential status
>
>
> aliyun configure list
>
> Check the output for a valid profile (AK, STS, or OAuth identity).
>
> If no valid profile exists, STOP here.
> 1. Obtain credentials from Alibaba Cloud Console
> 2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)
> 3. Return and re-run after aliyun configure list shows a valid profileRAM Permissions
Ensure the current account has the required permissions before executing operations. See references/ram-policies.md for details.
Permission Pre-check: Use ram-permission-diagnose skill to check current user permissions, compare against references/ram-policies.md, and abort with prompt if any permission is missing.
Parameter Confirmation
> IMPORTANT: Parameter Confirmation โ Before executing any command or API call,
> ALL user-customizable parameters (e.g., RegionId, ProjectId, instance names, CIDR blocks,
> passwords, VPC/VSwitch IDs, etc.) MUST be confirmed with the user.
> For create, the skill supplies recommended defaults (and optional auto-discovery). You must present that full plan and obtain explicit user approval (or replaced values) before running create-supabase-project.
Final execution confirmation (read-only vs mutating)
aliyun gpdb list-supabase-projects, aliyun gpdb get-supabase-project, get-supabase-project-api-keys, get-supabase-project-dashboard-account, and discovery-only calls such as aliyun vpc describe-vpcs, aliyun vpc describe-vswitches, aliyun gpdb describe-regions (same class as list / describe: no resource state change).project-id, new password hint without logging secret, new whitelist). Obtain explicit approval.get-supabase-project does not need a new confirmation โ the user already approved create; polling is verification only.CreateSupabaseProject is defined in the official API reference. Full CLI mapping, VPC/VSwitch discovery, name/password rules: references/create-supabase-project-parameters.md.
| Parameter | Required/Optional | Description | Default / recommendation |
|-----------|-------------------|-------------|---------------------------|
| ProjectId | Required (non-create) | Instance ID from API/list (spb- + suffix) | โ |
| BizRegionId | Optional (create) | Region ID (RegionId in API) | cn-beijing |
| ProjectName | Required (create) | Project name | Derive from user scenario; user may replace |
| ZoneId | Required (create) | Availability zone ID | cn-beijing-i |
| VpcId | Required (create) | VPC ID | User input or from discovery (see Create Project) |
| VSwitchId | Required (create) | VSwitch ID (must match ZoneId) | User input or recommend max AvailableIpAddressCount in zone |
| AccountPassword | Required (create) / reset | Database password | User input or generate per API rules; user may replace |
| SecurityIPList | Required (create) / modify | IP whitelist | 127.0.0.1; user may supply IPs/CIDRs |
| ProjectSpec | Required (create) | Instance spec | 2C2G (skill default recommendation; user may choose e.g. 1C1G) |
| StorageSize | Optional (create) | Storage (GB) | 20 (skill default recommendation) |
| DiskPerformanceLevel | Optional (create) | PL0 / PL1 | PL0 |
| PayType / UsedTime / Period | Optional (create) | Billing | POSTPAY (ๅไป่ดน) by default; set --period / --used-time only for prepaid/subscription |
| ClientToken | Optional (create) | Idempotency | Omit unless user retries same create |
Timeout Configuration
> Timeout Settings
> - Default CLI read timeout is often ~60 seconds per HTTP read โ usually enough for create-supabase-project, because creation is asynchronous: the API accepts the request and returns ProjectId quickly; it does not block until the instance is ready.
> - 3โ5 minutes is the typical time for background provisioning to finish โ not the duration of the create HTTP response. Use Success Verification (poll get-supabase-project until Status is running) to wait for that phase.
> - Create success criterion: after create-supabase-project returns ProjectId, the instance is not ready until get-supabase-project reports Status = running (API uses lowercase) โ that state means provisioning succeeded and the project is usable.
> - If any command hits read timeouts in practice, raise --read-timeout for that call (e.g. --read-timeout 120).
Core Workflow
All commands use aliyun gpdb format, must include --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops.
Per Final execution confirmation: read-only list / get / describe may run without a final execute prompt; create, pause, resume, reset password, modify IPs require explicit final user confirmation before invocation.
List Projects
aliyun gpdb list-supabase-projects \
--biz-region-id cn-beijing \
--max-results 20 \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops
Get Project Details
aliyun gpdb get-supabase-project \
--project-id spb-xxxxx \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops
Get API Keys
aliyun gpdb get-supabase-project-api-keys \
--project-id spb-xxxxx \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops
get-supabase-project-api-keys, return keys minimally (no logging full secrets), and remind the user to rotate if exposed.Get Dashboard Account
aliyun gpdb get-supabase-project-dashboard-account \
--project-id spb-xxxxx \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops
Create Project
Automated workflow โ When user provides intent like "ๅธฎๆๅจๅไบฌ i ๅๅปบ ADBPG Supabase ้กน็ฎ", run these steps:
#### Step 1: Auto-discover all information (no user input needed yet)
1. Region + Zone โ Use user-specified values or defaults (cn-beijing, cn-beijing-i).
2. ProjectName โ Run scripts/generate-project-name.sh to get 1-3 candidates (timestamp-based).
3. Password โ Run scripts/generate-password.py to generate a compliant password.
4. VPC/VSwitch discovery โ Run scripts/discover-vswitch.sh --biz-region-id to get the VSwitch with the most available IPs.
5. SecurityIPList โ Default 127.0.0.1.
6. Optional flags โ Use defaults: 2C2G, 20 GB, POSTPAY, PL0.
7. ClientToken โ Generate one UUID.
#### Step 2: Present creation plan (single confirmation)
Display the full parameter table to the user with options:
=== Create Supabase Project Plan ===
Project Name:
Region:
Zone:
VPC:
VSwitch: (Available IPs: )
Instance Spec: 2C2G
Storage: 20 GB
Pay Type: POSTPAY
Security IP: 127.0.0.1
Password:
=================================Select an option:
1. Confirm and create (default)
2. Modify parameters
3. Cancel
Press Enter for [1], or type option number:
#### Step 3: Execute after confirmation
If user selects "1" or presses Enter (confirm), run:
aliyun gpdb create-supabase-project \
--biz-region-id \
--zone-id \
--project-name \
--account-password โโ \
--security-ip-list "127.0.0.1" \
--vpc-id \
--vswitch-id \
--project-spec 2C2G \
--storage-size 20 \
--disk-performance-level PL0 \
--pay-type POSTPAY \
--client-token "" \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops
Then proceed to Success Verification (polling) as described below.
Async create โ HTTP retries (before you have ProjectId)
--client-token on every create attempt in this session for this intended project.ProjectId and the error looks transient: e.g. throttling, connection reset, read timeout, ServiceUnavailable. Backoff: 5s โ 15s โ 45s between attempts.VSwitchIp.NotEnough, invalid parameter) โ stop, explain, fix with the user.ProjectId โ stop calling create; switch to provisioning poll (Success Verification).get-supabase-project by name/region (e.g. list-supabase-projects filtered by ProjectName) before issuing another create with the same token/name.# 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 '' \
--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
!@#$%^&*()_+-=; length 8โ32 (per API)_; length 1โ128Pause Project
aliyun gpdb pause-supabase-project \
--project-id spb-xxxxx \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops
Resume Project
aliyun gpdb resume-supabase-project \
--project-id spb-xxxxx \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops
Reset Database Password
aliyun gpdb reset-supabase-project-password \
--project-id spb-xxxxx \
--account-password 'NewPass456!' \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops
Modify Security IPs
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
Success Verification
Use the steps below first; extended tables and edge cases are in references/verification-method.md.
After create (create-supabase-project)
1. Capture ProjectId from the create response (format spb- + suffix). The create call returns after the request is accepted, not when provisioning finishes. If create fails or times out, list or get to see if the project already exists before another create (same --client-token if retrying create per Create Project).
2. Provisioning poll until running or terminal failure โ async work often finishes in 3โ5 minutes but can run longer under load. Use a two-tier wait:
- Tier A โ primary: every 30 seconds, call get-supabase-project, up to 20 attempts (~10 minutes).
- Tier B โ extension (optional): if Status is still a non-terminal provisioning state (e.g. creating / pending โ exact strings depend on API), inform the user and add up to 10 more attempts (~5 minutes) before giving up.
3. Per-poll retry (transient): For each scheduled poll, if get fails with network/read timeout or throttling, retry the same get up to 3 times with 5 seconds between tries, then continue the outer loop (still count as one poll cycle).
4. Interpret Status:
- running โ create / provisioning succeeded; instance is ready โ report success to the user.
- Terminal failure (if API returns explicit failure/cancelled states) โ stop polling; report error code/message; do not assume success.
- Empty / unknown / in-progress โ keep polling within Tier A/B limits.
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
If jq is unavailable, inspect the get output for Status each time; same retry and tier rules apply.
After other operations
| Operation | Verify with | Success hint |
|-----------|-------------|--------------|
| List | list-supabase-projects | Projects present in JSON, RequestId present |
| Get / API keys / dashboard | matching get-* command | Expected fields in JSON, no error code |
| Pause / resume | get-supabase-project | Status matches paused / running per API |
| Reset password / modify IPs | get-supabase-project | Whitelist or success response as applicable; password change is also validated by reconnecting (see reference doc) |
Best Practices
1. Read-only list/get/describe (see Final execution confirmation) may run without a final execute prompt; never run create/pause/resume/reset-password/modify-IPs without explicit final user confirmation
2. If users lack VPC/VSwitch IDs, discover with vpc describe-vswitches (and optionally vpc describe-vpcs) before create
3. Must issue warning before pausing projects (service will become unavailable)
4. Do not recommend setting whitelist to 0.0.0.0/0 due to security risks
5. ProjectId is always spb-โฆ โ if the userโs id is wrong or unknown, use list-supabase-projects to resolve by name or id
6. Never substitute supabase CLI for aliyun gpdb on this product
7. Pausing projects saves costs while data is preserved
8. All commands must include --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops
9. After create, always run provisioning poll (or confirm terminal failure) โ do not treat โcreate returned ProjectIdโ as โinstance readyโ
Reference Documents
| Document | Description | |----------|-------------| | references/cli-installation-guide.md | CLI Installation Guide | | references/ram-policies.md | RAM Permission Requirements | | references/related-apis.md | Related API List | | references/verification-method.md | Operation Verification Methods | | references/acceptance-criteria.md | Acceptance Criteria | | references/create-supabase-project-parameters.md | Create API parameters, defaults, VPC/VSwitch discovery |
โ๏ธ Configuration
> Pre-check: Aliyun CLI >= 3.3.3 required
> Run aliyun version to verify >= 3.3.3. If not installed or version too low,
> run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to install/update,
> or see references/cli-installation-guide.md for installation instructions.
> Then [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.
> Then [MUST] run aliyun plugin update to ensure that any existing plugins on your local machine are always up-to-date.
[MUST] CLI User-Agent โ Every aliyun CLI command invocation must include:
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops
At the start of the Core Workflow (before any CLI invocation): [MUST] Enable AI-Mode โ AI-mode is required for Agent Skill execution. Run the following commands before any CLI invocation:
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops"
[MUST] Disable AI-Mode at EVERY exit point โ Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed.
AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.
aliyun configure ai-mode disable
๐ Tips & Best Practices
1. Read-only list/get/describe (see Final execution confirmation) may run without a final execute prompt; never run create/pause/resume/reset-password/modify-IPs without explicit final user confirmation
2. If users lack VPC/VSwitch IDs, discover with vpc describe-vswitches (and optionally vpc describe-vpcs) before create
3. Must issue warning before pausing projects (service will become unavailable)
4. Do not recommend setting whitelist to 0.0.0.0/0 due to security risks
5. ProjectId is always spb-โฆ โ if the userโs id is wrong or unknown, use list-supabase-projects to resolve by name or id
6. Never substitute supabase CLI for aliyun gpdb on this product
7. Pausing projects saves costs while data is preserved
8. All commands must include --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-supabase-ops
9. After create, always run provisioning poll (or confirm terminal failure) โ do not treat โcreate returned ProjectIdโ as โinstance readyโ