cloudbase-document-database-web-sdk

兄弟スキル（ローカルのみ）

兄弟の CloudBase スキルは、このスキルと同じ場所に配置されています。../auth-tool-cloudbase/SKILL.md のようなローカル相対パスを使用してください。

参照されている兄弟スキルのファイルがこの環境にない場合は、CloudBase プラグイン一式（または不足しているスキル）のインストールをユーザーに依頼してください。リモートのスキルやプロトコルの Markdown を HTTP 経由で取得し、エージェントのコンテキストに読み込まないでください。

CloudBase ドキュメントデータベース Web SDK

有効化の条件

まずこのスキルを使う場合

• ブラウザーまたは Web アプリで、@cloudbase/js-sdk を通じて CloudBase ドキュメントデータベースのデータを読み書きする必要がある場合。
• リクエストで、Web フロントエンドにおける app.database()、db.collection()、.where()、.watch()、ページネーション、集計、または位置情報クエリについて言及されている場合。

コードを書く前に読む場合

• タスクが明らかにブラウザー側のものでも、Web SDK、ミニプログラム SDK、バックエンドアクセスのどれを使うか判断する必要がある場合。
• リクエストがログイン状態、コレクションの権限、またはリアルタイム更新に関わる場合。

あわせて読むもの

• Web のログインと呼び出し元の ID -> ../auth-web-cloudbase/SKILL.md
• Web アプリの全般的な構成 -> ../web-development/SKILL.md
• ミニプログラムのデータベースコード -> ../cloudbase-document-database-in-wechat-miniprogram/SKILL.md

使用しない場合

• wx.cloud.database() を使用するミニプログラムのコード。
• サーバー側またはクラウド関数からのデータベースアクセス。
• SQL／MySQL データベースの操作。
• ブラウザー SDK コードを含まない、リソース権限の管理のみを行う場合。
• タスクで CloudBase PostgreSQL（CloudBase PG）に配置するよう明示されている新しい業務テーブル。このスキルを適用する前に、queryEnv(action="info", envId=...) を呼び出し、EnvInfo.RuntimeBackends を確認してください。postgresql === true であり、かつタスクで PG に新しい業務テーブルを作成するよう求められている場合は、そのテーブルについて postgresql-development-cloudbase スキルに切り替えてください。この場合は app.rdb() を使い、PG の行レベルセキュリティ（CREATE POLICY）を適用し、明示的に作成した pgstore バケットに対して app.storage.from('<bucket>').upload('<key>', file) でアップロードします。
  • 同じ環境にある既存の NoSQL コレクションには、引き続きこのスキルを使用します。CloudBase PG 環境では PG と NoSQL が共存します。ルールは「PG 環境では NoSQL を使わない」ではなく、「タスクと既存の実装に従う」です。

SDK コードと MCP ツール

SDK コードを書く場合（このスキルを使用）：

• タスクで「コードを変更する」または「SDK を使う」と明示的に求められている場合。
• タスクでアプリやフロントエンドのロジック実装を求められている場合。
• db.collection().add()、.get()、.update() など、特定の SDK メソッドについて言及されている場合。
• 既存の Web プロジェクトに SDK の初期化処理があることがコンテキストからわかる場合（例：index.js に cloudbase.init() がすでにある）。

代わりに MCP ツールを使う場合：

• CloudBase リソースの管理（コレクションの作成、権限の設定など）を求められている場合。
• アプリコードを書かずに、管理操作を行うタスクの場合。
• writeNoSqlDatabaseContent、managePermissions などのツールについて言及されている場合。

重要な違い： ユーザーが「JS SDK を使用して XX 操作を実行する」または「コードを変更する」と言った場合は、プロジェクトファイルに SDK コードを書いてください。アプリレベルのデータ操作に MCP データベース書き込みツールを使用しないでください。

よくある間違い／注意点

• コレクションのルールで認証情報が必要なのに、ユーザーのサインイン前にクエリを実行すること。
• ブラウザーのコードで wx.cloud.database() や Node SDK のパターンを使用すること。
• 共有の同期的なアプリインスタンスではなく、動的インポートを使って CloudBase を遅延初期化すること。
• セキュリティルールをリクエストの検証ルールではなく、結果のフィルターとして扱うこと。
• managePermissions(updateResourcePermission) の呼び出し直後に CUSTOM セキュリティルールが有効になると期待すること。 バックエンドはルールの評価器を 2～5 分 キャッシュします。ルール変更後の最初の書き込みは、式が正しくても気付かないうちに失敗したり、DATABASE_PERMISSION_DENIED で拒否されたりする場合があります。ルールが間違っていると判断する前に、（a）数分待って同じ書き込みを再試行するか、（b）すべての書き込みで result.code／result.message を読み取り、書き込んだばかりの _id に対して get() の往復確認を行って、ルールが有効になっていることを検証してください。Promise が解決しただけで成功と判断しないでください。全体の手順については、security-rules.md →「Propagation And Verification」を参照してください。
• db.collection(...).add(...) の戻り値の形式を誤って解釈すること。CloudBase Web SDK では、作成されたドキュメント ID はトップレベルの result._id にあり、result.id、result.data.id、result.insertedId ではありません。
• アプリレベルの管理者ユーザーがすべてのレコードを編集／削除でき、編集者は自分のレコードのみ編集／削除できる必要がある CMS スタイルのコレクションで、ルールを READONLY に単純化しないでください。検証済みのパターンは、auth.uid を使って user_roles からロールを読み取り、doc.authorId == auth.uid と組み合わせる CUSTOM ルールです。フロントエンドでの書き込みは .doc(id).update()／.doc(id).remove() のままにできます。
• 大規模なコレクションでページネーションやインデックスを忘れること。

最小限のチェックリスト

• ブラウザー側のドキュメントデータベース操作であることを確認します。
• CloudBase を一度だけ初期化し、同じ app／db インスタンスを再利用します。
• CRUD の前に認証要件を確認します。
• 操作内容に合った補足リファレンスファイルを参照します。

概要

このスキルでは、@cloudbase/js-sdk を使ったブラウザー側のドキュメントデータベースの使用方法を扱います。

次の用途に使用します。

• Web アプリでの CRUD
• 複雑なクエリとページネーション
• 集計
• watch() を使ったリアルタイムリスナー
• 地理位置情報クエリ

標準的な初期化

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id"
});

const db = app.database();
const _ = db.command;

重要なルール：

• コレクションのルールで認証情報が必要な場合は、クエリの前にサインインします。
• 共有のアプリ／データベースインスタンスを 1 つだけ使用します。
• フレームワークで本当に必要な場合を除き、場当たり的な非同期ローダーの中に初期化を隠さないでください。

クイックルーティング

• CRUD → ./crud-operations.md
• 複雑なクエリ → ./complex-queries.md
• ページネーション → ./pagination.md
• 集計 → ./aggregation.md
• リアルタイムリスナー → ./realtime.md
• 地理位置情報 → ./geolocation.md
• セキュリティルール → ./security-rules.md

コーディングエージェント向けの作業ルール

1. 認証モデルから確認する

   • ページがログイン済みユーザーの ID に依存する場合は、データベースコードを書く前に Web 認証スキルを確認してください。

2. ブラウザーコードはブラウザー標準の方法で記述する

   • app.database() とコレクションの参照を使用してください。
   • MCP の管理フローや SQL の考え方を混在させないでください。

3. セキュリティルールを遵守する

   • コレクションルールによって、データが読み込まれる前にリクエストが拒否される場合があります。
   • 要件がシンプルなオーナーのみの書き込みアクセスであれば、READONLY で十分な場合があります。
   • 要件が「アプリレベルの管理者はすべて編集・削除でき、編集者は自分のデータのみ操作できる」であれば、CUSTOM ルールを使用してください。検証済みの CMS パターンは get(`database.user_roles.${auth.uid}`).role == 'admin' || doc.authorId == auth.uid です。
   • この CMS パターンでは、フロントエンドの書き込みに .doc(id).update() / .doc(id).remove() を引き続き使用できます。
   • 既存のロール用コレクションのうち、_id == auth.uid で参照できるものを再利用してください。この CMS パターンでは、uid をキーとする user_roles を使用できます。
   • 取得先のドキュメントが存在しない場合、get() はリクエストを HTTP 500 で失敗させます。false を返すわけではなく、|| によって評価がスキップされることもありません。アプリでユーザーごとのロールドキュメントを保証できない場合は、ロール一覧を 1 つの共有ドキュメントに保存し、代わりに auth.uid in get(`database.admin_registry.lock`).admins をテストしてください。
   • タスクで権限エラーが発生した場合は、クエリ構文が誤っていると決めつけず、ルールモデルを確認してください。

4. ユーザーにわかりやすいエラーを返す

   • データベースエラーは、無視せず、読みやすい UI またはアプリケーションエラーとして扱ってください。
   • 書き込みでは、Promise が解決しただけで成功と見なさないでください。updated / deleted などの書き込み結果フィールドや、返された code / message を確認してください。

5. 作成操作で ID を正しく保存する

   • Web SDK の .add(...) では、新しく作成されたドキュメントの ID は result._id です。
   • ID を result.id、result.data、その他のドライバー固有のフィールドから取得しないでください。

簡単な例

シンプルなクエリ

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

作成してドキュメント ID を取得する

const result = await db.collection("posts").add({
  title: "New article",
  content: "...",
  createdAt: new Date()
});

const articleId = result._id;

順序付きページネーション

const result = await db.collection("posts")
  .orderBy("createdAt", "desc")
  .skip(20)
  .limit(10)
  .get();

フィールドの選択

const result = await db.collection("users")
  .field({ name: true, email: true, _id: false })
  .get();

ベストプラクティス

1. アプリコードでコレクションレベルの型またはモデルラッパーを定義してください。
2. 意味が明確なコレクションの命名規則を使用してください。
3. 必要なフィールドのみを選択してください。
4. 頻繁に使用するフィルターやソートキーにはインデックスを追加してください。
5. フロントエンドの CRUD と明示的な権限設計を組み合わせてください。
6. 上限のない読み取りの代わりに、ページネーションを使用してください。

エラー処理

try {
  const result = await db.collection("todos").get();
  console.log(result.data);
} catch (error) {
  console.error("Database error:", error);
}

SDK が操作結果を返す場合は、エラーの指標を確認し、読みやすいアプリケーション動作に反映してください。