| name | volcengine-db-supabase |
| description | Manage Volcengine AI Native BaaS for Supabase (AIDAP) database workspaces as a deployment database provider. Use when the user asks for Volcengine Supabase, AIDAP PostgreSQL, AIDAP database workspace setup, branch management, API keys, endpoint or database connection information, service activation, enterprise real-name verification, SQL execution, migrations, Edge Functions, Storage buckets, TypeScript type generation, or using AIDAP as the database for a Volcengine deployment. Prefer `ve aidap` for control-plane operations; use bundled scripts only for Supabase data-plane APIs missing from the current `ve` CLI. |
| license | MIT |
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
- Verify authentication with
ve sts GetCallerIdentity.
- Confirm AIDAP support in the installed CLI:
ve aidap --help
- 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:
- Ensure the AIDAP service is enabled. If not, ask the user to open:
https://console.volcengine.com/aidap
- Ensure the service-linked role
ServiceRoleForAIDAP exists. If CreateWorkspace fails with RoleNotExist, follow the Service-Linked Role Repair procedure below, then retry once.
- Activate the
volcengine-cli skill and use its GetVerifyInfo extension API capability to check enterprise verification.
- 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:
- Poll
DescribeWorkspaceDetail until WorkspaceStatus=Running.
- Poll
DescribeDefaultBranch until the branch has BranchStatus=Ready; keep its BranchId.
- 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
