volcengine-db-supabase

Volcengine AI-native BaaS platform · Supabase edition

This Skill is used in conversation to act asthe intelligent Ops 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 adaptation on top of the Supabase protocol/ecosystem,and differs from the official version：

Use byted-supabase-cli to operate (notthe official supabase CLI), authenticating 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 differ。

👉 Operations are governed by this Skill's documentation and byted-supabase-cli <command> --help prevail,do not apply the command conventions of the official Supabase CLI。

It will:

identify the user's natural-language Supabase needs
directly call byted-supabase-cli command-line tools to obtain real-time results
based on the returned results, provide explanations, troubleshooting, and next-step suggestions

Core principles

This section covers general work discipline,and should be followed for any Supabase task。

1. The platform evolves quickly — check online docs/release notes first, don't rely only on training data. Commands, parameters,config items, and API conventions change with versions. Before acting, check Volcengine's official documentation and release notes (see the end foronline documentation), especially when uncertain commands/parameters are involved; always check 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 another read-only query to confirm it took effect. An unverified fix = incomplete.

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, look at the error more carefully, and check logs if necessary. Supabase-type issues are not always solved by retrying the same command.

4. Expose tables to the Data API (REST). Newly created tablesdo not necessarilyget automatically exposed through the Data API. If you want anon / authenticated roles to access a table via REST, you need to explicitly GRANT。

Note: this is different from RLS — Data API exposure + role authorization determinewhether the table is reachable; RLS determines, once the table is reachable,which rows are visible. When users report "tables created via SQL are inaccessible," first confirm whether these two roles have been authorized.When granting to external roles (anon/authenticated), be sure to enable RLS at the same time.

5. ⛔ High-risk red line:projects stop(pausing a workspace) will make the customer's business completely unavailable. Paused instancescannot be automatically woken by client IO / access traffic(this is "wake on access" as with branch hibernationfundamentally different)—the entire workspace and all of itsall branchesstop serving; REST / Auth / Storage / direct DB all unreachable, and a person mustmanually projects start to recover. Therefore, before executing projects stop beforemust：

explicitly 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 automatically recover. Confirm?"

Verify that the target ref is 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 neitherwill notcause the business to stop serving.

（projects delete They are also irreversible high-risk operations and likewise require prior confirmation.)

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

7. Security checklist. For any task involving Auth, RLS, views, Storage, or user data, go through the following Supabase-specific security pitfalls(see the full version at references/security-guide.md）：

neveruse user_metadata / raw_user_meta_data for authorization decisions—itis user-modifiable, so putting it into RLS / authorization logic allows forgery. Store authorization data in raw_app_meta_data / app_metadata。
service_role / secrets must never appear in the frontend. The frontend uses publishable / anon key；service_role backend only.
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 it in a non-exposed schema.
auth.role() is deprecated —switch to TO authenticated / TO anonon policies. After anonymous sign-in is enabled, anonymous users also carry the authenticated role,auth.role() = 'authenticated' willsilently fail。
Writing only TO authenticated is "authentication, not authorization" (BOLA/IDOR) —it must be paired with an ownership predicate:to authenticated using ( (select auth.uid()) = user_id )。
UPDATE policies must have both USING and WITH CHECK, otherwise users can change a 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, the update silently returns 0 rows (with no error).
SECURITY DEFINER functions bypass RLS, and under public are callable by all roles by default. Do not use it to "solve" permission errors; if you must use it, put it in a non-exposed schema + perform the auth.uid() check inside the function body + after changes run db advisors。
Storage upsert requires all three privileges: INSERT + SELECT + UPDATE, and granting only INSERT will cause overwrite uploads to silently fail.
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、Volcano Engine Supabase related operation needs
Need to create, view, pause, or resume Supabase workspace (workspace / project), orrestart branch compute
Need to execute on the 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
Need to deploy or manage Edge Functions
Need to operate Storage Bucket(create, delete, view configuration, upload/download objects)
Need todeploy a frontend static site(and connect with 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 select AIDAP as the database solution（database_product=aidap) when, according to references/deploy-provider.md provision/reuse database workspace

Not applicable scenarios (no need to use):

Only discussing general database concepts, not involving Volcano Engine 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, no need to call the CLI

command-line tool

All capabilities of this Skill come from byted-supabase-cli this one 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 in --help also calls itself supabase), the two forms are equivalent. (Use --help to check the command structure on the fly, don't guess—seeCore Principle 1。）

Authentication and prerequisites

byted-supabase-cli usesVolcano Engine credentialsfor authentication.Prefer using 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 carry --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 such as sandboxes / VeFaaS IAM that already have role credentials, AK/SK do not need to be explicitly set; the CLI will automatically obtain temporary credentials.

Region: can be omitted; when not specified, defaults to cn-beijing. When you need to specify another region (such as cn-shanghai), use --region, or set it during login / configure set . (Written into the profile, no need to repeat later.) Resolution priority:--region > environment variables > profile > linked region > default (cn-beijing）。

Authentication self-check: able to successfully run byted-supabase-cli projects list meaning credentials + region are available.

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

Target location (workspace / branch)

workspace (workspace/project): use --workspace-id ws-... specify (its alias --project-ref is compatible with the official Supabase CLI).
branch (branch): use --branch-id br-... specify; if not passed, it falls back to that 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; afterwards data plane commands can use --linked(most commands default to --linked=true) without repeating --workspace-id。
Output format: add to admin commands -o json for easy 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 fetching, don't retrieve too much data at once; recommended per page --limit 10, and if you need more, increment --offset to page; 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

First confirm the target resource:workspace_id(if necessary branch_id）
execute firstread-only query, confirm the current state (projects list、db query "select ..." etc.)
only execute write operations when changes are needed; destructive operations (delete/stop) in non-interactive environments require adding --yes，Confirm with the user before execution. ⛔ Especially projects stop(pause workspace) is a high-risk red line—customer business will be completely stopped and cannot be automatically awakened by IO, so be sure to confirm twice first (seeCore Principle 5）
After the changequery 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 the idle timeout and not block with a question, see “💤 Idle timeout” below
Adjust compute / idle timeout	`projects compute-settings <ref> --min-cu <n> --max-cu <n> [--suspend-timeout-seconds <秒>]`(underlying ModifyComputeSettings;to set the idle 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 value of the Database service; what was changed is the Supabase service and it will show "unchanged"; use `computes list --workspace-id <ref> --service-type Supabase -o json`, see tool-reference
⛔ Pause / Resumethe entire workspace(stop/start,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 address / 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: branch computethe number of idle seconds before automatic suspension with no traffic (scale-to-zero). When the time is up, it automatically suspends; the next access to exposeURL (or any request) willautomatically wake it up(cold start) — this is "suspend" andnot"pause workspace" (for the difference, seethe distinction belowandCore Principle 5）。

Value semantics：-1 = explicitly turn off automatic suspension (compute always on / never suspends);0 = platform default when unset (behaviorally equivalent to always on);300–604800 seconds (5 minutes–7 days) = enabled, suspends when idle reaches the threshold.Newly created workspace does not suspend by default（projects list --detail is shown as 0). Toturn offautomatic suspension that has already been 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 limit is 0.5 — just copy these pitfalls as-is; for details see "💤 Suspend timeout" in tool-reference。

Protocol after creation (non-blocking)：projects create After success,proactively explain to the userthe above meaning andin a non-blocking wayprompt whether to set a suspend timeout; you can directly use this passage: "About idle suspension: currently the compute is always on and will not automatically suspend — stable but more resource-intensive. If you want to save compute, you can configure an idle auto-suspend time (no manual action is needed on the next access; Supabase wakes it up automatically), 1 hour is recommended."1 hour recommended (--suspend-timeout-seconds 3600）; if the user does not respond or indicates it is not needed, keep the default of no suspension,do not get stuck or block because of thisthe subsequent process.

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>`

⚠️ Do not confuse pause / restart / suspend(the most common misjudgment):

Restartbranch compute ("restart" "reboot" "restart compute") → branches restart <id>, one command does it;neveruse projects stop + projects start to simulate (that is stopping and then starting the entire workspace).

Suspend / wake = branch compute'sautomatic platform behavior: automatically scale-to-zero when idle reaches the threshold, and automatically wake on access (no manual command needed); thresholds are configurable, see above💤 Idle timeout. To manually reset compute use branches restart，do not use projects stop instead。

⛔ Pause / Resume = workspace levelStop/Start (projects stop / projects start), affects itsall branches。High-risk red line: after stopping, customer business is completely unavailable andcannot be automatically woken by IO, must be manual projects start—before executing projects stop be sure to restate the impact and confirm twice (seeCore Principle 5）。

One-sentence mnemonic:Idle/restart → customer access can self-heal or be restored with a single command (low risk); pause → customer access cannot be recovered, only manual start (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) / 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 submission process see below"Database schema changes and submission"。

Auth (authentication)

The platform supports Supabase Authentication. Auth is mostly on theapplication sideused via SDK (sign-up/login/session/JWT); for management and configuration see VolcanoAuthentication docs; for SDK usage see references/app-integration-guide.md。

🔐 Use for authentication data app_metadata(cannot be changed by users),neveruse user_metadata for authorization decisions (seeSecurity checklist）。

Realtime (real-time)

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

Edge Functions (edge functions)

Requirement	Command
List functions	`functions list --workspace-id ws-...`
Create function (local scaffolding)	`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>`

Deployment is done fromlocal function directory(functions new → edit → functions deploy), single-file/inline code is no longer supported. For authoring standards 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 download	`storage ls <path>` ／ `storage cp <src> <dst>`
Object move / delete	`storage mv <src> <dst>` ／ `storage rm <file...>`

Object paths are in the form ss:///<bucket>/<path>, for directory operations add -r recursive.

Deploy frontend static site

Need to deploy the frontend static sitedeploy online(optionally connecting to the Supabase backend, injecting environment variables, or creating the frontend + a new backend with one click),refer to references/tool-reference.md 's "Pages Actions" sectionand references/workflows.md(Pages Workflows), and just follow the commands in them.

⚠️ You must 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 are all ready), and only wants to deploy the frontend,do not use fast create, use the atomic pipeline instead 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

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

This fork does not have an independent migration subcommand, do not apply the official supabase migration new / apply_migration habit.
Confirm with read-only queries before and after changes(Core Principle 2).
After changes, run the inspection → byted-supabase-cli db advisors --workspace-id ws-..., and fix security/performance warnings.
If the change involves views, functions, triggers, or Storage,go back tosecurity checklistand recheck 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 depends on RLS (anon vs service_role) + operational discipline.
db query By default connects 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.

New feature release record (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 with TS/Python apps: SDK initialization + CRUD + Auth + Realtime
`references/schema-guide.md`	Table structure design and change conventions
`references/rls-guide.md`	Row-level security (RLS) policy configuration
`references/security-guide.md`	Supabase-specific security pitfalls checklist
`references/iam-permission-guide.md`	Permission denied (insufficient IAM authorization) troubleshooting: main account vs sub-account routing + authorization paths
`references/pg-best-practices/index.md`	Postgres performance and best practices (indexes / connections / locks / monitoring, etc.)
`references/edge-function-dev-guide.md`	Edge Function authoring and deployment
`references/deploy-provider.md`	For `volcengine-deploy` invocation: AIDAP as the provisioning process for the deployed database solution

📚 Postgres best practices breakdown(all by the above index.md Index, 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 in the business code.