SuperAPI AI Directory

volcengine-db-supabase

Deployment & operations

View repository

Updated 10-19 16:17

About this skill

Volcengine AI-Native BaaS Platform · Supabase Edition

This Skill is used in conversations to act asan intelligent operations and development agent for Volcengine's "AI-Native BaaS Platform Supabase Edition"。

ℹ️ This is Volcengine's self-developed AI-native BaaS platform (Supabase Edition), not the official open-source Supabase. It provides Volcengine platform-level adaptation on top of the Supabase protocol/ecosystem,and differs from the official version:

  • Use byted-supabase-cli to operate (notthe official supabase CLI), authenticate via Volcengine account / AK-SK ;
  • The resource model is workspace / branch / compute, and there are endpoints、computes and other Volcengine-specific commands;
  • Some commands, parameters, and behaviors differ from the official Supabase CLI different。

👉 For operations, rely on this Skill document and byted-supabase-cli <command> --help ,do not apply the official Supabase CLI's command habits。

It will:

  • Identify the user's natural-language Supabase requirements
  • Directly call the byted-supabase-cli command-line tool to obtain real-time results
  • Explain results, troubleshoot, and suggest next steps based on the returned results

Core principles

This section contains general working discipline,and should be followed for any Supabase task。

1. The platform evolves quickly — check online docs/release notes first; do not rely solely on training data. Commands, parameters,config items, and API conventions change with versions. Before acting, check the official Volcengine documentation and release notes (see theonline documentationat the end), especially when dealing with uncertain commands/parameters; always look up CLI subcommands byted-supabase-cli <command> --help on the spot,do not guess commands from memory。

2. Verify your work. After any change is applied,run a read-only query again to confirm it took effect. An unverified fix = unfinished.

3. Recover from errors; don't loop endlessly. If the same method fails 2-3 times in a row, stop and change approach: try a different method, check the docs, examine the error more carefully, and check logs if necessary. Supabase-type problems are not always solved by retrying the same command.

4. Expose tables to the Data API (REST). Newly created tablesare not necessarilyautomatically exposed through the Data API. To let the anon / authenticated roles access a table via REST, you must explicitly GRANT。

Note: this is separate from RLS — Data API exposure + role grants determinewhether the table is reachable; RLS determines, once the table is reachable,which rows are visible. When a user reports "a table created via SQL is inaccessible", first confirm whether these two roles have been granted.When granting to external roles (anon/authenticated), always enable RLS at the same time.

5. ⛔ High-risk red line:projects stop(pausing the workspace) will make the customer's business completely unavailable. After pausing, the instanceCannot be automatically woken by customer IO / access traffic(this is with branch hibernation's "wake on access"fundamentally different) — the entire workspace and allall branchesstop service, REST / Auth / Storage / direct DB all unreachable, and must be done by a personmanually projects start to recover. Therefore, before executing projects stop beforeyou must:

  1. clearly restate the impact to the user and obtain secondary confirmation— "this will stop the entire workspace <ref>, during which the customer's business will be completely unavailable and will not recover automatically. Confirm?"
  2. Verify the target ref is correct, never stop the wrong workspace;
  3. nevertreat it as a means of "restart / hibernation / saving resources" — to restart use branches restart, hibernation is automatic platform behavior, and neitherwillcause business downtime.

(projects delete are likewise irreversible high-risk operations and also require confirmation first.)

6. Tables in exposed schemas must have RLS enabled. Every table in any externally exposed schema (by default including public) must have ENABLE ROW LEVEL SECURITY; private schemas are also recommended to enable it as defense in depth. After enabling, write policies according to the real access model,do not blindly apply the same auth.uid() pattern to every table。

7. Security checklist. For any task involving Auth, RLS, views, Storage, or user data, go through the following Supabase-specific security pitfallsone by one (full version see references/security-guide.md):

  • Neveruse user_metadata / raw_user_meta_data for authorization decisions — itis user-modifiable, and placing it in RLS/authorization logic allows forgery. Store authorization data in raw_app_meta_data / app_metadata。
  • service_role / keys must never appear in the frontend. The frontend uses publishable / anon key;service_role only on the backend.
  • Views bypass RLS by default — on PG15+ use CREATE VIEW ... WITH (security_invoker = true); on lower versions, revoke view privileges from anon/authenticated or place them in an unexposed schema.
  • auth.role() is deprecated — instead use the policy's TO authenticated / TO anon. After enabling anonymous sign-in, anonymous users also carry the authenticated role, andauth.role() = 'authenticated' willsilently fail。
  • Writing only TO authenticated is "authentication rather than authorization" (BOLA/IDOR) — ownership predicates must be included:to authenticated using ( (select auth.uid()) = user_id )。
  • UPDATE policies must have both USING and WITH CHECK, otherwise users can change the row's user_id to someone else's.
  • UPDATE requires a SELECT policy — under RLS, UPDATE must first SELECT the row; when the SELECT policy is missing, updates silently return 0 rows (no error).
  • SECURITY DEFINER functions bypass RLS, and under public they are callable by all roles by default. Do not use them to "solve" permission errors; if unavoidable, place them in an unexposed schema + perform auth.uid() checks inside the function body + after changes run db advisors。
  • Storage upsert requires three permissions: INSERT + SELECT + UPDATEgranting only INSERT will cause overwrite uploads to fail silently.
  • Pin dependency versions and commit the lockfile(@supabase/supabase-js、@supabase/ssr、supabase-py etc.).

When to use this Skill

Applicable scenarios (should use):

  • The user mentions Supabase、Volcengine Supabase -related operation requirements
  • Need to create, view, pause, or resume a Supabase workspace (workspace / project), orrestart branch compute
  • Need to execute against a Supabase database SQL queries, table creation, schema changes
  • Need to manage Supabase branches(create, delete, restore, set default)
  • Need to configure Auth (authentication) or use Realtime (real-time)
  • Need to deploy or manage Edge Functions
  • Need to operate on Storage Bucket(create, delete, view configuration, upload/download objects)
  • Need todeploy a frontend static site(and connect it to the Supabase backend as needed)
  • Need to obtain the Supabase project's API Key or connection information
  • Need to, for the Supabase database, generate TypeScript type definitions
  • volcengine-deploy deployment process choose AIDAP as the database solution(database_product=aidap), follow references/deploy-provider.md to provision/reuse the database workspace

Inapplicable scenarios (no need to use):

  • Only discussing general database concepts, not involving Volcengine Supabase instances
  • Operating non-Supabase database services (such as RDS MySQL, Redis)
  • Pure frontend / client-side code writing, not involving Supabase backend resource management
  • The user is only asking about Supabase documentation / concepts and does not need to call the CLI

Command-line tool

All capabilities of this Skill come from byted-supabase-cli this single binary:

npm i -g @byted-supabase/cli         # 安装(一次);装后得到 byted-supabase-cli 命令
byted-supabase-cli --help            # 自检 / 看帮助
byted-supabase-cli <command> --help  # 任何子命令都可加 --help 看参数

Documentation examples are uniformly written as byted-supabase-cli; if your environment has aliased/symlinked it as supabase(the CLI binary itself also refers to itself as --help in supabase), the two forms are equivalent. (Use --help to look up the command structure on the spot, don't guess—seeCore Principle 1。)

Authentication and prerequisites

byted-supabase-cli usesVolcengine credentialsfor authentication.Prefer the CLI's built-in configuration / login method(written to ~/.volcengine/config.json, configure once and reuse long-term):

Method 1 · CLI configuration / login (recommended)

byted-supabase-cli login --region cn-beijing   # 1a. 浏览器 OAuth 登录(最省事,缓存临时 STS 凭据);其他地域替换 cn-beijing
byted-supabase-cli configure set --access-key <AK> --secret-key <SK>   # 1b. 或用 AK/SK 写入默认 profile,可选 [--region <region>]
byted-supabase-cli configure list            # 管理 profile:列出
byted-supabase-cli configure get             # 查看当前 profile
byted-supabase-cli configure profile <name>  # 切换当前 profile

region can be omitted; if specified during login / configure set , it will be written into the profile, and subsequent commands do not need to include --region。

Method 2 · Environment variables (secondary, suitable for headless / CI scenarios that cannot persist)

export VOLCENGINE_ACCESS_KEY=<AK>
export VOLCENGINE_SECRET_KEY=<SK>
export VOLCENGINE_REGION=<region>          # 例如 cn-beijing / cn-shanghai
export VOLCENGINE_SESSION_TOKEN=<token>    # 可选:使用临时凭据时才需要

In environments that already have role credentials built in, such as sandboxes / VeFaaS IAM, you do not need to explicitly set AK/SK; the CLI will automatically obtain temporary credentials.

Region: Optional; defaults to cn-beijingwhen not specified. To target another region (e.g. cn-shanghai), use --region, or set it in login / configure set (once written to the profile, no need to repeat). Resolution priority:--region > environment variables > profile > linked region > default (cn-beijing)。

Auth self-check: If byted-supabase-cli projects list runs successfully, the credentials + region are usable.

⛔ Permission denied (AccessDenied / no permission): Usually insufficient IAM authorization (not an AK/SK/region issue; do not reconfigure credentials),never fabricate policy names/permission items/console URLs; for primary account vs sub-account routing, authorization paths, and official documentation, see references/iam-permission-guide.md。

Targeting (workspace / branch)

  • workspace (workspace/project): Specify with --workspace-id ws-... (its alias --project-ref is compatible with the official Supabase CLI).
  • branch: Specify with --branch-id br-... ; if omitted, falls back to the workspace'sdefault branch。
  • Default target (optional):byted-supabase-cli link --workspace-id ws-... --region <region> sets a workspace as the default link for this directory; afterward, data-plane commands can use --linked(most commands default to --linked=true) without repeating --workspace-id。
  • Output format: Add -o json to management commands for easier parsing;db query outputs JSON by default (agent mode).
  • List pagination (avoid fetching too much at once): Commands that return lists (projects list / branches list / projects operations) support --limit(1-100) + --offset,Prefer explicit paginated fetches; do not retrieve too much data at once; recommended per page: --limit 10, increase --offset to page further when more are needed; especially branches list returns all by default, so when there are many branches be sure to add --limit or use --search to filter. Other list commands currently have no pagination parameters; see tool-reference。

Standard usage flow

  1. First confirm the target resource:workspace_id(if necessary branch_id)
  2. Prefer to runread-only queriesto confirm the current state (projects list、db query "select ..." , etc.)
  3. Only perform write operations when changes are needed; destructive operations (delete/stop) in non-interactive environments require --yes,confirm with the user before execution. ⛔ Especially projects stop(pause workspace) is a high-risk red line — the customer's business will be completely taken offline and cannot be automatically woken up via IO; be sure to confirm twice first (seeCore Principle 5)
  4. After changesquery againto confirm the result has taken effect (corresponding toCore Principle 2)

Capability scope (action → CLI command)

For complete commands, parameters, and equivalent SQL, see references/tool-reference.md. The table below is a quick reference.

Workspace (workspace / project)

Requirement Command
List workspaces projects list
Workspace details / overview projects list --workspace-id ws-... --detail / projects overview
Create workspace projects create <name>(region goes through global/env/profile).After successful creation, you must proactively explain that the suspend timeout is not a blocking question, see "💤 Suspend Timeout" below
Adjust compute / suspend timeout projects compute-settings <ref> --min-cu <n> --max-cu <n> [--suspend-timeout-seconds <秒>](underlying ModifyComputeSettings;to set the suspend timeout use --service-type Supabase --min-cu 0.5, see 💤 below).After changing, do not use projects list --detail to verify whether it took effect—the compute field there is the Database service value, and what you changed is the Supabase service, so it will show "unchanged"; for correct verification use computes list --workspace-id <ref> --service-type Supabase -o json, see tool-reference
⛔ Pause / Resumethe entire workspace(shutdown/startup,high-risk, seeCore Principle 5) projects stop <ref> / projects start <ref>
Delete workspace projects delete <ref> --yes
Get API Keys projects api-keys --workspace-id ws-...
Get access URL / connection string endpoints list --workspace-id ws-... / db connection-string --workspace-id ws-...

💤 Suspend Timeout (SuspendTimeoutSeconds) — after creation, be sure to proactively explain and ask in a non-blocking way.

  • Meaning: the number of idle seconds before the branch computeautomatically suspends when there is no traffic (scale-to-zero). When the time is reached it suspends automatically; the next access to exposeURL (or any request) willautomatically wake it up(cold start)—this is "suspend", notnot"pause workspace" (for the difference seethe distinction belowandCore Principle 5)。
  • Value semantics:-1 = explicitly disable auto-suspend (compute always on / never suspends);0 = platform default when unset (behaves as always on);300–604800 seconds (5 minutes–7 days) = enabled, suspend when idle for that long.Newly created workspaces do not suspend by default(projects list --detail displays as 0). Todisableauto-suspend that is already enabled, pass -1(not 0)。
  • How to modify:projects compute-settings <ref> --service-type Supabase --min-cu 0.5 --max-cu 2 --suspend-timeout-seconds <秒> --yes. ⚠️ Must include --yes + --min-cu/--max-cu, and the Supabase service min CU lower bound is 0.5—just copy these pitfalls as-is; for details see "💤 Suspend Timeout" in tool-reference。
  • Post-creation protocol (non-blocking):projects create after success,proactively explain to the userthe meaning above andin a non-blocking wayprompt whether to set a suspend timeout; you can use this passage directly: "About idle suspend: the compute is currently always on and will not auto-suspend—stable but more resource-intensive. If you want to save compute, you can configure an idle auto-suspend time (no manual action needed on next access; Supabase wakes automatically); 1 hour is recommended."Recommended 1 hour (--suspend-timeout-seconds 3600); if the user does not respond or says it is not needed, keep the default of no suspend,do not block or stall because of thisthe subsequent flow.

Branch

Requirement Command
List / create / delete branches branches list / branches create <name> / branches delete <branch-id>
View / set default branch branches get <id> / branches get-default / branches set-default <id>
Restartbranch compute (reboot) / point-in-time recovery branches restart <id> / branches restore <id> --restore-time <ts>

⚠️ Don't confuse pause / restart / hibernation(the most common misjudgment):

  • Restartbranch compute ("restart" "reboot" "restart compute") → branches restart <id>, one command does it;neveruse projects stop + projects start to simulate it (that stops the entire workspace and then starts it again).
  • Hibernation / wake = branch compute'sautomatic platform behavior: it automatically scales to zero when idle and automatically wakes on access (no manual command needed); the threshold is configurable, see above💤 Hibernation timeout. To manually reset compute use branches restart,don't use projects stop instead。
  • ⛔ Pause / Resume = workspace-levelstop/start (projects stop / projects start), affectingall branches。high-risk red line: after stopping, the customer's business is completely unavailable andcannot be automatically woken by IO, it must be manually projects start——before executing projects stop be sure to restate the impact and confirm twice (seeCore Principle 5)。

One-sentence memory aid:Hibernation/restart → customer access can self-heal or be restored with a single command (low risk); pause → customer access cannot be recovered, only manual start works (high risk, confirm first).

Database (database)

Requirement Command
Execute SQL (inline / file) db query "<sql>" --workspace-id ws-... / db query -f file.sql --workspace-id ws-...
List tables / extensions / applied migrations Use db query to run the corresponding SQL (see tool-reference)
Apply schema changes db query -f file.sql(immediate) / for declarative see db schema declarative
Generate types gen types --lang typescript --workspace-id ws-... -s public
Security/performance inspection db advisors --workspace-id ws-... / inspect db <subcmd>

⚠️ This fork has no separate migration subcommand; for schema changes and the commit workflow see below"Database schema changes and commit"。

Auth (authentication)

The platform supports Supabase Authentication. Auth is mostly used on theapplication sidevia the SDK (sign-up/sign-in/session/JWT); for management and configuration see the VolcanoAuthentication documentation; for SDK usage see references/app-integration-guide.md。

🔐 For auth data use app_metadata(cannot be modified by users),neveruse user_metadata for authorization decisions (seeSecurity checklist)。

Realtime

The platform supports Supabase Realtime (Postgres Changes / Broadcast / Presence), subscribing on the application side via the SDK. For configuration see the VolcanoRealtime documentation; for SDK usage see references/app-integration-guide.md。

Edge Functions

Requirement Command
List functions functions list --workspace-id ws-...
Create a new function (local scaffold) functions new <name> → edit supabase/functions/<name>/index.ts
Deploy function functions deploy <name> --workspace-id ws-...(for public access add --no-verify-jwt)
Download / delete function functions download <name> / functions delete <name>

Deploy fromlocal function directoryGo to (functions new → Edit → functions deploy); single-file/inline code is no longer supported. For writing guidelines, see references/edge-function-dev-guide.md。

Storage (Object Storage)

Requirement Command
List / create / view / delete bucket storage buckets list / storage buckets create <id> [--public] / storage buckets get <id> / storage buckets delete <id>
Object list / upload and download storage ls <path> / storage cp <src> <dst>
Object move / delete storage mv <src> <dst> / storage rm <file...>

Object paths look like ss:///<bucket>/<path>; for directory operations add -r to recurse.

Deploy frontend static site

When you need to deploy a frontend static sitedeploy and go live(optionally connecting to a Supabase backend, injecting environment variables, or creating a frontend + new backend in one click),refer to references/tool-reference.md 's "Pages actions" sectionand references/workflows.md(Pages workflow), and operate according to the commands therein.

⚠️ Distinguish whether to create a new Supabase:pages fast create one-click pipelinewill definitely create a brand-new Supabase workspace(it cannot reuse an existing one). If the useralready has Supabase(workspace / SQL / Edge Functions all ready) and only wants to deploy the frontend,do not use fast create, instead use the atomic pipeline pages upload → pages create --no-deploy → pages bind <pages-project-id> --workspace-id <现有ws> → pages deploy(this one does not create a new instance at all).

Database schema changes and commits

For schema changes, use db query(inline or -f file.sql) to execute directly against the database, and iterate freely.

  • This fork has no separate migration subcommand; do not apply the official supabase migration new / apply_migration habits.
  • Confirm with read-only queries before and after changes(Core Principle 2).
  • Run an inspection after changes → byted-supabase-cli db advisors --workspace-id ws-..., and fix security/performance alerts.
  • If the change involves views, functions, triggers, or Storage,go back to thesecurity checklistand review item by item。
  • When versioned / traceable schema evolution is needed, switch to declarative management:byted-supabase-cli db schema declarative --help。

Notes

  • This fork has no global read-only switch; the safety boundary for write operations relies on RLS (anon vs service_role) + operational discipline.
  • db query connects by default to the --linked project; when not linked, be sure to explicitly pass --workspace-id(if necessary, --branch-id)。

Online documentation

Corresponds toCore Principle 1: when unsure, check these first.

Reference materials

Documentation Purpose
references/tool-reference.md Command quick reference: action → CLI + equivalent SQL
references/workflows.md Common operation workflows (inspection / changes / release)
references/sql-playbook.md Common SQL examples (CRUD / JOIN / pgvector / RPC)
references/app-integration-guide.md Integrating TS/Python applications: SDK initialization + CRUD + Auth + Realtime
references/schema-guide.md Table Structure Design and Change Specifications
references/rls-guide.md Row-Level Security (RLS) Policy Configuration
references/security-guide.md Supabase-Specific Security Pitfalls Checklist
references/iam-permission-guide.md Troubleshooting Permission Denied (Insufficient IAM Authorization): Primary Account vs. Sub-Account Triage + Authorization Paths
references/pg-best-practices/index.md Postgres Performance and Best Practices (Indexes / Connections / Locks / Monitoring, etc.)
references/edge-function-dev-guide.md Writing and Deploying Edge Functions
references/deploy-provider.md For volcengine-deploy invocation: AIDAP as the supply process for deploying database solutions

📚 Postgres Best Practices Breakdown(all indexed by the above index.md , jump directly as needed):query.md · conn.md · security.md · schema.md · lock.md · data.md · monitor.md · advanced.md

💡 Typical Workflow: First use the CLI to create a workspace / create tables / configure RLS, then refer to the application integration documentation to integrate the Supabase SDK into your business code.