CloudBase environment overview

A CloudBase environment is the unit of resource isolation and billing in CloudBase. One environment contains a full, independent set of databases, cloud storage, cloud functions, CloudBase Run services, authentication, AI capabilities, and quotas. Data is fully isolated between environments.

Core concepts

Concept	Description
Environment ID	A globally unique identifier, required for SDK initialization and API calls

What an environment contains

• Database: a PostgreSQL database (chosen at creation; the environment then runs in PG mode automatically). To use document database capabilities, enable the Document plugin in the PostgreSQL database
• Cloud storage: object storage + CDN acceleration
• Compute: cloud functions (FaaS), CloudBase Run (containers)
• Static website hosting: deploy frontend build artifacts in one step
• HTTP gateway: expose cloud functions / CloudBase Run as public HTTP endpoints
• Authentication: user management, login methods, JWT issuance
• AI: large language models, knowledge bases, Agents

Environment running modes: PG mode vs. classic mode

A CloudBase environment has two running modes: if you choose a PostgreSQL database, the environment runs in PG mode; if not, it runs in classic mode. The differences between the two modes are as follows:

• PG mode: authentication, cloud storage, and the permission model are all carried by PostgreSQL and expressed in SQL (GRANT + RLS). Business data can continue to use the document database, or use the same PostgreSQL instance to store relational data
• Classic mode: authentication, cloud storage, and the permission model run as independent subsystems; the database provides a document database by default

Further reading

If you are evaluating or preparing to use PostgreSQL database capabilities, continue with the PG mode overview to learn how authentication, cloud storage, and the permission model are carried by PostgreSQL, and how the document database and PostgreSQL coexist.

Running mode constraints

PG mode is only available for newly created environments; existing environments cannot be upgraded, and the mode cannot be switched

How to identify an environment's running mode

Call the DescribeEnvs API and check whether the returned EnvInfo contains the PostgreSQL field:

• The PostgreSQL array is not empty (contains instance information) → the environment runs in PG mode
• The PostgreSQL field is empty or absent → the environment runs in classic mode

// PG environment example (the PostgreSQL field is not empty)
{
  "EnvInfo": {
    "EnvId": "your-env-id",
    "PostgreSQL": [
      {
        "InstanceName": "postgres-xxxxxxx",
        "Name": "postgres",
        "Region": "ap-shanghai",
        "Status": 1,
        "Version": "17.6"
      }
    ]
  }
}

Comparison of the two running modes

Dimension	Classic mode	PG mode
Account system	Authentication runs as an independent module, decoupled from the database permission model	Account data is stored in the auth schema; account information is tied to the PostgreSQL permission model, and JWT claims can be read directly in SQL
Cloud storage permissions	Access to storage is controlled by separate security rules	Centrally controlled by PostgreSQL RLS policies, consistent with the database permission model
Data permission model	The document database controls access with security rules	PostgreSQL controls access with GRANT (table level) + RLS (row level)
Access roles	Access is decided by CloudBase identity and security rules	Supports three access roles: anon / authenticated / service_role

Next steps

• PG mode overview — an in-depth look at PG mode
• PostgreSQL database overview
• Document database overview — getting started with the document database
• Create a CloudBase environment