文档数据库：小程序 SDK

微信小程序中使用 CloudBase 文档数据库 SDK

如何使用

查看如何使用Skill了解详细的使用方法。

测试 Skill

你可以使用以下提示词来测试：

• "在微信小程序中使用 CloudBase 文档数据库实现数据查询和更新"
• "创建一个使用 CloudBase 文档数据库的小程序应用"

先完成 MCP 连接，再选择一个提示词开始你的 AI 原生开发之旅

安装与查看

如果需要安装全部 CloudBase Skills，可执行：

npx skills add tencentcloudbase/cloudbase-skills

如果只安装当前 Skill，可执行：

npx skills add https://github.com/tencentcloudbase/skills --skill cloudbase-document-database-in-wechat-miniprogram

当前 Skill 在线查看： cloudbase-document-database-in-wechat-miniprogram

---

Skill 规则原文

查看 SKILL.md 原文

## 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 WeChat Mini Program SDK

## Activation Contract

### Use this first when

- A WeChat Mini Program must access CloudBase document database through `wx.cloud.database()`.
- The request mentions Mini Program collection CRUD, pagination, aggregation, or geolocation queries.

### Read before writing code if

- The task is Mini Program database work but you still need to separate it from Web SDK, cloud functions, or SQL tasks.
- The request depends on built-in user identity, `_openid`, or Mini Program-side permissions.

### Then also read

- Mini Program project rules and CloudBase integration -> `../miniprogram-development/SKILL.md`
- Mini Program auth and identity flow -> `../auth-wechat-miniprogram/SKILL.md`
- Browser-side document database code -> `../cloudbase-document-database-web-sdk/SKILL.md`

### Do NOT use for

- Browser/Web code using `@cloudbase/js-sdk`.
- Server-side or cloud-function database access.
- MySQL / relational database work.

### Common mistakes / gotchas

- Copying Web SDK code into Mini Program pages.
- Manually writing `_openid` during create or update operations.
- Assuming built-in Mini Program identity means security rules can be ignored.
- Mixing collection CRUD and backend-wide admin workflows in the same client path.

### Minimal checklist

- Confirm the caller is a Mini Program page/component or Mini Program-side logic.
- Initialize `wx.cloud` correctly before database calls.
- Verify whether the collection rules rely on `auth.openid` / `_openid`.
- Read the specific companion reference file for the operation you need.

## Overview

This skill covers **Mini Program-side document database access** through `wx.cloud.database()`.

Use it for:

- collection CRUD in Mini Program pages
- query composition and pagination
- aggregation
- geolocation queries

Mini Program CloudBase access comes with built-in identity, but database operations are still constrained by collection permissions and security rules.

## Canonical initialization

```javascript
const db = wx.cloud.database();
const _ = db.command;
```

To target a specific environment:

```javascript
const db = wx.cloud.database({
  env: "test"
});
```

Important notes:

- Users are authenticated through the Mini Program CloudBase context.
- In cloud functions, caller identity is available through `wxContext.OPENID`.
- In client-side collection rules, ownership checks usually use `auth.openid` / `doc._openid`.

## Quick routing

- CRUD -> `./crud-operations.md`
- Complex queries -> `./complex-queries.md`
- Pagination -> `./pagination.md`
- Aggregation -> `./aggregation.md`
- Geolocation -> `./geolocation.md`
- Security rules -> `./security-rules.md`

## Working rules for a coding agent

1. **Keep Mini Program code Mini Program-native**
   - Use `wx.cloud.database()`.
   - Do not substitute browser SDK initialization patterns.

2. **Respect ownership fields**
   - `_openid` is system-managed for SDK writes.
   - Never set or override `_openid` manually in `.add()`, `.set()`, or `.update()` payloads.

3. **Remember that security rules validate requests**
   - If a rule requires ownership conditions, the query shape must match that rule model.
   - Permission errors usually mean the rule/query relationship is wrong, not only that the user is logged out.

4. **Route admin-style operations to backend flows**
   - If the task needs privileged global access, use backend tools or functions instead of exposing that path directly in Mini Program client code.

## Quick examples

### Basic collection access

```javascript
const todos = db.collection("todos");
const result = await todos.where({ completed: false }).get();
```

### Document reference

```javascript
const todo = db.collection("todos").doc("todo-id");
const result = await todo.get();
```

## Best practices

1. Create clear collection naming conventions.
2. Use typed wrappers or model helpers in app code where possible.
3. Design rules around real ownership and sharing patterns.
4. Use pagination instead of large unbounded reads.
5. Keep admin/operations logic in backend code, not Mini Program direct access.