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-clito operate (notthe officialsupabaseCLI), authenticate via Volcengine account / AK-SK ;- The resource model is workspace / branch / compute, and there are
endpoints、computesand 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-clicommand-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:
- 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?"- Verify the target
refis correct, never stop the wrong workspace;- 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 deleteare 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_datafor authorization decisions — itis user-modifiable, and placing it in RLS/authorization logic allows forgery. Store authorization data inraw_app_meta_data/app_metadata。 service_role/ keys must never appear in the frontend. The frontend uses publishable /anonkey;service_roleonly on the backend.- Views bypass RLS by default — on PG15+ use
CREATE VIEW ... WITH (security_invoker = true); on lower versions, revoke view privileges fromanon/authenticatedor place them in an unexposed schema. auth.role()is deprecated — instead use the policy'sTO authenticated/TO anon. After enabling anonymous sign-in, anonymous users also carry theauthenticatedrole, andauth.role() = 'authenticated'willsilently fail。- Writing only
TO authenticatedis "authentication rather than authorization" (BOLA/IDOR) — ownership predicates must be included:to authenticated using ( (select auth.uid()) = user_id )。 - UPDATE policies must have both
USINGandWITH CHECK, otherwise users can change the row'suser_idto 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 DEFINERfunctions bypass RLS, and underpublicthey are callable by all roles by default. Do not use them to "solve" permission errors; if unavoidable, place them in an unexposed schema + performauth.uid()checks inside the function body + after changes rundb 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-pyetc.).
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-deploydeployment process choose AIDAP as the database solution(database_product=aidap), followreferences/deploy-provider.mdto 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 assupabase(the CLI binary itself also refers to itself as--helpinsupabase), the two forms are equivalent. (Use--helpto 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, seereferences/iam-permission-guide.md。
Targeting (workspace / branch)
- workspace (workspace/project): Specify with
--workspace-id ws-...(its alias--project-refis 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 jsonto management commands for easier parsing;db queryoutputs 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--offsetto page further when more are needed; especiallybranches listreturns all by default, so when there are many branches be sure to add--limitor use--searchto filter. Other list commands currently have no pagination parameters; see tool-reference。
Standard usage flow
- First confirm the target resource:
workspace_id(if necessarybranch_id) - Prefer to runread-only queriesto confirm the current state (
projects list、db query "select ...", etc.) - Only perform write operations when changes are needed; destructive operations (delete/stop) in non-interactive environments require
--yes,confirm with the user before execution. ⛔ Especiallyprojects 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) - 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–604800seconds (5 minutes–7 days) = enabled, suspend when idle for that long.Newly created workspaces do not suspend by default(projects list --detaildisplays as0). Todisableauto-suspend that is already enabled, pass-1(not0)。- 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 createafter 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;neveruseprojects stop+projects startto 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 useprojects stopinstead。- ⛔ 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 manuallyprojects start——before executingprojects stopbe 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
migrationsubcommand; 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),neveruseuser_metadatafor 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, seereferences/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-rto 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" sectionandreferences/workflows.md(Pages workflow), and operate according to the commands therein.⚠️ Distinguish whether to create a new Supabase:
pages fast createone-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 pipelinepages 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
migrationsubcommand; do not apply the officialsupabase migration new/apply_migrationhabits. - 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 queryconnects by default to the--linkedproject; 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.
- New feature release notes (changelog):https://www.volcengine.com/docs/87275/2105759?lang=zh
- API release history / API list:https://www.volcengine.com/docs/87275/2105870?lang=zh / https://www.volcengine.com/docs/87275/2105871?lang=zh
- SDK release history / overview:https://www.volcengine.com/docs/87275/2248647?lang=zh / https://www.volcengine.com/docs/87275/2248648?lang=zh
- Using Database:https://www.volcengine.com/docs/87275/2385100?lang=zh
- Using Authentication:https://www.volcengine.com/docs/87275/2277072?lang=zh
- Using Realtime:https://www.volcengine.com/docs/87275/2277058?lang=zh
- Using Edge Function:https://www.volcengine.com/docs/87275/2288709?lang=zh
- Using Storage:https://www.volcengine.com/docs/87275/2277057?lang=zh
- Go SDK:https://www.volcengine.com/docs/87275/2248650?lang=zh / Python SDK:https://www.volcengine.com/docs/87275/2375511?lang=zh
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.