关系型数据库（PostgreSQL）

版本提示

自 @cloudbase/manager-node@5.4.0 起新增此模块。通过 app.database 访问，提供在 PostgreSQL 架构的云开发环境上执行 SQL 语句及管理数据的能力。

---

初始化

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

const { database } = app

---

executePGSql

1. 接口描述

接口功能：在 PostgreSQL 环境上执行任意 SQL 语句（DDL / DML / DQL 等），并返回结果集与受影响行数。

接口声明：app.database.executePGSql(options): Promise<IExecutePGSqlResult>

2. 输入参数

IExecutePGSqlOptions

字段	必填	类型	说明
Sql	是	String	要执行的 SQL 语句
Role	否	String	指定 role 执行 SQL，可传任意有效的 role（包括用户自定义 role）。云开发内置了 cloudbase_read_only_user 只读角色，使用该角色执行 SQL 可避免非预期的写操作执行成功
EnvId	否	String	云开发环境 ID，不传则使用当前管理实例初始化时的 EnvId

3. 返回结果

IExecutePGSqlResult

字段	类型	说明
RequestId	String	请求唯一标识
AffectedRows	Number	受影响行数（DML 类语句有效）
Columns	String[] / null	字段名列表（SELECT 类语句返回）；无结果集时为 null
Rows	String[] / null	数据行列表，每一项是 JSON 串，反序列化后是 (string | null)[]，按 Columns 顺序对齐；无结果集时为 null
ExecutionTimeMs	Number	SQL 执行耗时（毫秒）

4. 示例代码

// 创建表
await database.executePGSql({
  Sql: 'CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT NOT NULL, email TEXT UNIQUE)'
})

// 插入数据
const insertRes = await database.executePGSql({
  Sql: "INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')"
})
console.log('受影响行数:', insertRes.AffectedRows) // 1

// 查询并解析结果
const res = await database.executePGSql({
  Sql: 'SELECT id, name, email FROM users WHERE id = 1'
})
console.log(res.Columns) // ['id', 'name', 'email']
const rows = (res.Rows || []).map(s => JSON.parse(s))
// rows: [['1', 'Alice', 'alice@example.com']]

// 使用云开发内置的只读 role 执行查询，避免非预期的写操作执行成功
const readonlyRes = await database.executePGSql({
  Role: 'cloudbase_read_only_user',
  Sql: 'SELECT id, name, email FROM users'
})
console.log(readonlyRes.Rows)

// 指定其他环境 ID 执行
await database.executePGSql({
  EnvId: 'other-env-id',
  Sql: 'SELECT NOW()'
})