relational-database-web-cloudbase

name	relational-database-web-cloudbase
description	Use when building frontend Web apps that talk to CloudBase Relational Database via @cloudbase/js-sdk – provides the canonical init pattern so you can then use Supabase-style queries from the browser.
alwaysApply	false

When to use this skill

Use this skill whenever you need to access CloudBase Relational Database from a browser app (React, Vue, vanilla JS) using @cloudbase/js-sdk.

Use it when you need to:

• Initialize CloudBase Relational Database on the frontend
• Replace an existing Supabase client with CloudBase Relational Database
• Share a single db client across your Web app

Do NOT use this skill for:

• Backend/Node access to CloudBase Relational Database (use relation-database-skill → node-sdk/quickstart.md)
• MCP/agent database management (use relation-database-skill → mcp-tools/mcp-guide.md)
• Auth flows (use the Web/Node/Auth skills instead)

How to use this skill (for a coding agent)

1. Confirm environment
   • Ask the user for:
     • env – CloudBase environment ID
2. Follow the initialization pattern in this file exactly
   • Only change values like env, never the object shape.
3. After initialization, use Supabase knowledge for queries
   • Treat db as a Supabase client – method names and patterns are identical.
4. Avoid re-initializing CloudBase
   • Create a single shared db client and reuse it across components.

---

Installation

npm install @cloudbase/js-sdk

Initialization pattern (canonical)

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

const app = cloudbase.init({
  env: "your-env-id", // CloudBase environment ID
});

const auth = app.auth();
// Handle user authentication separately (Web Auth skill)

const db = app.rdb();
// Use db exactly like a Supabase client

Initialization rules (Web, @cloudbase/js-sdk):

• Always use synchronous initialization with the pattern above
• Do not lazy-load the SDK with import("@cloudbase/js-sdk")
• Do not wrap SDK initialization in async helpers such as initCloudBase() with internal initPromise caches
• Create a single shared db client and reuse it instead of re-initializing

Rules:

• Do not invent new properties on the cloudbase.init options.
• Always call app.rdb() to get the database client; app is not the DB client.

---

Scenario 1: Replace Supabase client in a React app

// lib/db.js (shared database client)
import cloudbase from "@cloudbase/js-sdk";

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

export const db = app.rdb();

// hooks/usePosts.js
import { useEffect, useState } from "react";
import { db } from "../lib/db";

export function usePosts() {
  const [posts, setPosts] = useState([]);

  useEffect(() => {
    async function fetchPosts() {
      const { data } = await db.from("posts").select("*");
      setPosts(data || []);
    }
    fetchPosts();
  }, []);

  return { posts };
}

---

Scenario 2: Basic query pattern (Supabase-style)

// Fetch latest posts
const { data, error } = await db
  .from("posts")
  .select("*")
  .order("created_at", { ascending: false });

if (error) {
  console.error("Failed to load posts", error.message);
}

---

Scenario 3: Insert / update / delete rows

// Insert
await db.from("posts").insert({ title: "Hello" });

// Update
await db.from("posts").update({ title: "Updated" }).eq("id", 1);

// Delete
await db.from("posts").delete().eq("id", 1);

---

Key principle: CloudBase Relational Database = Supabase API

• After you have db = app.rdb(), use Supabase documentation and patterns for all queries.
• This skill only standardizes Web initialization and client sharing.
• Do not duplicate Supabase docs into this skill; rely on the model's built-in Supabase knowledge for query shapes and options.