连接数据库

CloudBase PostgreSQL 支持通过 SDK、HTTP API，以及兼容 PostgreSQL 协议的客户端访问数据库。不同连接方式适合不同场景，建议先根据运行环境选择访问路径。

选择连接方式

连接方式	适用场景	说明
小程序 ClientSDK	微信小程序前端直接读写数据	适合轻量业务逻辑，必须配合基础权限控制数据边界
JS SDK	Web 应用前端访问	适合用户态数据访问，同样需要开启 RLS 策略
HTTP API	App、服务端、低代码平台或第三方系统	基于 PostgREST 协议，适合跨语言集成
PostgreSQL 协议直连	云函数、云托管、后端服务	适合复杂 SQL、事务、批处理和连接池场景

前端访问

前端访问包括小程序 ClientSDK 和 Web JS SDK。前端请求会携带用户身份，数据库可以通过 auth.uid() 在 RLS 策略中识别当前用户。

前端访问适合用户只能访问自己数据的场景，例如任务列表、个人资料、订单草稿等。生产环境中不要只依赖前端参数做权限判断，应在数据库中开启 RLS。

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

const app = cloudbase.init({
  env: "<envId>",
  // 可选：传入 Publishable Key，未显式登录时会以 anon 身份访问
  accessKey: "<Publishable Key>",
});

const auth = app.auth;

// 示例使用匿名登录；也可以换成账号密码、短信或第三方登录
await auth.signInAnonymously();

const db = app.rdb();

const { data, error } = await db
  .from("todos")
  .select("id,title,is_completed")
  .eq("is_completed", false);

if (error) {
  throw error;
}

具体 SDK 语法请参考 JS SDK。

HTTP API 访问

HTTP API 适合非 JavaScript 环境或服务间调用。基础域名格式为 https://<envId>.api.tcloudbasegateway.com，通过资源路径访问表或 RPC 函数。

调用时需要在 Authorization 请求头中传入 Bearer <token>。<token> 可以是登录后获取的 access_token、Publishable Key 或 API Key；API Key 拥有服务端权限，不能暴露在前端。

# 匿名登录，获取 access_token
curl -X POST "https://<envId>.api.tcloudbasegateway.com/auth/v1/signin/anonymously" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X GET 'https://<envId>.api.tcloudbasegateway.com/v1/rdb/rest/todos?select=id,title,is_completed&is_completed=eq.false' \
  -H 'Authorization: Bearer <access_token>'

查询、插入、更新、删除和 RPC 调用示例请参考查询数据、新增数据和调用 RPC。

服务端直连

云函数、云托管或自有后端可以使用 PostgreSQL 协议直连数据库。服务端直连适合需要事务、复杂 SQL、批量写入或数据库连接池的场景。

import pg from "pg";

const pool = new pg.Pool({
  host: process.env.PGHOST,
  port: Number(process.env.PGPORT || 5432),
  database: process.env.PGDATABASE,
  user: process.env.PGUSER,
  password: process.env.PGPASSWORD,
  ssl: { rejectUnauthorized: false },
  max: 5,
});

const { rows } = await pool.query("select id, title from todos limit 20");

在 serverless 场景中，应复用全局连接池，避免每次请求都新建连接。连接池大小需要结合并发量、实例数和数据库最大连接数评估。是否需要启用 SSL 以及证书校验方式，以控制台展示的连接要求为准。

账号与网络

数据库连接地址、端口、账号和密码以云开发控制台实际展示为准。建议为业务服务创建独立账号，并按最小权限授予表、函数或 schema 访问能力。

如果后端部署在 CloudBase 云函数或云托管中，优先使用内网或同地域访问路径。需要公网访问时，应限制账号权限，并妥善保管连接信息。

安全建议

前端访问必须配置 RLS，不要把管理员账号或数据库密码放到客户端。
服务端账号密码放在环境变量或密钥管理中，不要提交到代码仓库。
生产环境建议使用 SSL 连接，并限制账号可访问的 schema、表和函数。
高并发场景使用连接池或连接复用，避免连接数耗尽。

选择连接方式​

前端访问​

HTTP API 访问​

服务端直连​

账号与网络​

安全建议​