/postgresql-development-cloudbase

name: postgresql-development-cloudbase
description: "Use when building, debugging, or evaluating CloudBase PostgreSQL / CloudBase PG / PG mode apps, including Postgres schema setup, queryPgDatabase/managePgDatabase, JS SDK v3 app.rdb() CRUD/RPC, PG HTTP API fallback, RLS-style permissions, username-password auth, and Web CMS/admin CRUD flows backed by CloudBase PG."
version: 2.36.1
license: MIT
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 PostgreSQL Development

Activation Contract

Use this first when

• The task says CloudBase PG, PostgreSQL, Postgres, PG mode, RLS, JS SDK v3 PostgreSQL, `app.rdb()`, `queryPgDatabase`, or `managePgDatabase`.
• A Web app or CMS must persist business data in CloudBase PostgreSQL.

Then also read

• Access-pattern design or slow-query work -> `../postgresql-best-practices-cloudbase/SKILL.md`
• Web auth provider readiness -> `../auth-tool-cloudbase/SKILL.md`
• Web login implementation -> `../auth-web-cloudbase/SKILL.md`
• General Web implementation and verification -> `../web-development/SKILL.md`
• Browser storage upload -> `../cloud-storage-web/SKILL.md`
• Raw HTTP API details only when SDK coverage is blocked -> `../http-api-cloudbase/SKILL.md`
• PG reference index -> `references/index.md`
• PG mode overview -> `references/pg-mode-overview.md`
• Auth / GRANT / RLS details -> `references/auth-and-rls.md`
• End-to-end PG app closure -> `references/app-workflow.md`
• PG storage details — **MUST read before writing any bucket / upload / URL code** -> `references/storage-pg.md`
• HTTP API fallback -> `references/http-api.md`
• Troubleshooting -> `references/troubleshooting.md`

Do NOT use first

• `relational-database-mcp-cloudbase` / `queryMysqlDatabase` / `manageMysqlDatabase` for new relational work. Those skills are only for an environment that already has MySQL.
• `cloudbase-document-database-web-sdk` / collection APIs for business data that must live in CloudBase PG.

Required Flow

🚨 CRITICAL: PG mode API is NOT the same as NoSQL

CloudBase PG (`app.rdb()`, `app.storage.from('bucket')`) uses **different API method names** than CloudBase NoSQL (`app.database()`, `app.uploadFile()`). Low-capability models often paste legacy NoSQL/auth snippets from training; reject that path immediately. If this task is PG-backed, **do not** write `app.database()`, `db.collection(...)`, `app.uploadFile()`, `getLoginState()`, or route guards based on `auth.getUser()`. Use `app.rdb()`, PG storage v3, and `auth.getSession()` instead. If you are used to writing `.where()`, `.orderBy()`, `.count()` from other ORMs or NoSQL — **stop and read the table below**.

| ❌ Do NOT use these (NoSQL / ORM habits) | ✅ Use these in PG mode | |------------------------------------------|------------------------| | `.where({ field: value })` | `.match({ field: value })` or `.eq("field", value)` | | `.where("field", "ilike", "%v%")` | `.ilike("field", "%v%")` | | `.orderBy("field", { ascending: false })` | `.order("field", { ascending: false })` | | `.count()` | `.select("*", { count: "exact" })` — count is in response | | `.offset(n)` | `.range(from, to)` | | `app.uploadFile()` (legacy NoSQL upload) | `app.storage.from('bucket').upload(key, file)` | | `app.getTempFileURL()` (legacy NoSQL URL) | `app.storage.from('bucket').createSignedUrl(key, expiresIn)` | | `app.storage.from()` (no bucket name) | `app.storage.from('bucket')` — **must** pass bucket name |

**If you find yourself typing `.where()` or `.orderBy()` or `.count()` — stop and use the correct method from the right column.**

0. **First, confirm this environment actually has PostgreSQL provisioned.** Call `queryEnv(action="info", envId=...)` and read the derived `EnvInfo.RuntimeBackends` block (`{ postgresql, nosql, mysql }`) along with `EnvInfo.RuntimeMode`. It is only safe to apply this skill's PG-specific guidance when `RuntimeBackends.postgresql === true` (equivalently, `EnvInfo.PostgreSQL` is non-empty AND/OR `EnvInfo.Meta` contains `postgresql=enable`).

• PG mode is a **new-environment mode** selected when creating a CloudBase environment with PostgreSQL. Do not try to "upgrade" a legacy environment in place; create/select a PG-mode environment instead.
• If `RuntimeBackends.postgresql === false`, STOP — this is a legacy NoSQL-only env: switch to `cloudbase-document-database-web-sdk` for browser data and `cloud-storage-web` (with `app.uploadFile()`) for uploads. Do not write `app.rdb()` code, do not enable RLS, do not create a pgstore bucket here.
• If both `postgresql` and `nosql` are `true` (the common case in a PG environment), they coexist. Apply this skill to NEW business data the task asks you to put in PG (e.g. articles / role tables explicitly described as PG). Existing NoSQL collections, the bucket reported in `EnvInfo.Storages[]`, and any `managePermissions(resourceType="noSqlDatabase")` rules continue to govern the legacy NoSQL data — do NOT migrate or rewrite them unless the task explicitly asks.
• Note: in a PG env, `EnvInfo.Storages[]` is the legacy NoSQL bucket. It still works for legacy `app.uploadFile()` flows but is NOT a usable pgstore bucket — never reuse it as the `<bucket>` segment in `app.storage.from('<bucket>').upload('<key>', file)`.

> **Creating a PG-mode environment** > > If step 0 shows `RuntimeBackends.postgresql === false` and you need PostgreSQL, create a new environment with PG enabled: > > - **Via MCP**: `manageEnv(action="create", alias="my-env", packageId="baas_personal", resources=["storage","function","postgresql"], confirm="yes")` — optional `region` (e.g. `region="ap-shanghai"`) selects whe