关系型数据库（PostgreSQL）

tcb db 命令集合提供对 CloudBase PostgreSQL 环境的 SQL 执行与 migration 变更管理能力。

tcb db execute：直接执行任意 SQL 语句（DDL / DML / DQL）。
tcb db pg migration <subcommand>：以文件形式管理 PostgreSQL schema 变更，支持创建、预览、执行、拉取、修复历史等操作。

`tcb db execute`

v3.4.0

tcb db execute 在 PostgreSQL 环境下的支持自 CLI v3.4.0 起提供。

执行 SQL 语句。常见场景包括执行高级 Storage bucket 管理和 RLS 策略管理。

tcb db execute --sql '<sql>' [options]

参数

参数	说明	默认值
`-s, --sql <sql>`	要执行的 SQL 语句	必填
`--role <role>`	指定执行 SQL 的 role（可为任意有效 role，含用户自定义 role）	—
`-e, --env-id <envId>`	环境 ID	必填
`--json`	以 JSON 格式输出结果	—

内置只读角色

云开发内置了 cloudbase_read_only_user 只读角色。通过 --role cloudbase_read_only_user 执行查询，可避免非预期的写操作执行成功。

示例

# 基础查询
tcb db execute -e <pgEnvId> --sql "SELECT 1"

# 查询 Storage bucket 列表
tcb db execute -e <pgEnvId> --sql "SELECT name, public FROM storage.buckets ORDER BY created_at"

# 使用内置只读角色执行查询，防止误操作
tcb db execute -e <pgEnvId> --role cloudbase_read_only_user --sql "SELECT name, public FROM storage.buckets"

# 创建 Storage bucket
tcb db execute -e <pgEnvId> --sql "INSERT INTO storage.buckets (id, name, public, created_at, updated_at) VALUES ('avatars', 'avatars', false, now(), now())"

`tcb db pg migration`

以文件形式在版本控制中管理 PostgreSQL schema 变更。命令集合覆盖创建、列表、拉取、执行、修复五个动作。

版本要求

tcb db pg migration 系列命令需要 @cloudbase/cli v3.7.0+。可通过 tcb -v 查看当前版本，通过 npm i -g @cloudbase/cli 升级到最新版。

目录结构与命名约定

本地 migration 目录固定为 cloudbase/migrations/（相对于命令执行时的工作目录）。
文件名格式：<version>_<name>.sql
- version：14 位 UTC 时间戳（YYYYMMDDHHmmss），由 migration new 自动生成。
- name：仅允许小写字母和下划线（如 create_users_table、add_index）。
目录不存在时会由 migration new 自动创建；migration up / migration repair 遇到目录缺失会直接报错。

全局约定

项	说明
`-e, --env-id <envId>`	除 `migration new` 外，其余子命令均需指定环境 ID
`--json`	全局选项，输出结构化 JSON，适合脚本 / CI 场景
登录态	所有子命令均会在执行前自动检查登录，未登录时会引导 `tcb login`

`tcb db pg migration new`

创建一个新的空 migration 文件，文件名前缀为当前 UTC 时间戳。

tcb db pg migration new <name>

参数

参数	说明	默认值
`<name>`	migration 名称，仅允许小写字母和下划线	必填

示例

# 创建空文件
tcb db pg migration new create_users_table

# 通过 stdin 直接写入 SQL 内容
echo "CREATE TABLE t(id int)" | tcb db pg migration new add_t

执行后会在 cloudbase/migrations/ 下生成类似 20260728141530_create_users_table.sql 的文件。若管道有输入，则 SQL 内容会写入该文件；否则生成空文件供后续编辑。

`tcb db pg migration list`

列出 PostgreSQL migration 状态，默认对比本地目录与远端已应用记录。

# 默认：本地 vs 远端对比
tcb db pg migration list -e <envId>

# 仅查询远端（可选分页）
tcb db pg migration list -e <envId> --remote-only [--limit <n>] [--offset <n>]

参数

参数	说明	默认值
`--remote-only`	仅查询远端已应用 migration，不扫描本地目录	`false`
`--limit <n>`	单页条数，取值范围 `[1, 500]`。仅在 `--remote-only` 下生效	`100`
`--offset <n>`	分页偏移。仅在 `--remote-only` 下生效	`0`
`-e, --env-id <envId>`	环境 ID	必填
`--json`	输出 JSON	—

分页参数只在 --remote-only 下有效

默认模式需要与本地目录做全量对比，会自动全量拉取远端 migration。在默认模式下传入 --limit / --offset 会直接报错。

示例

# 对比本地与远端
tcb db pg migration list -e <envId>

# JSON 格式输出，便于脚本消费
tcb db pg migration list -e <envId> --json

# 仅查看远端最新 200 条已应用 migration
tcb db pg migration list -e <envId> --remote-only --limit 200 --offset 0

输出为对齐两侧的三列表格 Local | Remote | Time (UTC)：只在本地或只在远端的行，会在对应列留空，便于快速识别未同步项。

`tcb db pg migration fetch`

从远端拉取已应用 migration 到本地目录。默认全量，也可传入 version 拉取单条。

# 全量拉取远端 migration
tcb db pg migration fetch -e <envId>

# 拉取单条
tcb db pg migration fetch <version> -e <envId>

参数

参数	说明	默认值
`[version]`	可选，14 位版本号；不传则拉全部	—
`-f, --force`	覆盖本地已存在的同名文件	`false`
`--dry-run`	仅预览将要写入的文件，不实际落盘	`false`
`-e, --env-id <envId>`	环境 ID	必填
`--json`	输出 JSON	—

示例

# 首次接入远端历史，把已应用 migration 全部拉到本地
tcb db pg migration fetch -e <envId>

# 拉取指定版本
tcb db pg migration fetch 20260724153000 -e <envId>

# 覆盖本地同名文件（以远端为准）
tcb db pg migration fetch -e <envId> --force

# 只看计划，不落盘
tcb db pg migration fetch -e <envId> --dry-run

已存在的本地文件默认会跳过（skipped），需要 --force 才会覆盖。

`tcb db pg migration up`

执行本地待应用 migration。命令内部会先调用 preview 生成执行计划，再提交 push 任务并轮询任务状态直到终态。

tcb db pg migration up -e <envId> [--dry-run] [--include-all]

参数

参数	说明	默认值
`--dry-run`	仅预览执行计划，不实际提交执行	`false`
`--include-all`	允许 out-of-order migrations（即接受版本号早于远端最新版本的 pending 项）	`false`
`-e, --env-id <envId>`	环境 ID	必填
`--json`	输出 JSON	—

示例

# 仅预览待执行 migration
tcb db pg migration up -e <envId> --dry-run

# 正常执行
tcb db pg migration up -e <envId>

# 允许 out-of-order（历史上有本地版本号早于线上最新版本时使用）
tcb db pg migration up -e <envId> --include-all

冲突处理

当出现 checksum_mismatch 时，可先执行 tcb db pg migration fetch <version> -e <envId> --force 同步远端内容，或用 migration repair 修正历史记录。

`tcb db pg migration repair`

修复远端 migration 历史记录，不执行 SQL。用于对齐本地与远端状态，例如手动补齐 history、标记回滚、修正 checksum 等。

tcb db pg migration repair <version> --status <applied|reverted> --reason <reason> -e <envId>

参数

参数	说明	默认值
`<version>`	14 位 migration 版本号	必填
`--status <status>`	目标状态：`applied` 或 `reverted`	必填
`--reason <reason>`	修复原因（用于审计）	必填
`--dry-run`	仅展示 repair 计划，不真正执行	`false`
`-e, --env-id <envId>`	环境 ID	必填
`--json`	输出 JSON	—

Name 自动推断

repair 不需要显式传入 Name，命令会按目标状态自动推断：

--status applied：从本地 cloudbase/migrations/ 目录中查找匹配 <version> 的文件，读取 SQL 作为修复内容。本地缺文件会直接报错。
--status reverted：从远端 history 查询该 version 的 Name，本地文件不参与。

示例

# 手动将本地 migration 标记为已应用（如在数据库中直接执行过该 SQL）
tcb db pg migration repair 20260724153000 --status applied --reason "manual_fix" -e <envId>

# 将远端 history 中的某条记录标记为已回滚
tcb db pg migration repair 20260724153000 --status reverted --reason "rollback_record" -e <envId>

# 先预览 repair 计划
tcb db pg migration repair 20260724153000 --status applied --reason "checksum_align" -e <envId> --dry-run

典型工作流

# 1. 首次接入：把远端历史 migration 全部拉到本地
tcb db pg migration fetch -e <envId>

# 2. 新增变更：创建一个 migration 文件并编辑
tcb db pg migration new create_orders_table
# 编辑 cloudbase/migrations/<version>_create_orders_table.sql，写入 SQL

# 3. 预览执行计划
tcb db pg migration up -e <envId> --dry-run

# 4. 实际执行
tcb db pg migration up -e <envId>

# 5. 校验状态
tcb db pg migration list -e <envId>

声明式部署（`database` 字段）

除了 tcb db pg migration 命令式管理，也可以在 cloudbaserc.json 中配置 database 字段，通过 tcb deploy 一键声明式执行数据库迁移。

属性	值
类型	`Object`
说明	数据库迁移配置，用于 `tcb deploy` 声明式执行 SQL 迁移（优先支持 SQL）

子字段：

字段	类型	必填	默认值	说明
`type`	String	是	—	数据库类型，目前仅支持 `postgresql`
`migrations`	String	否	`./cloudbase/migrations`	迁移文件目录（相对项目根，仅相对路径）。迁移文件推荐使用 `<14位时间戳>_<名称>.sql` 命名

示例：

{
  "database": {
    "type": "postgresql",
    "migrations": "./cloudbase/migrations"
  }
}

补充说明

type：数据库类型，当前仅支持 postgresql
migrations 迁移文件：
- 命名规范：<14位时间戳>_<名称>.sql，例 20240101120000_init.sql
- CLI 按文件名字典序升序执行（时间戳保证顺序）
- 执行成功的文件记录在 __migrations 表中，不会重复执行
- 不支持自动回滚；如需回滚请手动编写反向 SQL

tcb db execute​

参数​

示例​

tcb db pg migration​

目录结构与命名约定​

全局约定​

tcb db pg migration new​

参数​

示例​

tcb db pg migration list​

参数​

示例​

tcb db pg migration fetch​

参数​

示例​

tcb db pg migration up​

参数​

示例​

tcb db pg migration repair​

参数​

Name 自动推断​

示例​

典型工作流​

声明式部署（database 字段）​