关系型数据库（PostgreSQL）
tcb db 命令集合提供对 CloudBase PostgreSQL 环境的 SQL 执行与 migration 变更管理能力。
tcb db execute：直接执行任意 SQL 语句（DDL / DML / DQL）。tcb db pg migration <subcommand>：以文件形式管理 PostgreSQL schema 变更，支持创建、预览、执行、拉取、修复历史等操作。
tcb db execute
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>.sqlversion：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>