cloudbase-document-database-web-sdk
Use CloudBase document database Web SDK only for confirmed NoSQL collection work. Query, create, update, and delete document data; if the task mentions PostgreSQL / CloudBase PG / app.rdb(), route to postgresql-development instead.
TencentCloudBase · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add TencentCloudBase/cloudbase-skills --skill cloudbase-document-database-web-sdk技能说明
name: cloudbase-document-database-web-sdk description: Use CloudBase document database Web SDK only for confirmed NoSQL collection work. Query, create, update, and delete document data; if the task mentions PostgreSQL / CloudBase PG / app.rdb(), route to postgresql-development instead. version: 2.33.2 alwaysApply: false
Sibling skills (local only)
Sibling CloudBase skills ship beside this skill. Use local relative paths such as ../auth-tool-cloudbase/SKILL.md.
If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do not HTTP-fetch remote skill or protocol markdown into the agent context.
CloudBase Document Database Web SDK
Activation Contract
Use this first when
- A browser or Web app must read or write CloudBase document database data through
@cloudbase/js-sdk. - The request mentions
app.database(),db.collection(),.where(),.watch(), pagination, aggregation, or geolocation queries in a Web frontend.
Read before writing code if
- The task is clearly browser-side, but you still need to decide between Web SDK, Mini Program SDK, or backend access.
- The request touches login state, collection permissions, or realtime updates.
Then also read
- Web login and caller identity ->
../auth-web-cloudbase/SKILL.md - General Web app structure ->
../web-development/SKILL.md - Mini Program database code ->
../cloudbase-document-database-in-wechat-miniprogram/SKILL.md
Do NOT use for
- Mini Program code using
wx.cloud.database(). - Server-side or cloud-function database access.
- SQL / MySQL database operations.
- Pure resource-permission administration with no browser SDK code.
- NEW business tables that the task explicitly asks to put in CloudBase PostgreSQL (CloudBase PG). Before applying this skill, call
envQuery(action="info", envId=...)and readEnvInfo.RuntimeBackends. Ifpostgresql === trueAND the task asks for a new business table to live in PG, switch to thepostgresql-development-cloudbaseskill for that table: it goes throughapp.rdb(), uses PG row-level security (CREATE POLICY), and uploads viaapp.storage.from('<bucket>').upload('<key>', file)against an explicitly-created pgstore bucket.- Existing NoSQL collections in the same env keep using THIS skill — PG and NoSQL coexist in CloudBase PG environments. The rule is "follow the task / existing surface", not "PG env forbids NoSQL".
SDK Code vs MCP Tools
When to write SDK code (use this skill):
- The task explicitly asks to "modify code" or "use SDK"
- The task asks to implement app/frontend logic
- The task mentions specific SDK methods like
db.collection().add(),.get(),.update() - The context shows an existing Web project with SDK initialization (e.g.,
index.jsalready hascloudbase.init())
When to use MCP tools instead:
- The task asks to manage CloudBase resources (create collection, set permissions, etc.)
- The task involves admin/management operations without writing app code
- The task mentions tools like
writeNoSqlDatabaseContent,managePermissions, etc.
Key distinction: If the user says "使用 JS SDK 执行 XX 操作" (use JS SDK to perform XX operation) or "修改代码" (modify code), write SDK code in the project files. Do not use MCP database write tools for app-level data operations.
Common mistakes / gotchas
- Querying before the user is signed in when the collection rules require identity.
- Using
wx.cloud.database()or Node SDK patterns in browser code. - Initializing CloudBase lazily with dynamic imports instead of a shared synchronous app instance.
- Treating security rules as result filters rather than request validators.
- Expecting a
CUSTOMsecurity rule to take effect immediately after you callmanagePermissions(updateResourcePermission). The backend caches rule evaluators for 2–5 minutes; first writes after a rule change may silently fail or be rejected withDATABASE_PERMISSION_DENIEDeven when the expression is correct. Either (a) wait a few minutes and retry the same write before assuming the rule is wrong, or (b) verify the rule is live by readingresult.code/result.messageon every write and by doing aget()round-trip on the just-written_id; do not treat a resolved promise as success. Seesecurity-rules.md→ "Propagation And Verification" for the full pattern. - Misreading the return shape of
db.collection(...).add(...). In the CloudBase Web SDK, the created document ID is exposed at top-levelresult._id, notresult.id,result.data.id, orresult.insertedId. - For CMS-style collections that need app-level admin users to edit/delete all records while editors can only edit/delete their own records, do not oversimplify the rule to
READONLY. A validated pattern is aCUSTOMrule that reads role fromuser_rolesbyauth.uidand combines it withdoc.authorId == auth.uid, while frontend writes can stay on.doc(id).update()/.doc(id).remove(). - Forgetting pagination or indexes for larger collections.
Minimal checklist
- Confirm this is browser-side document database work.
- Initialize CloudBase once and reuse the same
app/dbinstance. - Verify auth expectations before CRUD.
- Read the right companion reference file for the specific operation.
Overview
This skill covers browser-side document database usage via @cloudbase/js-sdk.
Use it for:
- CRUD in a Web app
- complex queries and pagination
- aggregation
- realtime listeners with
watch() - geolocation queries
Canonical initialization
import cloudbase from "@cloudbase/js-sdk";
const app = cloudbase.init({
env: "your-env-id"
});
const db = app.database();
const _ = db.command;
Important rules:
- Sign in before querying if the collection rules require identity.
- Keep a single shared app/database instance.
- Do not hide initialization inside ad-hoc async loaders