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 read EnvInfo.RuntimeBackends. If postgresql === true AND the task asks for a new business table to live in PG, switch to the postgresql-development-cloudbase skill for that table: it goes through app.rdb(), uses PG row-level security (CREATE POLICY), and uploads via app.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.js already has cloudbase.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
CUSTOM security rule to take effect immediately after you call managePermissions(updateResourcePermission). The backend caches rule evaluators for 2–5 minutes; first writes after a rule change may silently fail or be rejected with DATABASE_PERMISSION_DENIED even 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 reading result.code / result.message on every write and by doing a get() round-trip on the just-written _id; do not treat a resolved promise as success. See security-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-level result._id, not result.id, result.data.id, or result.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 a CUSTOM rule that reads role from user_roles by auth.uid and combines it with doc.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 / db instance.
- 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 unless the framework truly requires it.
Quick routing
- CRUD ->
./crud-operations.md
- Complex queries ->
./complex-queries.md
- Pagination ->
./pagination.md
- Aggregation ->
./aggregation.md
- Realtime listeners ->
./realtime.md
- Geolocation ->
./geolocation.md
- Security rules ->
./security-rules.md
Working rules for a coding agent
Start from the auth model
- If the page relies on logged-in user identity, read the Web auth skill before writing database code.
Keep browser code browser-native
- Use
app.database() and collection references.
- Do not mix in MCP management flows or SQL mental models.
Respect security rules
- Collection rules can reject requests before data is read.
- If the requirement is simple owner-only write access,
READONLY can be enough.
- If the requirement is “app-level admin can edit/delete all, editor only own”, use a
CUSTOM rule. A validated CMS pattern is get('database.user_roles.' + auth.uid).role == 'admin' || doc.authorId == auth.uid.
- For that CMS pattern, frontend writes can stay on
.doc(id).update() / .doc(id).remove().
- Reuse whichever role collection already exists and can be addressed by
_id == auth.uid. In this CMS pattern, user_roles keyed by uid is acceptable.
- If the task fails with permission issues, inspect the rule model rather than assuming the query syntax is wrong.
Return user-friendly errors
- Database errors must become readable UI or application errors, not silent failures.
- For writes, do not treat a resolved promise as success by default. Check write result fields such as
updated / deleted or surfaced code / message.
Persist IDs from create operations correctly
- For Web SDK
.add(...), the newly created document ID is result._id.
- Do not look for the ID under
result.id, result.data, or other driver-specific fields.
Quick examples
Simple query
const result = await db.collection("todos")
.where({ completed: false })
.get();
Create and capture document ID
const result = await db.collection("posts").add({
title: "New article",
content: "...",
createdAt: new Date()
});
const articleId = result._id;
Ordered pagination
const result = await db.collection("posts")
.orderBy("createdAt", "desc")
.skip(20)
.limit(10)
.get();
Field selection
const result = await db.collection("users")
.field({ name: true, email: true, _id: false })
.get();
Best practices
- Define collection-level types or model wrappers in the app code.
- Use meaningful collection naming conventions.
- Select only required fields.
- Add indexes for frequent filters or sort keys.
- Pair frontend CRUD with explicit permission design.
- Use pagination instead of unbounded reads.
Error handling
try {
const result = await db.collection("todos").get();
console.log(result.data);
} catch (error) {
console.error("Database error:", error);
}
When the SDK returns an operation result, check error indicators and translate them into readable application behavior.
1---
2name: cloudbase-document-database-web-sdk-2
3description: 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.
4version: 2.32.5
5alwaysApply: false
6metadata:
7 source: https://skillmd.com/skills/ahang1598/cloudbase-document-database-web-sdk-2
8---
9
10## Sibling skills (local only)
11
12Sibling CloudBase skills ship beside this skill. Use local relative paths such as `../auth-tool-cloudbase/SKILL.md`.
13
14If 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.
15
16# CloudBase Document Database Web SDK
17
18## Activation Contract
19
20### Use this first when
21
22- A browser or Web app must read or write CloudBase document database data through `@cloudbase/js-sdk`.
23- The request mentions `app.database()`, `db.collection()`, `.where()`, `.watch()`, pagination, aggregation, or geolocation queries in a Web frontend.
24
25### Read before writing code if
26
27- The task is clearly browser-side, but you still need to decide between Web SDK, Mini Program SDK, or backend access.
28- The request touches login state, collection permissions, or realtime updates.
29
30### Then also read
31
32- Web login and caller identity -> `../auth-web-cloudbase/SKILL.md`
33- General Web app structure -> `../web-development/SKILL.md`
34- Mini Program database code -> `../cloudbase-document-database-in-wechat-miniprogram/SKILL.md`
35
36### Do NOT use for
37
38- Mini Program code using `wx.cloud.database()`.
39- Server-side or cloud-function database access.
40- SQL / MySQL database operations.
41- Pure resource-permission administration with no browser SDK code.
42- **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 read `EnvInfo.RuntimeBackends`. If `postgresql === true` AND the task asks for a new business table to live in PG, switch to the `postgresql-development-cloudbase` skill for that table: it goes through `app.rdb()`, uses PG row-level security (`CREATE POLICY`), and uploads via `app.storage.from('<bucket>').upload('<key>', file)` against an explicitly-created pgstore bucket.
43 - 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".
44
45### SDK Code vs MCP Tools
46
47**When to write SDK code (use this skill):**
48- The task explicitly asks to "modify code" or "use SDK"
49- The task asks to implement app/frontend logic
50- The task mentions specific SDK methods like `db.collection().add()`, `.get()`, `.update()`
51- The context shows an existing Web project with SDK initialization (e.g., `index.js` already has `cloudbase.init()`)
52
53**When to use MCP tools instead:**
54- The task asks to manage CloudBase resources (create collection, set permissions, etc.)
55- The task involves admin/management operations without writing app code
56- The task mentions tools like `writeNoSqlDatabaseContent`, `managePermissions`, etc.
57
58**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.
59
60### Common mistakes / gotchas
61
62- Querying before the user is signed in when the collection rules require identity.
63- Using `wx.cloud.database()` or Node SDK patterns in browser code.
64- Initializing CloudBase lazily with dynamic imports instead of a shared synchronous app instance.
65- Treating security rules as result filters rather than request validators.
66- **Expecting a `CUSTOM` security rule to take effect immediately after you call `managePermissions(updateResourcePermission)`.** The backend caches rule evaluators for **2–5 minutes**; first writes after a rule change may silently fail or be rejected with `DATABASE_PERMISSION_DENIED` even 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 reading `result.code` / `result.message` on every write and by doing a `get()` round-trip on the just-written `_id`; do not treat a resolved promise as success. See `security-rules.md` → "Propagation And Verification" for the full pattern.
67- Misreading the return shape of `db.collection(...).add(...)`. In the CloudBase Web SDK, the created document ID is exposed at top-level `result._id`, not `result.id`, `result.data.id`, or `result.insertedId`.
68- 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 a `CUSTOM` rule that reads role from `user_roles` by `auth.uid` and combines it with `doc.authorId == auth.uid`, while frontend writes can stay on `.doc(id).update()` / `.doc(id).remove()`.
69- Forgetting pagination or indexes for larger collections.
70
71### Minimal checklist
72
73- Confirm this is browser-side document database work.
74- Initialize CloudBase once and reuse the same `app` / `db` instance.
75- Verify auth expectations before CRUD.
76- Read the right companion reference file for the specific operation.
77
78## Overview
79
80This skill covers **browser-side document database usage** via `@cloudbase/js-sdk`.
81
82Use it for:
83
84- CRUD in a Web app
85- complex queries and pagination
86- aggregation
87- realtime listeners with `watch()`
88- geolocation queries
89
90## Canonical initialization
91
92```javascript
93import cloudbase from "@cloudbase/js-sdk";
94
95const app = cloudbase.init({
96 env: "your-env-id"
97});
98
99const db = app.database();
100const _ = db.command;
101```
102
103Important rules:
104
105- Sign in before querying if the collection rules require identity.
106- Keep a single shared app/database instance.
107- Do not hide initialization inside ad-hoc async loaders unless the framework truly requires it.
108
109## Quick routing
110
111- CRUD -> `./crud-operations.md`
112- Complex queries -> `./complex-queries.md`
113- Pagination -> `./pagination.md`
114- Aggregation -> `./aggregation.md`
115- Realtime listeners -> `./realtime.md`
116- Geolocation -> `./geolocation.md`
117- Security rules -> `./security-rules.md`
118
119## Working rules for a coding agent
120
1211. **Start from the auth model**
122 - If the page relies on logged-in user identity, read the Web auth skill before writing database code.
123
1242. **Keep browser code browser-native**
125 - Use `app.database()` and collection references.
126 - Do not mix in MCP management flows or SQL mental models.
127
1283. **Respect security rules**
129 - Collection rules can reject requests before data is read.
130 - If the requirement is simple owner-only write access, `READONLY` can be enough.
131 - If the requirement is “app-level admin can edit/delete all, editor only own”, use a `CUSTOM` rule. A validated CMS pattern is `get('database.user_roles.' + auth.uid).role == 'admin' || doc.authorId == auth.uid`.
132 - For that CMS pattern, frontend writes can stay on `.doc(id).update()` / `.doc(id).remove()`.
133 - Reuse whichever role collection already exists and can be addressed by `_id == auth.uid`. In this CMS pattern, `user_roles` keyed by uid is acceptable.
134 - If the task fails with permission issues, inspect the rule model rather than assuming the query syntax is wrong.
135
1364. **Return user-friendly errors**
137 - Database errors must become readable UI or application errors, not silent failures.
138 - For writes, do not treat a resolved promise as success by default. Check write result fields such as `updated` / `deleted` or surfaced `code` / `message`.
139
1405. **Persist IDs from create operations correctly**
141 - For Web SDK `.add(...)`, the newly created document ID is `result._id`.
142 - Do not look for the ID under `result.id`, `result.data`, or other driver-specific fields.
143
144## Quick examples
145
146### Simple query
147
148```javascript
149const result = await db.collection("todos")
150 .where({ completed: false })
151 .get();
152```
153
154### Create and capture document ID
155
156```javascript
157const result = await db.collection("posts").add({
158 title: "New article",
159 content: "...",
160 createdAt: new Date()
161});
162
163const articleId = result._id;
164```
165
166### Ordered pagination
167
168```javascript
169const result = await db.collection("posts")
170 .orderBy("createdAt", "desc")
171 .skip(20)
172 .limit(10)
173 .get();
174```
175
176### Field selection
177
178```javascript
179const result = await db.collection("users")
180 .field({ name: true, email: true, _id: false })
181 .get();
182```
183
184## Best practices
185
1861. Define collection-level types or model wrappers in the app code.
1872. Use meaningful collection naming conventions.
1883. Select only required fields.
1894. Add indexes for frequent filters or sort keys.
1905. Pair frontend CRUD with explicit permission design.
1916. Use pagination instead of unbounded reads.
192
193## Error handling
194
195```javascript
196try {
197 const result = await db.collection("todos").get();
198 console.log(result.data);
199} catch (error) {
200 console.error("Database error:", error);
201}
202```
203
204When the SDK returns an operation result, check error indicators and translate them into readable application behavior.