Connect to your database

CloudBase PostgreSQL can be accessed through SDKs, HTTP APIs, and clients compatible with the PostgreSQL protocol. Choose the access method based on your runtime environment.

Choose a connection method

Method	Use case	Notes
Mini Program ClientSDK	Direct access from WeChat Mini Programs	Suitable for lightweight user data access. Use Basic permissions to enforce boundaries
JS SDK	Web app frontend access	Suitable for user-scoped access. RLS policies are required
HTTP API	Apps, servers, low-code platforms, or third-party systems	Based on PostgREST and suitable for cross-language integration
PostgreSQL protocol	Cloud Functions, CloudBase Run, backend services	Suitable for complex SQL, transactions, batch jobs, and connection pools

Frontend access

Frontend access includes the Mini Program ClientSDK and Web JS SDK. Frontend requests carry user identity, and the database can use auth.uid() in RLS policies to identify the current user.

Frontend access is suitable when users can only access their own data, such as task lists, profiles, or order drafts. Do not rely only on frontend parameters for authorization. Enable RLS in the database.

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

const app = cloudbase.init({
  env: "<envId>",
  // Optional: pass a Publishable Key so unauthenticated calls use the anon identity
  accessKey: "<Publishable Key>",
});

const auth = app.auth;

// Anonymous sign-in is shown here. You can also use password, SMS, or third-party sign-in.
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;
}

For SDK syntax, see JS SDK.

HTTP API access

The HTTP API is suitable for non-JavaScript environments and service-to-service calls. The base domain is https://<envId>.api.tcloudbasegateway.com, and resource paths are used to access tables or RPC functions.

Requests need Bearer <token> in the Authorization header. <token> can be an access_token obtained after sign-in, a Publishable Key, or an API Key. API Keys have server-side permissions and must never be exposed to the frontend.

# Anonymous sign-in to get an 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>'

For examples, see Query data, Insert data, and Call RPC.

Server-side direct connection

Cloud Functions, CloudBase Run, and custom backends can connect through the PostgreSQL protocol. Direct connections are suitable for transactions, complex SQL, batch writes, and connection pools.

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");

In serverless environments, reuse a global connection pool instead of creating connections on every request. Size the pool based on concurrency, instance count, and the database connection limit. Whether SSL is required and how certificates should be verified depend on the connection requirements shown in the console.

Accounts and network

Use the connection address, port, account, and password shown in the CloudBase console. Create separate accounts for application services and grant only the required schema, table, or function permissions.

If your backend runs in CloudBase Functions or CloudBase Run, prefer private or same-region access when available. For public access, restrict account permissions and protect connection information.

Security recommendations

• Frontend access must use RLS. Do not put admin accounts or database passwords in clients.
• Store server-side account passwords in environment variables or secret management systems.
• Use SSL in production and restrict the schemas, tables, and functions each account can access.
• Use connection pooling and reuse connections in high-concurrency scenarios to avoid exhausting connections.