Cloudbase Platform

Environment and Authentication

1. SDK Initialization:

   • CloudBase SDK initialization requires environment ID
   • Can query environment ID via queryEnv tool
   • If the user only provides an environment alias, nickname, or other short form, resolve it with queryEnv(action="list", alias=..., aliasExact=true) first and use the returned full EnvId
   • Do not pass alias-like short forms directly into SDK init, auth.set_env, console URLs, or generated config files
   • For Web, always initialize synchronously:
     • import cloudbase from "@cloudbase/js-sdk"; const app = cloudbase.init({ env: "your-full-env-id" });
     • Do not use dynamic imports like import("@cloudbase/js-sdk") or async wrappers such as initCloudBase() with internal initPromise
   • Then proceed with login using a verified method (username/password, phone, email, or WeChat)

2. Environment Management (via manageEnv): The manageEnv tool provides full lifecycle management for CloudBase environments.

   Action	Description	Key Parameters
   listPackages	Query available plans	(none)
   create	Create new environment (needs confirm)	alias, packageId, resources, duration, region, externalStorage
   modifyPlan	Change plan (upgrade/downgrade, needs confirm)	envId, packageId
   renew	Renew environment (needs confirm)	envId, duration

   Creating an environment with specific resources:

   manageEnv(action="create", alias="my-env", packageId="baas_personal",
             resources=["storage","function","postgresql"], confirm="yes")

   • resources (optional, create only): controls which CloudBase capabilities to enable:
     • storage — Cloud Storage
     • function — Cloud Functions
     • postgresql — PostgreSQL relational database (PG mode)
   • Defaults to all three when omitted. MCP always sends non-empty Resources to CreateEnv.
   • flexdb (document database) is not offered: new environments are created without a NoSQL tenant. Do not pass it — it is rejected by the schema. To find out whether an environment actually has NoSQL, read queryEnv(action="info") → EnvInfo.RuntimeBackends rather than assuming.
   • Region is selectable: pass region (e.g. region="ap-shanghai") to choose where the environment is created. It is applied as the X-TC-Region request context, not as a CreateEnv body field — so do not put Region inside params. Omit it to use the current session region (cloudBaseOptions.region → TCB_REGION → project config / rc binding → site default: ap-shanghai for the domestic site, ap-singapore for the intl site). Equivalent CLI: tcb env create --region ap-shanghai.
   • ⚠️ If you pass region, repeat the same value on the confirming call together with confirm="yes"; otherwise the second call falls back to the session region and the environment may be created somewhere other than the summary you confirmed.
   • externalStorage (optional, create only): { bucketName, region, basePath } creates the environment's cloud storage on an existing shared COS bucket instead of a dedicated one, isolating its files under basePath (must be unique within the bucket). All three fields are required when the object is passed. Use it only when the user provides the bucket — typically a platform creating many environments under one account, where one bucket per environment would hit the account's COS bucket quota; never invent bucket names. It does not cover static hosting: the hosting bucket is chosen by the platform when hosting is enabled and cannot be set through this tool.
   • ⚠️ Like region, repeat the same externalStorage on the confirm="yes" call. The confirming call reads only its own arguments, so leaving it out creates the environment with a dedicated bucket instead.

   manageEnv(action="create", alias="tenant-a", packageId="baas_personal",
             externalStorage={ bucketName: "shared-bucket-1250000000", region: "ap-shanghai", basePath: "tenant-a" },
             confirm="yes")

   • ⚠️ All paid operations (create / modifyPlan / renew) require confirm="yes".

   Querying available packages before creating:

   manageEnv(action="listPackages")

   Changing plan (e.g. personal → standard):

   manageEnv(action="modifyPlan", envId="your-env-id", packageId="baas_pf_standard", confirm="yes")

   Renewing an environment:

   manageEnv(action="renew", envId="your-env-id", duration=1, confirm="yes")

Authentication Best Practices

Important: Authentication methods for different platforms are completely different, must strictly distinguish!

Web Authentication

• Must use SDK built-in authentication: CloudBase Web SDK provides complete authentication features
• Recommended method: SMS login with auth.getVerification(), for detailed, refer to web auth related docs
• Forbidden behavior: Do not use cloud functions to implement login authentication logic
• Session management: For route guards and login proof, use auth.getSession() and require data.session; do not use deprecated getLoginState() or auth.getUser() / auth.getCurrentUser() as proof of real login.
• Provider and login-method setup: Use queryAppAuth / manageAppAuth, not the MCP auth tool
• Anonymous login is disabled by default. Publishable accessKey alone does not create a gateway-authenticated anonymous session. With @cloudbase/js-sdk 3.x, call await auth.signInAnonymously() (or an equivalent authenticated session) before NoSQL app.database() CRUD, or the gateway returns 401. If the app uses AuthGuard or RLS for access control, ensure is_anonymous checks are in place when anonymous access is allowed.
• ⚠️ PG RLS: Use auth.uid(), NOT current_user. When writing RLS policies for CloudBase PostgreSQL, the user identity must use auth.uid() (returns the JWT sub / actual user ID as text, not uuid — unlike Supabase). Prefer owner columns as varchar(64) / text; if the column is uuid, cast with auth.uid()::uuid or you get operator does not exist: uuid = text. Do NOT use current_user or current_setting(...) — these PostgreSQL built-in functions return the database role name (e.g. authenticated), not the CloudBase auth user ID. CloudBase PG provides four auth helper functions: auth.uid(), auth.role(), auth.email(), auth.jwt(). Verify availability with SELECT proname FROM pg_proc WHERE pronamespace = 'auth'::regnamespace.

Mini Program Authentication

• Login-free feature: Mini program CloudBase is naturally login-free, no login flow needed
• User identifier: In cloud functions, get wxContext.OPENID via wx-server-sdk
• User management: Manage user data in cloud functions based on openid
• Forbidden behavior: Do not generate login pages or login flow code

Cloud Functions

1. Node.js Cloud Functions:
   • Node.js cloud functions need to include package.json, declaring required dependencies
   • Can use manageFunctions(action="createFunction") to create functions
   • Use manageFunctions(action="updateFunctionCode") to deploy cloud functions
   • Prioritize cloud dependency installation, do not upload node_modules
   • functionRootPath refers to the parent directory of function directories, e.g., cloudfunctions directory

Database Permissions

⚠️ CRITICAL: Always configure permissions BEFORE writing database operation code!

1. Permission Model:

   • CloudBase database access has permissions
   • Default basic permissions include:
     • READONLY: Everyone can read, only creator/admin can write
     • PRIVATE: Only creator/admin can read/write
     • ADMINWRITE: Everyone can read, only admin can write (⚠️ NOT for Web SDK write!)
     • ADMINONLY: Only admin can read/write
     • CUSTOM: Fine-grained control with custom rules

2. Platform Compatibility (CRITICAL):

   • ⚠️ Web SDK cannot use ADMINWRITE or ADMINONLY for write operations
   • ✅ For user-generated content in Web apps, use CUSTOM rules
   • ✅ For admin-managed data (products, settings), use READONLY
   • ✅ Cloud functions have full access regardless of permission type

3. Configuration Workflow:

   Create collection → Configure security rules → Write code → Test

   • Use managePermissions(action="updateResourcePermission") to configure resource permissions
   • If permissions were just changed, retry after a few seconds (typically within ~30s). Do not blind-wait 2-5 minutes. If it still fails, re-check the actual rule shape and active client write pattern first — most failures are misconfigured rules, not cache.
   • See no-sql-web-sdk/security-rules.md for detailed resourceType="noSqlDatabase" examples only; do not treat doc._openid, auth.openid, query-subset validation, or create / update / delete JSON templates as generic rules for functions, storage, or SQL tables
   • Official references:
     • General security rules overview: https://cloud.tencent.com/document/product/876/41802
     • NoSQL database security rules: https://docs.cloudbase.net/database/security-rules
     • Cloud function security rules: https://docs.cloudbase.net/cloud-function/security-rules
     • Storage security rules: https://docs.cloudbase.net/storage/security-rules

Compatibility note:

• Canonical plugin name: permissions
• Legacy plugin aliases security-rule, security-rules, secret-rule, secret-rules, and access-control still resolve to the permissions plugin
• Legacy tools readSecurityRule / writeSecurityRule are removed; prefer queryPermissions / managePermissions

4. Common Scenarios:

   • E-commerce products: READONLY (admin manages via cloud functions)
   • Shopping carts: CUSTOM with auth.uid check (users manage their own)
   • Orders: CUSTOM with ownership validation
   • System logs: PRIVATE or ADMINONLY

5. Cross-Collection Operations:

   • Prefer security rules / RLS and client SDK when the permission model allows it
   • Use cloud functions when the operation needs elevated privileges, server secrets, or multi-collection logic that rules cannot express
   • For minimal Web demos (Todo / Notes / Kanban / 最小前后端), do not introduce cloud functions for CRUD — follow ../minimal-web-baas-demo/SKILL.md

Role Management (MCP)

CloudBase MCP provides role management via queryPermissions and managePermissions (CLI equivalent: tcb role). See each tool's schema for the full action list.

⚠️ CRITICAL: Role policies and resource permissions are two independent systems with NO automatic synchronization.

• Resource permissions (security rules) control access to specific resources (tables, collections, functions, storage)
• Roles (identity dimension) control policy bundles and member assignments

Query (queryPermissions): listRoles, getRole (by roleId / roleIdentity / roleName). Manage (managePermissions): createRole, updateRole, deleteRoles, addRoleMembers, removeRoleMembers, addRolePolicies, removeRolePolicies.

managePermissions(action="createRole", roleName="Developer", roleIdentity="developer",
                  policies=["FunctionsAccess"], memberUids=["user-uid-1"])

⚠️ Only custom roles can be deleted. System roles are read-only.

See also: CLI equivalent commands in cloudbase-cli/references/permission.md

3. Cloud Function Optimization:
   • Browser CRUD should not default to a cloud-function middleware layer; prefer @cloudbase/js-sdk → database (see ../minimal-web-baas-demo/SKILL.md)
   • When cloud functions are truly required, keep the count minimal and scope each function to secrets, elevated privilege, or background work

Data Models

1. Get Data Model Operation Object:

   • Mini Program: Need @cloudbase/wx-cloud-client-sdk, initialize const client = initHTTPOverCallFunction(wx.cloud), use client.models
   • Cloud Function: Need @cloudbase/node-sdk@3.10+, initialize const app = cloudbase.init({env}), use app.models
   • Web: Need @cloudbase/js-sdk, initialize const app = cloudbase.init({env}), after login use app.models

2. Data Model Query:

   • Can call MCP manageDataModel tool to:
     • Query model list
     • Get model detailed information (including Schema fields)
     • Get specific models SDK usage documentation

3. MySQL Data Model Invocation Rules:

   • MySQL data models cannot use collection method invocation, must use data model SDK
   • Wrong: db.collection('model_name').get()
   • Correct: app.models.model_name.list({ filter: { where: {} } })
   • Use manageDataModel tool's docs method to get specific SDK usage

Console Management

After creating/deploying resources, provide corresponding console links. All console URLs follow the pattern: https://tcb.cloud.tencent.com/dev?envId=${envId}#/{path} — replace ${envId} with the real EnvId resolved via queryEnv (resolve aliases first; see Environment and Authentication below), and resource names with actual values.

The CloudBase console is updated frequently. If a live, logged-in console shows a different hash path from this list, prefer the live console path over stale documentation and then update this skill to match.

Entry points (one line each)

• Overview: #/overview
• Template Center: #/cloud-template/market
• Document Database: #/db/doc · Collections #/db/doc/collection/${collectionName} · Models #/db/doc/model/${modelName}
• MySQL Database: #/db/mysql · Tables #/db/mysql/table/default/ (must be enabled in console first)
• PostgreSQL Database: #/db/postgres · Data editor #/db/postgres/data-editor · SQL editor #/db/postgres/sql-editor · Settings #/db/postgres/setting (instance spec, account password) · Tasks #/db/postgres/tasks (async task list: spec change, share-to-dedicated upgrade) · Backups #/db/postgres/backups · Migrations #/db/postgres/migrations
• Cloud Functions: #/scf · Detail #/scf/detail?id=${functionName}&NameSpace=${envId}
• CloudRun: #/platform-run (a per-environment capability that must be provisioned first — manageCloudRun(action="initEnv"), then poll queryCloudRun(action="envStatus") until normal; an env can exist without CloudRun, and in that case CloudRun APIs still return success with empty fields)
• Cloud Storage: #/storage
• AI+: #/ai
• Static Hosting: #/static-hosting (alt: https://console.cloud.tencent.com/tcb/hosting)
• Identity Authentication: #/identity · Login management #/identity/login-manage · Token management #/identity/token-management
• Weida Low-Code: #/lowcode/apps
• Logs & Monitoring: #/devops/log
• Environment Settings: #/env/env-setting (env info, QPS overage, preview state)
• HTTP Access: #/env/http-access (security domains, CORS, env vars, quotas)
• ICP Filing: #/env/filing-manage (whether this env qualifies as a filing resource: package tier, remaining validity > 6 months, CloudRun fixed IP; unmet items carry their own "renew" / "enable fixed IP" buttons)

For configuration pages (like login management), guide users through the setup process rather than only dropping a link.

Reference index

All packaged reference files (required for skill lint reachability):

• protocols/change-safety-protocol.md
• protocols/deployment-gate.md
• protocols/deployment-share.md
• protocols/sensitive-runtime-data-protection.md