SuperAPI AI Directory

byted-supabase

Data & analytics

View repository

Updated 10-15 17:30

About this skill

Volcano Engine AI-Native BaaS Platform · Supabase Edition

This Skill is used in conversation to act asthe intelligent operations and development agent for Volcano Engine's "AI-Native BaaS Platform Supabase Edition"。

ℹ️ This is an AI-native BaaS platform independently developed by Volcano Engine (Supabase Edition), not the official open-source Supabase. It has been adapted into a Volcano Engine platform 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 Volcano Engine account / AK-SK ;
  • the resource model is workspace / branch / compute, and there are endpoints、computes and other Volcano-specific commands;
  • some commands, parameters, and behaviors are different。

👉 Operations are subject to this Skill's documentation and byted-supabase-cli <command> --help ,do not apply the command habits of the official Supabase CLI。

It will:

  • Identify the user's Supabase natural language requirements
  • Directly call byted-supabase-cli command-line tools to obtain real-time results
  • Provide explanations, troubleshooting, and next-step suggestions based on the returned results

Core Principles

This section covers general working discipline,which any Supabase task should follow。

1. The platform evolves quickly — check the online documentation/release notes first; do not rely only on training data. Commands, parameters,config items, and API conventions change with versions. Before taking action, first check the Volcano Engine official documentation and release notes (see the end of this documentOnline Documentation), 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 deployed,run another read-only query to confirm it took effect. An unverified fix = unfinished.

3. Recover from errors, do not loop endlessly. If the same method fails 2-3 times in a row, stop and change your approach: try another method, check the documentation, look at 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 tablesmay notbe 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 a user reports "a table created via SQL is inaccessible", first confirm whether these two roles have been authorized.When granting external (anon/authenticated) access, 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. Instances after pausingCannot be automatically woken by customer IO / access traffic(this is fundamentally different from branch hibernation's "wake on access"fundamentally different) — the entire workspace and allall branchesbranches under it stop service, REST / Auth / Storage / direct DB connection all unreachable, and must be done by a personmanually projects start to recover. Therefore, before executing projects stop ,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 / hibernate / save resources" — use projects sleep/projects wakefor workspace hibernation/waking, and use computes restart/projects settingsfor compute restart/auto-hibernation configuration; neitherwill notis equivalent to workspace suspension.

(projects delete is also an irreversible high-risk operation and likewise requires confirmation first.)

6. Tables in an exposed schema must have RLS enabled. Every table in any externally exposed schema (by default including public) must ENABLE ROW LEVEL SECURITY; private schemas are also recommended to enable it as defense in depth. Once enabled, 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 putting it into RLS/authorization logic allows it to be forged. 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 — switch to TO authenticated / TO anonon policies. After enabling anonymous sign-in, anonymous users also carry the authenticated role, andauth.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 (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 you must, put them in an unexposed schema + perform auth.uid() checks inside the function body + run db advisors。
  • Storage upsert requires the three privileges INSERT + SELECT + UPDATE, and granting 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、Volcano Engine Supabase -related operation requirements
  • Need to create, view, pause, or resume a 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 (real-time)
  • Need to deploy or manage Edge Functions
  • Need to operate Storage Bucket(create, delete, view configuration, upload/download objects)
  • Need to run isolated code, execute an AI Coding Agent, upload files, or manage temporary Sandbox
  • Need todeploy a frontend static site(and connect it 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

Not applicable scenarios (no need to use):

  • Only discussing general database concepts, not involving a Volcano Engine Supabase instance
  • 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, with 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 already aliased/symlinked it as supabase(the CLI binary itself, in --help , also calls itself supabase), the two forms are equivalent. (Use --help to look up the command structure on the spot; do not guess—seeCore Principle 1。)

Authentication and prerequisites

The authentication method depends on the runtime mode:

  • Volcano account methodUse Volcano Engine credentials.Prefer the CLI's built-in configuration / login method(write to ~/.volcengine/config.json, configure once and reuse for a long time):

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 in login / configure set , it will be written to 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 that already have role credentials, such as the sandbox / VeFaaS IAM, you can skip explicitly setting AK/SK; the CLI will automatically obtain temporary credentials.

Region: can be omitted; when not specified, defaults to cn-beijing. If you need to specify another region (such as cn-shanghai), then use --region, or set it in 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: If it runs successfully, byted-supabase-cli projects list that means the credentials + region are usable.

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

Target selection (workspace / branch)

  • workspace: specify with --workspace-id ws-... (its alias --project-ref is compatible with the official Supabase CLI).
  • branch: specify with --branch-id br-... ; if not passed, it falls back to this 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 having to repeat --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 pagination when fetching, don't retrieve too much data at once; recommended --limit 10per page, and if more is needed increment --offset to page through; especially branches list returns everything by default, so when there are many branches be sure to add --limit or use --search to filter. Other list commands have no pagination parameters for now, see tool-reference。

Standard usage flow

  1. First run byted-supabase-cli link status -o json, read the type field to confirm whether it is currently the Volcano account method (management) or the branch URL + Key method (solo)。
  2. Workspace mode: confirm workspace_id(if necessary branch_id), prefer read-only queries (such as projects list、db query "select ...")。
  3. Branch URL + Key method: confirm the linked Supabase URL; depending on the operation, confirm whether the anon key, service-role key or database URL is configured, prefer read-only queries (such as storage buckets list、functions list、auth config get)。
  4. When changes are needed, then perform write operations; destructive operations (delete/shutdown) in non-interactive environments require --yes,confirm with the user before execution. ⛔ Especially in Workspace mode, projects stop(pausing a workspace) is a high-risk red line—the customer's business will be completely down and cannot be automatically woken up by IO, so be sure to double-confirm first (seeCore Principle 5)。
  5. After changes,query 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)

Need 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 sleep timeout is not a blocking prompt, see 「💤 Sleep timeout」 below
Configure compute auto-sleep projects settings compute <ref> --min-cu <n> --max-cu <n> [--suspend-timeout-seconds <秒>](underlying ModifyComputeSettings;to set the compute auto-sleep timeout, use --service-type Supabase --min-cu 0.5, see 💤 below). This command only modifies the configuration; it will not immediately put the workspace or compute to sleep.
Immediately sleep the entire workspace projects sleep --workspace-id <workspace-id> --yes(underlying SuspendWorkspace; this is workspace sleep, not pause)
Wake a sleeping workspace projects wake --workspace-id <workspace-id> --yes(first call DescribeWorkspaceEndpoint to get AddressDomain, then access a Supabase instance once to trigger wake-up)
⛔ Pause / Resumethe entire workspace(stop/start,high-risk, seeCore Principle 5) projects stop --workspace-id <workspace-id> / projects start --workspace-id <workspace-id>
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-...

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

  • Meaning: the number of idle seconds before branch computeautomatically sleeps when there is no traffic (scale-to-zero). When the time is reached, it automatically sleeps; the next access to exposeURL (or any request) willautomatically wake it up(cold start) —— this is "sleep" andnot"pause workspace" (for the difference, seethe distinction belowandCore Principle 5)。
  • Value semantics:-1 = explicitly turn off auto-sleep (compute always on / never sleeps);0 = the unset platform default (behaviorally equivalent to always on);300–604800 seconds (5 minutes–7 days) = enabled, sleeps when idle for that long.Newly created workspaces do not sleep by default(projects list --detail is displayed as 0). Toturn offan already enabled auto-sleep, pass -1(not 0)。
  • How to modify:projects settings compute <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; for details see "💤 Sleep timeout" in tool-reference。
  • Post-creation protocol (non-blocking):projects create after success,proactively explain to the userthe above meaning andin a non-blocking wayprompt whether to set a sleep timeout; you may directly use this passage: "About idle sleep: the current compute is always on and will not automatically sleep—stable but more resource-intensive. If you want to save compute, you can configure an idle auto-sleep time (no manual action is needed on the next access; Supabase will automatically wake it up); 1 hour is recommended."1 hour recommended (--suspend-timeout-seconds 3600); if the user does not respond or says it is not needed, keep the default of no sleep,do not get stuck or blocked because of thisin subsequent processes.

AI Gateway

AI Gateway provides Workspace branch capabilities for large model access, image generation, and Seedance video generation. For tasks involving AI Gateway, first read the complete guide references/ai-gateway.md, then execute as needed:

  • Model/endpoint query:ai-gateway status、ai-gateway models list
  • OpenAI-compatible call:ai-gateway chat completions
  • Image generation: refer to the Images API example in the guide
  • Quota management:ai-gateway quota get、quota set-default、quota users list/get/set
  • Usage summary:ai-gateway usage

The guide includes JavaScript/Python integration demos for Supabase Auth, Third-Party Auth JWT, and the backend, as well as quota units, image model sizes, and troubleshooting notes. Commands and parameters are subject to access_token, Third-Party Auth JWT, backend service_role_key , as well as quota units, image model sizes, and troubleshooting notes. Commands and parameters are subject to byted-supabase-cli ai-gateway --help .

Sandbox (isolated execution)

When running untrusted code, isolated testing, AI Coding Agent, temporary services, or Sandbox file operations, first read references/sandbox-guide.md。

  • First check byted-supabase-cli --version and sandbox --help; if the command does not exist, then byted-supabase-cli update。
  • For one-off tasks and debugging CLI create、connect、exec、kill; for continuous in-app execution and background tasks, use the E2B-compatible SDK.
  • e2b SDK must be lower than 2.51(Node e2b@2.50.0, Python is constrained by byted_supabase_sandbox ): starting from 2.51 it switches to /v2/sandboxes, and gateways before 6.9.1 return 404. For the Node SDK, first npm pack then install the tgz; do not install the directory directly.
  • Choose one of three identity creation options: user session (recommended), backend service_role + ownerUserId、service_role + PassServiceRoleJwtToSandbox(bypasses RLS, use with caution). anon key cannot be used as apiKey。
  • Strictly distinguish management-plane credentials, the CLI's envdAccessToken, user session token, and service_role key;sandboxID and tokens should only be placed in environment variables and not output. After execution ends or fails, kill it.
  • Background commands must timeoutMs: 0, and immediately after startup disconnect()。
  • The result depends on exit_code / status and stdout / stderr; the outer command succeeding does not mean the task inside the sandbox succeeded.
  • The port preview address is accessible by default to holders, and should only be given to the sandbox owner; when encountering 401, 501, 502, troubleshoot according to the FAQ in the reference documentation.

branch

Requirement Command
List / create / delete branch 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 computes restart <branch-id> [--compute-id <compute-id>] / branches restore <id> --restore-time <ts>

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

  • Restartbranch compute ("restart" "reboot" "restart compute") → computes restart <id> [--compute-id <compute-id>], underlying RestartBranch;neveruse projects stop + projects start to simulate (that is stopping and starting the entire workspace).
  • workspace hibernate = projects sleep, call SuspendWorkspace, to put the entire workspace into hibernation;do notuse projects stop instead.
  • workspace wake = projects wake, first obtain DescribeWorkspaceEndpoint via AddressDomain, then access the Supabase instance once to trigger wake; do not use projects start, the latter corresponds to recovery after an explicit pause.
  • Compute auto-hibernate = set projects settings via SuspendTimeoutSeconds, automatically executed by the platform based on idle time; this is not a compute restart, nor an immediate workspace hibernate.
  • ⛔ Pause / resume = workspace-levelstop/start (projects stop / projects start), affectingall branches。high-risk red line: after stopping, the customer's business becomes completely unavailable andcannot be automatically woken by IO, manual action is required projects start— before executing projects stop , be sure to restate the impact and confirm a second time (seeCore Principle 5)。

One-sentence mnemonic:Hibernate/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

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 in"Database schema changes and commits"。

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 VolcanoAuthentication docs; for SDK usage, see references/app-integration-guide.md。

🔐 Use app_metadatafor authorization data (it cannot be modified by users);neveruse user_metadata to make authorization decisions (seeSecurity checklist)。

Realtime

The platform supports Supabase Realtime (Postgres Changes / Broadcast / Presence), subscribed to on the application side via the SDK. For configuration, see VolcanoRealtime docs; 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 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>

Deploy from thelocal 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 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 for recursion.

Deploy frontend static site

When you need to deploy a frontend static sitelive(optionally connecting it to a Supabase backend, injecting environment variables, or creating a frontend + new backend with one click),refer to references/tool-reference.md 's "Pages actions" sectionand references/workflows.md(Pages workflow), and just follow the commands in them.

⚠️ Be clear about whether to create a new Supabase:pages fast create one-click flowwill definitely create a brand-new Supabase workspace(an existing one cannot be reused). If the userAlready have Supabase(workspace / SQL / Edge Functions are all ready), and only want to deploy the frontend,do not use fast create, switch to the atomic pipeline pages upload → pages create --no-deploy → pages bind <pages-project-id> --workspace-id <现有ws> → pages deploy(this path 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 does not have an independent migration subcommand, so do not apply the habits of the official supabase migration new / apply_migration .
  • Use read-only queries to confirm before and after changes(Core Principle 2).
  • After changes, run the inspection → byted-supabase-cli db advisors --workspace-id ws-...and fix security/performance alerts.
  • If the changes involve 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 security boundary for write operations depends on RLS (anon vs service_role) + operational discipline.
  • db query defaults to connecting 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/ai-gateway.md AI Gateway integration demo, image generation, quota management, and troubleshooting
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 Integrate TS/Python applications: SDK initialization + CRUD + Auth + Realtime
references/schema-guide.md Table structure design and change standards
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 routing + authorization path
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/sdk-pitfalls.md Common SDK and query pitfalls (URL length limits / error capture / index evaluation)
references/sandbox-guide.md Sandbox CLI/SDK lifecycle, credential boundaries, and failure diagnostics
examples/hello-world-node/ Minimal complete Node.js Sandbox SDK example: register/login user, create Sandbox, execute commands, and clean up
examples/hello-world-python/ Minimal complete Python Sandbox SDK example: register/login user, create Sandbox, execute commands, and clean up
scripts/sandbox-cli-lifecycle.sh、scripts/sandbox-node.mjs、scripts/sandbox-python.py Sandbox CLI lifecycle and complete Node/Python examples

📚 Postgres best practices breakdown(all indexed by the index.md above, and can be accessed 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.