Skip to main content

PG Mode Overview

PG mode is a new way of running CloudBase environments, built on a Postgres-Native architecture. When you create a CloudBase environment and choose PostgreSQL database, the environment runs in PG mode automatically — PostgreSQL acts as the unified foundation of the infrastructure layer:

  • Authentication: user data lives in the PostgreSQL auth schema, so you can read the current user identity directly in SQL
  • Cloud storage: file metadata is stored in the PostgreSQL storage schema, with access controlled by RLS policies
  • PostgreSQL database: a ready-to-use PostgreSQL instance with full SQL capabilities, plus RESTful APIs exposed automatically through PostgREST
  • Permission system: a two-layer model combining table-level permissions (GRANT) and row-level permissions (RLS Policy), with the anon / authenticated / service_role database roles handling authorization. See architecture and permission model, data permission management, and the RLS policy patterns
  • Business data: you can keep using the document database, or store relational data in the PostgreSQL instance with RLS-based access control. To get started quickly, read the quickstart and the hands-on tutorial

Compared with the classic mode, the biggest difference is not "a different database" — it is that the infrastructure layer changes from separate subsystems into a unified runtime built on PostgreSQL. PG mode therefore fits scenarios that need strongly-typed modeling, relational queries, transactional consistency, and fine-grained row-level permissions.

tip

CloudBase PG mode environments are generally available. You can create a PG mode environment from the console and use it in production.

New environments only

PG mode is only available for newly created environments. Existing classic-mode environments cannot be upgraded. To use these capabilities, create a new environment and choose PostgreSQL database.

If you are on a classic-mode environment, see the classic mode overview to learn about its capabilities and how they differ.

Why Is It Called PG Mode?​

PG mode is not simply "adding a PostgreSQL instance to the existing environment". As described above, it changes the database access layer, the permission model, authentication, cloud storage, and access roles at the same time: PostgreSQL is not just a SQL database — it is the unified runtime foundation for identity, storage, permissions, and business data access.

Because these foundational capabilities are all rebuilt around PostgreSQL, we call it PG mode (built on the Postgres-Native architecture), to distinguish it from the classic running mode of CloudBase and to highlight PostgreSQL as the first-class citizen of the whole environment runtime.

Architecture​

In PG mode, client requests reach the database through a unified authentication and policy-checking chain:

Client (Web / Mini Program / Cloud Function)
   │  Authorization: Bearer <Token>
   │  (Publishable Key / access_token / API Key)
   ▼
CloudBase gateway
   │  Parses the JWT → sets role + request.jwt.claims
   ▼
PostgREST (automatic RESTful API)
   ▼
PostgreSQL
   ├─ Layer 1: table-level permission check (GRANT ... TO <role>)
   ├─ Layer 2: RLS policy filtering (USING / WITH CHECK)
   └─ schemas:
       ├─ auth     account system (users, etc.)
       ├─ storage  cloud storage metadata (buckets / objects)
       └─ public   business tables

Double-lock principle: an operation succeeds only when both the table-level GRANT and the RLS policy allow it. If either layer rejects the request, a permission error is returned.

Key Capabilities​

CapabilityDescription
Full SQL supportNative PostgreSQL features: tables, views, foreign keys, indexes, transactions, triggers, stored procedures, CTEs, window functions, and more
PostgREST RESTful APIRESTful endpoints generated from your schema, with filtering, sorting, pagination, relational queries, and RPC calls
Two-layer permission modelTable-level GRANT plus row-level RLS — permissions are SQL, sharing the same language and semantics as business queries
Cloud storage integrationFile read/write permissions are enforced by RLS, fully consistent with table permissions
Authentication integrationAccount data lives in the database auth schema, so you can read the current user identity in SQL through JWT claims
Rich extension ecosystemAvailable extensions include pgvector (vector search), vectorscale (DiskANN vector index), tencentdb_ai (Tencent Cloud AI), zhparser / pg_jieba (Chinese tokenization), TimescaleDB (time series), Apache AGE (graph), PL/V8 (JavaScript stored procedures), and more

When to Use PG Mode​

PG mode is recommended for:

  • Business systems that need complex relational queries and transactional consistency
  • Applications that need row-level data permissions (multi-tenant and SaaS applications, for example)
  • Teams that want to expose data to front ends, third-party systems, or low-code platforms through standard REST APIs
  • AI and search applications that rely on the SQL ecosystem (pgvector for vector search, pg_jieba for Chinese full-text search, and so on)
  • Developers who want AI coding assistants (Cursor, CodeBuddy, Claude Code, etc.) to build full-stack features smoothly — permissions are SQL, so the assistant never switches context

Next Steps​