volcengine-db-supabase

Volcengine AIDAP Database Skill

AIDAP refers to Volcengine's AI 原生 BaaS 平台 Supabase 版 product. This skill manages its deployment-relevant database workspace capabilities and wires them into applications. The stable deploy-facing AIDAP engine choices are supabase and postgresql; resolve current CreateWorkspace EngineType / EngineVersion enums from references/tool-reference.md before creating a workspace. The control plane should use ve aidap directly whenever the action exists. For old-skill data-plane capabilities not exposed by ve, use scripts/supabase_dataplane.py only for Supabase-compatible workspace APIs.

Boundaries

• Supported by ve aidap: workspace, branch, compute, database, DB account, endpoint, API key, ACL, schema diff, start/stop, and deletion operations.
• AIDAP deploy engine choices are supabase and postgresql. Preserve the user's selected engine instead of treating Supabase as an RDS PostgreSQL provider.
• Real-name verification requires the volcengine-cli skill's GetVerifyInfo extension API capability; activate that skill first to use it.
• Not covered by current ve CLI: SQL execution, migration application, Supabase Edge Function management, Supabase Storage bucket management, and TypeScript type generation. Use scripts/supabase_dataplane.py for those old-skill capabilities.
• scripts/supabase_dataplane.py uses ve aidap only to resolve endpoint, default branch, and API keys. The data-plane calls use the Supabase service-role key in apikey and Authorization headers, not Volcengine AK/SK.
• Service activation is a console flow. If the service is not enabled, direct the user to https://console.volcengine.com/aidap.
• A successful ve aidap DescribeWorkspaces --body '{"Limit":1,"Offset":0}' response with Total: 0 or Workspaces: [] only means no workspaces exist; do not treat it as a service-disabled signal.
• AIDAP workspace creation requires the service-linked role ServiceRoleForAIDAP. If CreateWorkspace fails with RoleNotExist, follow the Service-Linked Role Repair procedure.

Initial Checks

1. Verify authentication with ve sts GetCallerIdentity.
2. Confirm AIDAP support in the installed CLI:

ve aidap --help

3. When creating a workspace or troubleshooting creation failure, activate the volcengine-cli skill and use its GetVerifyInfo extension API capability to check real-name verification. Personal verification is IsVerified=true with IdentityType="individual"; enterprise verification is IsVerified=true with IdentityType="enterprise".

Workspace Bootstrap

When the user has no workspace:

1. Ensure the AIDAP service is enabled. If not, ask the user to open:

https://console.volcengine.com/aidap

2. Ensure the service-linked role ServiceRoleForAIDAP exists. If CreateWorkspace fails with RoleNotExist, follow the Service-Linked Role Repair procedure below, then retry once.
3. Activate the volcengine-cli skill and use its GetVerifyInfo extension API capability to check enterprise verification.
4. Create the workspace with ve aidap CreateWorkspace, using the selected AIDAP engine and the current official enum mapping from references/tool-reference.md.

Minimal explicit-network body shape:

ve aidap CreateWorkspace --body '{
  "WorkspaceName": "demo-supabase",
  "EngineType": "<current EngineType for database_engine>",
  "EngineVersion": "<current EngineVersion for database_engine>",
  "BranchSettings": {
    "BranchName": "main",
    "DatabaseName": "postgres"
  },
  "ComputeSettings": {
    "AutoScalingLimitMinCU": 0.25,
    "AutoScalingLimitMaxCU": 1,
    "SuspendTimeoutSeconds": 300
  },
  "NetworkSettings": {
    "VpcId": "vpc-xxxx",
    "SubnetId": "subnet-xxxx",
    "SharedPublicNetwork": false
  },
  "WorkspaceSettings": {
    "DeletionProtection": "Disabled",
    "PublicConnection": "Disabled"
  },
  "WorkspaceTags": [
    {"Key": "publish-by", "Value": "deploy-skill"}
  ]
}'

Use a subnet in the same region as the workspace. For database_engine=postgresql, prefer an explicit VpcId and SubnetId from an existing Available VPC/subnet, such as the account's default VPC/subnet. Do not start with shared public/shared-network-only creation and then retry into explicit networking; the explicit network path is the verified low-friction path for PostgreSQL workspaces.

Do not invent or hard-code stale EngineType / EngineVersion values. Check the current API enum table in references/tool-reference.md, then refresh it from the official CreateWorkspace documentation or CLI/API evidence before live creation if the table may be stale.

After CreateWorkspace, verify readiness in dependency order:

1. Poll DescribeWorkspaceDetail until WorkspaceStatus=Running.
2. Poll DescribeDefaultBranch until the branch has BranchStatus=Ready; keep its BranchId.
3. Run DescribeComputes for that branch and keep the Primary database compute's ComputeId when ComputeStatus=Active.

For PostgreSQL workspaces, pass both BranchId and ComputeId to endpoint and database connection queries. A verified DescribeWorkspaceEndpoint call with only BranchId returned InvalidParameter: 参数ComputeId值无效.

Common Commands

Use ve aidap <Action> --help before writing command arguments; AIDAP is evolving and the CLI help is the local source of truth.

ve aidap DescribeWorkspaces --body '{"Limit":20,"Offset":0}'
ve aidap DescribeWorkspaceDetail --WorkspaceId ws-xxxx
ve aidap DescribeDefaultBranch --WorkspaceId ws-xxxx
ve aidap DescribeBranches --WorkspaceId ws-xxxx
ve aidap DescribeComputes --WorkspaceId ws-xxxx --BranchId br-xxxx
ve aidap CreateBranch --WorkspaceId ws-xxxx --BranchSettings.Name dev
ve aidap DescribeWorkspaceEndpoint --WorkspaceId ws-xxxx --BranchId br-xxxx --ComputeId cp-xxxx
ve aidap DescribeAPIKeys --WorkspaceId ws-xxxx --BranchId br-xxxx
ve aidap DescribeDBAccounts --WorkspaceId ws-xxxx --BranchId br-xxxx
ve aidap CreateDBAccount --WorkspaceId ws-xxxx --BranchId br-xxxx --AccountName app --AccountPassword '<secret>'
ve aidap CreateDatabase --WorkspaceId ws-xxxx --BranchId br-xxxx --DatabaseName appdb --DatabaseOwner app
ve aidap DescribeDBAccountConnection --WorkspaceId ws-xxxx --BranchId br-xxxx --ComputeId cp-xxxx --DatabaseName appdb --AccountName app
ve aidap DescribeSupabaseDeployEnvVars --WorkspaceId ws-xxxx --BranchId br-xxxx

Branch-scoped actions must pass the explicit BranchId; do not rely on an implicit default branch for endpoint, API key, DB account, database, connection, or deploy-env-var operations. DescribeWorkspaceEndpoint without BranchId has been observed to fail with InvalidParameter. For PostgreSQL endpoint and account connection queries, also pass the resolved primary ComputeId.

If CreateDBAccount or CreateDatabase reports PrimaryComputeNotFound, first compare DescribeDefaultBranch, DescribeBranches, and DescribeComputes for the same workspace and branch. If the branch is the default branch and DescribeComputes shows a Primary database compute in Active state, stop guessing branch IDs and record the case as an AIDAP control-plane inconsistency. Use the PostgreSQL fallback in references/deploy-provider.md only when a credential-bearing admin POSTGRES_URL is available and the user accepts using it.

Never print passwords, API keys, JWT secrets, service-role keys, or connection strings containing credentials in final answers. Write DATABASE_URL into a local env file with mode 600, then verify it with psql (select 1 or a table-list query). Summarize the host/port, resource IDs, verification result, and credential file path, not the full connection string.

Service-Linked Role Repair

If ve aidap CreateWorkspace fails with a message like:

RoleNotExist: Role 'trn:iam::<account-id>:role/ServiceRoleForAIDAP' does not exist

do not immediately classify it as a service-disabled condition. Repair the missing AIDAP service-linked role through IAM:

ve iam GetServiceLinkedRoleTemplate --ServiceName aidap
ve iam CreateServiceLinkedRole --ServiceName aidap
ve iam GetRole --RoleName ServiceRoleForAIDAP

After GetRole confirms RoleName=ServiceRoleForAIDAP and IsServiceLinkedRole=1, retry CreateWorkspace once. If the retry returns NotVerifiedAccount or 账号未实名认证, stop and ask the user to complete real-name verification at https://console.volcengine.com/user/authentication/detail/.

CreateAccessControlList currently has fragile CLI array parameter handling and has returned InvalidParameterFormat for common array forms. Do not tell the user that an ACL has been tightened until you verify the effective AllowHost from DescribeDBAccountConnection. If AllowHost still includes broad ranges such as 0.0.0.0/0 or ::/0, warn clearly and recommend tightening in the console or with a separately verified API call.

Data-Plane Commands

Use scripts/supabase_dataplane.py for old-skill capabilities that ve aidap does not expose. The script accepts either --workspace-id ws-... or --workspace-id br-...; when only a workspace is supplied it resolves the default branch with ve aidap DescribeDefaultBranch.

python3 scripts/supabase_dataplane.py execute-sql --workspace-id ws-xxxx --query "select * from pg_tables limit 5"
python3 scripts/supabase_dataplane.py apply-migration --workspace-id ws-xxxx --name create_todos --query-file ./migration.sql
python3 scripts/supabase_dataplane.py generate-typescript-types --workspace-id ws-xxxx --schemas public
python3 scripts/supabase_dataplane.py deploy-edge-function --workspace-id ws-xxxx --function-name hello --source-file ./index.ts
python3 scripts/supabase_dataplane.py create-storage-bucket --workspace-id ws-xxxx --bucket-name uploads --public

Set READ_ONLY=true to block data-plane write actions. If SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are already set, the script can skip ve aidap key lookup.

Deploy Integration

When volcengine-deploy needs an AIDAP database, it passes database_product=aidap plus database_engine=supabase|postgresql. Read references/deploy-provider.md for the wiring loop and environment variables.

References

• CLI action map and bootstrap notes: references/tool-reference.md
• Application integration patterns: references/app-integration-guide.md
• Schema and RLS guidance: references/schema-rls-guide.md
• SQL playbook: references/sql-playbook.md
• Edge Function development: references/edge-function-dev-guide.md
• Deployment database-provider wiring: references/deploy-provider.md